Bundle

A bundle is a variant of an entity type that has its own set of fields. The node entity type has content types as bundles, such as Article and Basic page; taxonomy terms have vocabularies. The Drupal user guide uses the term entity subtype for the same idea. Some entity types, such as the user, have no bundles.

How bundles work in Drupal 11

An entity type that has bundles names a bundle key. For nodes it is type. The entity type definition links both sides: the node definition sets bundle_entity_type to node_type, and the node_type definition sets bundle_of to node. In code, EntityTypeInterface exposes this through getBundleEntityType() and getBundleOf().

Drupal.org says a bundle is typically a configuration entity that stores what differs between the content entities of a type. The base class is ConfigEntityBundleBase. It refuses to save a changed bundle ID and throws a ConfigNameException. When a bundle is deleted, it also deletes the bundle's view and form display configuration. A bundle name can have at most 32 characters.

The reason bundles matter is fields. Per the user guide, administrators add fields to a subtype, and all entities of that subtype share them. A Vendor content type can have a logo that a Basic page does not.

Example

When a developer creates a node, the bundle goes in as the type value, and bundle() returns it later:

$node = $storage->create(['type' => 'article', 'title' => 'Sample title']);
        $node->bundle(); // 'article'

Here node is the entity type and article is the bundle. In the admin interface the same split appears as content type (Structure › Content types), vocabulary or block type.

Common mistakes

• Mixing up the entity type and the bundle. A request to "add a field to nodes" is incomplete until it names a bundle, because administrators add fields per subtype.
• Trying to rename a bundle. Core blocks changing a saved bundle ID. Choose the machine name carefully before the first save.

For marketing and content teams

The user guide notes that the word bundle shows up especially in programmer documentation. In the admin interface it surfaces as "content type", "vocabulary" or "block type", depending on what is being structured. When a developer asks which bundle a request is for, the answer is the name of the content type, vocabulary or block type that should get the new field.

Sources

• Drupal.org: Bundles
• Drupal.org: Introduction to the Entity API in Drupal
• Drupal User Guide: Glossary
• Drupal User Guide: Concept: Content entities and fields
• ConfigEntityBundleBase class, Drupal core 11.x
• EntityTypeInterface, Drupal API
• EntityTypeInterface source, Drupal core 11.x
• EntityInterface, Drupal API
• BlockContent entity class, Drupal API
• Drupal.org change record: Introducing bundle classes
• Entity hooks, Drupal core 11.x