Creating your own entities with Entity API

There have been plenty of articles about Drupal 7 and entities already. Entities are great. They provide a unified way to work with different data units in Drupal. Drupal 7 is all about entities. They are everywhere: nodes, users, taxonomy terms, vocabularies...

But how, as developers, can we create our own entities? When do we really need to do that? I think these questions are really very project-specific. We can probably use nodes for nearly everything. But when it comes to performance-sensitive projects, nodes should really only be used for content, and we should separate as much as possible from nodes. Why? Nodes are revisioned, they fire a lot of hooks, and they have functionality that we likely won't need. Also if we know exactly what fields we should have in our entities, we can create our own custom entities to avoid all those joins of Field API tables.

There are plenty of examples in Drupal core of how to create entities. To create entities, you should really write a lot of code. But there is also, of course, a faster way. You can use Entity API to simplify the code structure. With Entity API we can really move a lot of code to Entity Controller using standard Entity API functions and, in this way, keep our main module clean and nice.

Entity API provides:

• More functions to work with entities. Drupal core provides functions to work with entities: entity_load(), entity_label(), entity_extract_ids(), entity_uri(), entity_get_info(). Core doesn't have any functions to save or delete entities, but this is where Entity API helps us. It provides: entity_id(), entity_export(), entity_import(), entity_save(), entity_create(), entity_delete(), entity_view(), entity_access(), entity_get_property_info(). This allows us to move more logic for all operations to the Controller Class (we will talk about this bit later).
• Administration UI for exportable entities. This is a really great feature that allows us to create UIs for exportable entities easily. This is needed when we have bundles as entities. The administrative interface is very similar to the content types overview page for nodes.
• Metadata wrappers. This allows us nicely get/set values of properties and fields of entities. Also we can get/set data of related entities... like geting the value of a profile field for the author of the node. No more LANGUAGE_NONE everywhere in the code!
• Integration with Views and Rules. Integration with Rules is done by default when we use the Entity API Controller class, so we can hook in during creating/editing/deleting entities. By default Views can create a view using properties of our Entities, but they are very generic. After we describe the properties to Entity API (this is also needed for wrappers), Views will understand much more. Then we will be able to build different kinds of relationships, exposed filters, etc.
• Provide entity tokens (entity_token module).

Administration UI screenshot

Every entity has its own Controller. This class is responsible for all operations on this particular entity (create, edit, delete, view, etc). This is very convenient as it can be easily reused by our custom entities, thanks to inheritance. It's also worth mentioning that with Entity API, our entities are "first class" objects and not objects of stdClass.

Lets take a look at a practical implementation of an entity to sample the functionality.

Practical example

Our case is quite abstract: we create two entities, example_task and example_task_type. Task has the properties: uid (author of the task), type, created, changed, title, and description. Task type is simply information about bundles of the task, so it has the fields: id, type, label, and description. Other fields of the Task type are added by Entity API to make this entity exportable (module and status properties).

First of all, (as in case with using only core functionality) in order to implement custom entities we should describe their base tables in hook_schema(). I will avoid listing of all that code here.

Then we should implement hook_entity_info() to declare our entities:

I won't describe every option in hook_entity_info() here as there is a lot of documentation and articles about it already (see the list of references in the bottom of this article).

What is specific to Entity API:

• we define 'entity class'. It is self explanatory.
• 'label callback' => 'entity_class_label'. This is a standard Entity API label callback that takes a look at our entity class method defaultLabel()
• 'uri callback' => 'entity_class_uri'. This is also a standard Entity API callback for uri. It executes our entity defaultUri() method
• 'exportable' key for example_task_type. In our example we set task types to be exportable.
• 'admin ui' for example_task_type. This is where we define our Administration UI for task types.

The next step in our implementation is to let Drupal understand that entities of example_task_type are bundles for example_task. This should be done in following way:

<?php
/**
* Implements hook_entity_info_alter().
*/
function example_task_entity_info_alter(&$entity_info) {
  foreach (example_task_types() as $type => $info) {
    $entity_info['example_task']['bundles'][$type] = array(
      'label' => $info->label,
      'admin' => array(
        'path' => 'admin/structure/task-types/manage/%example_task_type',
        'real path' => 'admin/structure/task-types/manage/' . $type,
        'bundle argument' => 4,
      ),
    );
  }
}
?>

