May 21, 2012

Anatomy of a Drupal Entity

On a recent project in which we had to create a number of different entities, I started a list of functions / classes / etc. that are required when creating an entity in Drupal 7. Rather than remembering to move it around to each project, I think it makes more sense to post it here instead

This is by no means a definitive, complete document on how the various pieces of functionality work to produce an entity, so please leave any comments / questions that you have and I'll update the content accordingly.

Also, this is not intended (yet?) as a tutorial on how to make a module from scratch or how to write each of the functions described, but rather a shopping list of all the functions you should include in your entity.

Module dependencies

Entity API
This is a big one, it offers up bunch of services and functions that the Drupal core entity API does not (such as CRUD operations).


If you're creating an entity module (in this case, my_entity), you'll need at a minimum, the following functions in your my_entity.module file:


  • hook_help
    • While not specific to entity modules, this one's good to have in general and I don't see it often enough so I'm listing it here
  • hook_entity_info
    • Defines your my_entity and my_entity_type entities
  • hook_entity_info_alter
    • Provides any default bundle types
  • hook_permission
    • Defines permissions for entity / entity type administration, and view / edit / delete permissions for individual content types (think of the Content permissions section for a good idea of what to put here
  • my_entity_access / my_entity_type
    • Referenced in hook_entity_info, this checks if a user has access to perform the given operation on the entity or entity_type
  • hook_theme
    • Themes the "add content type" page of entity types to add, and the entity itself
  • hook_menu_local_tasks_alter
    • Adds the "Add" action link on the 'admin/content/my_entity' page of existing content
  • my_entity_get_types
    • Gets an array of all types (bundles) for the entity
  • my_entity_type_load
    • Gets a my_entity_type object
  • my_entity_load
    • Loads an entity, should call my_entity_load_multiple
  • my_entity_load_multiple
    • Loads multiple entities into an array, calls entity_load
  • my_entity_create
    • Creates an entity, wraps the entity controller's create() function
  • my_entity_uri
    • Provides a URI for an entity (like 'node/nid' for nodes)
  • my_entity_page_title
    • Gives the page title for a specific entity
  • my_entity_page_view
    • Renders the entity as a page


class MyEntity extends Entity
  This is the class that will represent your entity objects and is named in hook\_entity\_info().
  The constructor of this class should augment the passed values with any required defaults.
  In addition, you should override the following methods for this class:

	defaultLabel() Default label for this entity
    defaultUri() Default URI for the entity

class EntityType extends Entity
  Makes $type and $label public variables


  • my_entity_form_wrapper
  • Wrapper around drupal_get_form for the add / edit entity form
  • Sets the breadcrumb of the form page
  • my_entity_delete_form_wrapper
  • Wrapper around the 'delete entity' form
  • my_entity_edit_form
  • Form for adding / editing a new entity. Make sure to attach the UI-driven fields to the to form in this step
  • my_entity_edit_form_validate
  • Validates the add / edit form submission
  • my_entity_edit_form_submit
  • Adds any entity-specific info (such as creation time, etc.), then saves the entity and redirects to the content list
  • my_entity_form_submit_delete
  • Redirects user to the delete form
  • my_entity_delete_form
  • Delete form for an entity
  • my_entity_delete_form_submit
  • Deletes an entity and redirects the user to the content list
  • my_entity_add_page
  • Takes the user to the add-entity page, which lists the available bundles
  • Wraps the UI Controller's addPage method
  • theme_my_entity_add_list
  • Themes the list of available entity types for entity creation
  • my_entity_set_breadcrumb
  • Sets the breadcrumb for administrative entity pages


class EntityUIController extends EntityDefaultUIController
  UI Controller for the entities. Recommended functions to override in this module:

    Actually called hook_menu() and not a Drupal hook, this function adds menu items for the entity list, add, add/type, view, edit, and delete pages
    Markup for the add overview page which displays the list of content types


  • my_entity_type_form
  • Entity type (bundle) adding / editing form
  • my_entity_type_form_submit
  • Saves the entity, and redirects it to the admin/structury/entity_type page
  • my_entity_type_form_submit_delete
  • Processes the delete button on the entity_type_form
    Redirects to the delete page for the entity type


class EntityTypeUIController extends EntityDefaultUIController
  UI Controller for the entity types. Recommended functions to override in this module:
    Actually called hook_menu(), this function adds menu items for the entity list, add, add/type, view, edit, and delete pages