A Simple Entity Data API for Module Builders
Entity Data is a handy little API to make module builder's lives easier. If you need to build a module that adds functionality and data to an entity, no longer will you have to implement your own CRUD and export/import support.
A module builders dilemma
Fields are a powerful way to add data to Drupal entities. However, sometimes fields can be rather cumbersome. Particularly when you want to add something and thus attach fields to entities that already exists.
The alternative is to roll your own. Just use a hook alter to add UI for your data to the entity edit form using regular form API fields. Then on submit, save the data to a custom table created by the module.
This approach was the primary way of adding functionality to nodes and other entities prior to Drupal 7, before fields were in core. This technique is still utilized quite often in Drupal 7.
Each module that needs to manage entity data without fields has to implement a common pattern for properly storing data:
- Provide a schema to create a new table to store the custom data.
- Implement CRUD functions for saving, loading and deleting data, including deleting records when the entity is deleted.
- Make sure the data exports and imports with the entity
A module builders dream
OK, maybe the header is a bit of hyperbole, but on recent projects were we were having to add data to nodes and various custom entities, Entity Data really made our lives a lot easier.
We created the Entity Data module to centralize the functionality in the common pattern above into a simple to use API.
The primary functions for interacting with Entity Data are:
entity_data_set($entity_type, $entity_id, $name, $value, $revision_id = 0, $language = LANGUAGE_NONE);
entity_data_get($entity_type, $entity_id, $name, $default = NULL, $revision_id = 0, $language = LANGUAGE_NONE);
entity_data_del($entity_type, $entity_id, $name, $revision_id = 0, $language = LANGUAGE_NONE);
They work pretty much the same way as Drupal's handy variable_get, variable_set, and variable_del. Except instead of storing data in a global context, the data is associated with an entity. And rather importantly, data is loaded only when the entity is loaded, not globally like core's variable_* methods.
In addition to using the getter/setter functions, data is auto-loaded and saved with the entity. Any data that has been saved to an entity will be automatically loaded into the entity_data property and can be accessed using:
$entity->entity_data[$name]
Additionally any data added to the entity_data property will automatically be saved on entity_insert or entity_update.
This also means that entity_data is automatically exported with the entity and will be maintained on import.
So next time you have to write a module to extend entities, save yourself some time and code by letting Entity Data handle your CRUD.
Have questions or comments about Entity Data? Leave them in the comments below and we'll answer ASAP!