Next we should take care about pages where we add, view, and edit our example tasks. To do this we define various items in hook_menu():

Of note in the hook_menu() implementation is that we use entity_access for most of the access callbacks. The purpose of this function is to check for an access callback defined by the entity ('access callback' property) and execute it. So our access callback for tasks looks like this:

And of course our hook_permissions() for defining our permissions

Now let's take a look at the most interesting part – controllers. The Task entity class looks like this:

We only define our label for the entity and what path it should have.

Now Controller class:

Please pay attention to the fact that we inherit our Controller class from EntityAPIController class that is provided by Entity API.

The create() method is responsible for the default values of entity properties when creating a new object. It is imperative that our entity has values when saving the object. In order to create an 'empty' entity we use the entity_create function.

buildContent() is needed for us to have our Description field displayed on the view page for the entity. We show this field using a theming function from the Field API, so the behaviour will be the same as other fields added with fields. Also you can see usage of a wrapper here, but lets come back to it a bit later.

Controller and entity class for example task type look different:

Please pay attention to the fact that we inherit our Controller class from EntityAPIControllerExportable class that is provided by Entity API. This is needed to make our entity exportable.

For entity class we define the method isLocked(). This is needed to understand whether this entity is locked so it is not possible to edit/delete it.

In the Controller class we also define the create() method for an empty entity and in the save() method we should call field_attach_create_bundle() to let Fields API know that a new bundle is created. Of course, we also rebuild the menu to refresh our newly created bundle admin paths.

Now we need to define our forms for saving/deleting entities. You can find them in attached module. There is nothing non standard compared to not using Entity API there so let's skip this part (there is plenty of code there as well).

Instead lets take a closer look at usage of other standard Entity API functions in our module.

What we are missing is an API to work with our entities. Here it is:

As you can see, these are simply wrappers around Entity API functions. This is a great benefit of using Entity API as we make our API very simple and transparent.

The same applies for our Task type entity:

I hope now you start to have a feeling how convenient it is to use standard Entity API functions to build your own entities.

Now let's take a look at metadata wrappers which simplify getting and setting values of entity properties/fields. E.g.

The entity definition informs meta data wrappers about the raw data structure(base table definition), but this doesn't describe the context of a field's use. For example, the 'uid' field from our task entity is a simple integer and Drupal doesn't know that it is a reference to a user object. In order to create this link we use following code:

<?php
/**
* Implements hook_entity_property_info_alter().
*/
function example_task_entity_property_info_alter(&$info) {
  $properties = &$info['example_task']['properties'];
  $properties['created'] = array(
    'label' => t("Date created"),
    'type' => 'date',
    'description' => t("The date the node was posted."),
    'setter callback' => 'entity_property_verbatim_set',
    'setter permission' => 'administer nodes',
    'schema field' => 'created',
  );
  $properties['changed'] = array(
    'label' => t("Date changed"),
    'type' => 'date',
    'schema field' => 'changed',
    'description' => t("The date the node was most recently updated."),
  );
  $properties['uid'] = array(
    'label' => t("Author"),
    'type' => 'user',
    'description' => t("The author of the task."),
    'setter callback' => 'entity_property_verbatim_set',
    'setter permission' => 'administer example_task entities',
    'required' => TRUE,
    'schema field' => 'uid',
  );
}
?>

We also define 'date' type for our 'created' and 'changed' fields. Now we can use the following way to retrieve the name of our entity author:

<?php
$wrapper = entity_metadata_wrapper('example_task', $entity);
$wrapper->uid->name->value(array('sanitize' => TRUE));
?>

We can also build views relationship to our entity author. See the screenshot below.

Revisions

At the moment entity revisions are not supported by Entity API. There are steps being made to include this functionality in issue http://drupal.org/node/996696, so your help to move this issue forward is very welcome.

Other examples and documentation

I hope it has become clearer how to simplify creating entities using Entity API. There are a lot of modules that leverage the EntityAPI already like Profile2 and DrupalCommerce.

I would like to thank Wolfgang Ziegler (fago) a lot for this great module and all his work.

References to great resources about Entities and Entity API module: