Understanding the Entity API Module

Feb 21, 2012 · by Logan Smyth

Entities in Drupal 7 simplify and centralize common logic that, in earlier versions of Drupal, was duplicated in several places, or only usable in specific modules. There are, however, many features (such as saving entities!) that did not make it into Drupal 7. The Entity API module fills in these missing gaps in the core and goes a step farther by simplifying definition of new entity types, and integration with contrib modules such as Views, Rules, and Features.

Generalized API

Core provides standardized entity loading using entity_load. There are however no functions to save, view, or delete entities! The Entity module defines entity_save, entity_view, and entity_delete functions. These new functions provide the other operations that are critical when code needs to work generally for multiple entity types. Normally you have to implement your own logic for saving an entity, and hope that you are properly invoking all the right hooks, but now you don’t have to worry about writing that yourself.

Clean Object-Oriented Design

All Drupal core entities are stdClass objects. The Entity API defines an Entity class which encapsulates the entity's properties (such as its type) into one object, and wraps many of the entity operation functions such as entity_save(), entity_label(), entity_uri(), entity_i18n_string(), etc. into methods. For example, instead of writing entity_save($entity_type, $obj), you can just write $obj->save(). You can of course extend this class when defining your own entities, which is what we’ve often chosen to do.

Another general upside to using classes in Drupal 7 is that files containing classes can be automatically loaded when they are needed, so any complex logic that you might need for your class will only need to be loaded on pages where the entity is actually used. This can be a plus for performance since it decreases the amount of code loaded on each page.

Automatic CRUD UI

No one likes building complex menu structures. Thankfully, the Entity module simplifies creation of standard UIs for managing entities. All you have to do is give it a base path for the interface and define the edit form, and from there the module can create add, edit and listing pages automatically, so you don’t have to.

Views and Rules integration

Integrating with other modules can be complicated, so the Entity module includes automatic integration with several modules, including Views and Rules. It will automatically give Views data about the structure of your entity by using the database schema or the entity properties. Similarly, because the loading and saving is done via the Entity module, it can automatically trigger events in the Rules module.

Exporting and Features integration

Exporting objects and configuration into code is a huge plus for both site deployment, and change tracking. The Entity module provides functions to export entities to JSON, and cleanly integrates with Features. To export a custom entity type, all that you need to do is use a specific entity controller, and define required exportable fields such as 'machine name' and ‘status’.

Standardized definition of properties

The same data that is used to provide integration with Views is available for any module to use. The Entity module provides the hooks hook_entity_property_info(_alter) ( see also ) for defining information about an entity type's properties. This property information includes the name along with metadata like data type, label and description, and if the value is required or needs to be sanitized.

This property data can be automatically generated by inspecting the entity's database table, or you can manually specify properties using hook_entity_property_info for more advanced behavior. Along with integration with Views, this data can then be used to automatically sanitize string data, or format numbers, or reference other tables.


Building on the Entity module's property definitions, you can specify validation callback functions to validate data for properties. Heavy reliance on the Form API validation in core and contrib means that it is often very hard to validate an entity programmatically and the only real option is to re-execute the form behind the scenes. By having metadata about properties easily available, the values can be validated properly without having to work through the Form API at all.


I hope this has motivated you a bit to take a look at the Entity module. Usage of the module is growing daily and you may already have it installed as a dependency for a contrib module. Several high-profile contrib modules, such as Organic Groups, Commerce, Rules, Search API and Field Collection, have the Entity module as a dependency and there are more all the time.

Featured Articles