Entity

An entity in Drupal is a single item of content or configuration, such as one page, user, taxonomy term or content type, handled through one common API.

Learn DrupalDrupal glossary
Edited by Founder and CEO, DXPR Last updated

An entity is one item of data that Drupal manages as an object: a page, a user account, a taxonomy term, a file, or a content type. The Drupal user guide defines it as an item of either content or configuration data, although in everyday use the word usually means a content entity. All entities share one API for loading, saving and deleting them.

How entities work in Drupal 11

Each entity is an object whose class implements EntityInterface. That interface gives every entity the same basic methods: id(), uuid(), label(), bundle(), save(), delete() and toUrl().

Core has two families of entities:

  • Content entities hold content data, such as pages, user accounts and taxonomy terms. They consist of base fields and configurable fields, they can have revisions and translations, and each type has its own database table. The base class is ContentEntityBase.
  • Configuration entities hold site setup, such as content types and vocabularies, and they are stored in the shared config table. The base class is ConfigEntityBase.

Entities are grouped into entity types: content items (node), taxonomy terms, users, comments, files and content blocks, among others. Most types are divided into bundles. For nodes the bundles are content types; for taxonomy terms they are vocabularies. The user guide calls these subtypes.

A storage handler does the loading and saving for each type. Content entities use SqlContentEntityStorage by default, and configuration entities use ConfigEntityStorage.

An entity type, its bundles and their fieldsThe node entity type, called Content in the admin, has base fields that every bundle shares, such as Title, Authored by, Published and Authored on. Its bundles are content types: Article adds the fields Body, Image, Tags and Comments, and Basic page adds Body. Each saved article or basic page is one entity with its own values. Users, taxonomy terms, comments and files are other entity types.Entity type: node (Content)Base fields every bundle shares, such as:Title, Authored by, Published, Authored onbundles (content types)Bundle: ArticleMachine name: articleFields: Body, Image, Tags, CommentsBundle: Basic pageMachine name: pageFields: Bodyeach saved item is an entityEntity: one saved articleIts own values for those fieldsEntity: one saved basic pageIts own values for those fieldsUsers, taxonomy terms, comments and files are other entity types.
The node entity type has bundles such as Article and Basic page; each bundle adds its own fields, and each saved item is an entity.

Example

A developer who wants to read a node asks the entity type manager for the node storage, then loads it by ID. In a class where the manager is injected, it looks like this:

$storage = $entityTypeManager->getStorage('node');
        $node = $storage->load(1);
        $title = $node->label();

On the site, that node is reached at /node/1. The same load(), loadMultiple() and create() methods exist on the storage of every entity type, which is why custom code for terms or users looks much like custom code for nodes. A newly created entity is not saved until you call save().

Common mistakes

  • Treating "entity" as a synonym for "node". Nodes are one entity type among several. A request to "add a field to the entity" is incomplete until you name the entity type and the bundle.
  • Mixing up the two families. Content entities and configuration entities are stored and moved differently. Content stays on each site; configuration can be exported and imported.
  • Querying the database tables directly. The storage handler is the documented way to load, save and delete entities, so use it instead of writing SQL against the entity tables.
  • Forgetting to save. The create() method builds an entity object without permanently saving it.

For marketing and content teams

When developers say "entity", they usually mean one item you edit in the admin interface: a content item, a tag, a user or an uploaded file. You will hear the word most when you ask for something new, because the question becomes which entity type and which bundle should carry it. A new landing page type is a new bundle of the content item type. A new list of categories is a new vocabulary, and each category in it is a taxonomy term entity.

Sources

Questions about Entity

A node is one kind of entity: the entity type behind content items such as articles and basic pages. Users, taxonomy terms, files and comments are other entity types. Every node is an entity, but not every entity is a node.

A content entity holds data for visitors, such as a node or a taxonomy term. It is built from fields and can have revisions and translations. A configuration entity, such as a content type, stores site setup and lives with the rest of the site's configuration.

A bundle is a variant of an entity type. For the node entity type, the bundles are the content types, such as article and page. Each bundle can have its own set of fields.

They ask the entity type manager for the storage handler of an entity type, then call a method such as load() or loadMultiple() on it. The storage handler loads, saves and deletes entities of that type.

Related terms

All Drupal terms from A to Z