Warning message

Documentation is currently being migrated into the new system. Some pages might be temporarily missing, and some guides might appear empty. Thank you for your patience while we are improving Drupal.org documentation.

An Introduction to Entities

Last updated on
October 14, 2016 - 21:22

If you are looking for the documentation or the entity API in Drupal 8, click here.

Maybe you've heard of "entities" in Drupal 7, wondered what they were, and wanted to learn the underlying concepts. Leveraging the Entity API lets you create more lightweight and flexible solutions.

The Drupal community often compares site building through configuration to a favorite childhood toy: LEGO bricks. We can build Entity types, which can make Bundles, to which we can add Fields and then create Entities. This article explains the relationships between Entity types > Bundles > Fields > Entities. This was one of the most important changes of Drupal 7, and brought components from some well-loved contributed modules -- such as CCK -- into the core system.

The illustration below shows some examples of Entity types included with Drupal 7, with some example entities:

entity types and some entities

Let’s take a closer look at these concepts. It’s sort of a chicken-and-egg thing, one doesn’t exist without the other.

Entity types

In earlier versions of Drupal, the field system was only used on content types. Now, thanks to the Entity API, we can add fields to other things, like comments. Fieldable entities make Drupal eminently flexible. An entity type is a useful abstraction to group together fields. Below are the Entity types in Drupal core:

  • Nodes (content)
  • Comments
  • Files
  • Taxonomy terms
  • Taxonomy vocabularies
  • Users

You can also build new kinds of entity types where the options above don't suit your needs. For more information, read further about using the hook_entity_info and extension by Entity API: entity_crud_hook_entity_info.


Bundles are an implementation of an entity type to which fields can be attached. You can consider bundles as subtypes of an entity type. With content nodes (an entity type), for example, you can generate bundles (subtypes) like articles, blog posts, or products. Not all entity types have bundles, however. For example, users do not have separate bundles (subtypes). For the entity types that do allow bundles, you can create as many bundles (subtypes) as you want. Then, using the Field system, you can add different fields to each bundle. Examples include a file download field on Basic Pages and a subtitle field on Articles.


A field is a reusable piece of content. In technical terms, each field is a primitive data type, with custom validators and widgets for editing and formatters for display. You can read further for a developer's guide to using the Drupal 7 Fields API.

What's important to know as it relates to Entities is that Fields can be added to any of the bundles (or entity types) to help organize their data.

Say, for example, you create a content type with an unstructured text field and use HTML to structure parts of it, like a summary section, or prices. That would make it more difficult, then, to control how these were displayed, or to make connections between different types of related content.

This is where using fields is essential. You could create a summary field of type Long Text as well as price fields of type Decimal.


An entity would be one instance of a particular entity type such as a comment, taxonomy term or user profile or of a bundle such as a blog post, article or product.

You can use entity_load to load any entity. Note, however, that the core does not provide a save or delete function, but thanks to Entity API module the missing pieces are added (entity_create(), entity_save(), entity_delete(), entity_view() and entity_access()).

Putting this in Object-Oriented Design/Programming terms...

If you come from an OOD/P background and are trying to better understand what these key D7 concepts are, the following suggested mapping might help (albeit not strictly true from a purist’s perspective) :-

  • An entity type is a base class
  • A bundle is an extended class
  • A field is a class member, property, variable or field instance (depending on your naming preference)
  • An entity is an object or instance of a base or extended class

All these four OOD/P concepts are special in that they are serialisable (stored - e.g. to a database or file). Serialisation takes place via the Entity API.

So what’s the big deal?

If you’re familiar with Drupal 6 and new to Drupal 7, this will sound like great news. In Drupal 6 and before, users and comments didn't have the same power that nodes (content) had. They couldn't have translations, fields, versioning, and so on. It also meant that systems such as Views, which relied on controlling the selection and listing of fields didn’t work as well with comments and users. Some experimentation was done with modules that turned comments or users into nodes. However, this meant that all the additional information in the node object was added to comments.

Instead, the community created this abstraction based on what was common between these different models of entity types. In this way, the Entity API allows for more lightweight and flexible solutions. There are many entity-aware modules, and more being developed with Drupal 7, which make it easier to relate content together, and gain a more flexible architecture.

Entity API module

The project Entity API extends the entity API of Drupal core in order to provide a unified way to deal with entities and their properties. Additionally, it provides an entity CRUD controller, which helps in simplifying the creation of new entity types.

Learn more about using the Entity API in your projects.

View a slideshow by jdleonard on entities and the Entity API.

Learn by example on Understanding entity terminology.