Last updated December 1, 2015. Created on August 27, 2011.
Edited by prathK, Fiable.biz, tz_earl, VikrantR. Log in to edit this page.

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

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.

Fields

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.

Entity

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.
http://www.slideshare.net/jdleonard/entities-in-drupal-7-the-entity-api

Learn by example on Understanding entity terminology.

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.

Comments

Stomper’s picture

I've read that entities are best for non "documenty" things, whereas content types are better for content types.

If i was to have a piece of content called library, that was simply the name and street address of a library, would it be more suitable as an entity?

zeta ζ’s picture

Let’s consider some examples of entity types:

  • Nodes (content)

Content types are Entity types. Your library entity type could be like a basic page, with a name (title) and a free-form address in the body, or a more specific design with fields for each part of the address.

alex.designworks’s picture

content types are bundles
entity types are nodes, comments, users, taxonomy terms etc.

You would create a new entity type for something that is not a content, but needs to be fieldable.

ed523’s picture

Wouldn't user roles be a subtype of user?

sajalsoni’s picture

Nope, "user role" is a completely different "thingie" compared to "user" entity type. Since it'll store different "kind" of information compared to "user" entity type.

Although, sub-types of "user" entity are not allowed in the drupal core, if they were allowed, you could create following subtypes of "user" entity type.

- Moderater User
- Publisher User
- Manager User

etc.

So basically, you just inherit the properties of core "user" entity type! You could think if this something similar to creating new "user" kind of custom content types!

Sajal

rhfdc’s picture

I think your documentation needs to tell the end-user who is trying to optimize his installation (or has some modules that require Entity API) how to install it. Do I just stick it in sites/all/modules and let Drupal partake of it, or do I put it in drupal/modules?

nevets’s picture

Contributed modules go in sites/all/modules.

neerajsingh’s picture

Drupal always says 'NEVER HACK CORE..!!', so don't place anything out of your sites directory.
You should place all your contributed modules inside of 'sites/all/modules/*', and 'Entity API' module is not an exception hence this should also go here...

zendka’s picture

Taxonomy terms are entity types and vocabularies are bundles. That looks neat.
Now why would taxonomy vocabularies be entity types as well?

nevets’s picture

It allows you to add fields to a vocabulary. So for example you might add an image field or a synonym field

zendka’s picture

I think you're talking about vocabularies as taxonomy term bundles. That makes total sense: adding a synonym to a taxonomy term looks reasonable.
But adding a synonym to a vocabulary? This is like adding a synonym to a content type. I can't see the use.

sajalsoni’s picture

In fact, if you could look at it as a bigger picture, Vocabularies and Taxonomies are treated as a configuration entities, rather than just content entities, if I'm not wrong. And as with the other config entities, Vocabulary is fieldable too, so you could attach the more fields if needed.

Sajal