Entity CRUD, editing, and view hooks

Hooks used in various entity operations.

Entity create, read, update, and delete (CRUD) operations are performed by entity storage classes; see the Entity API topic for more information. Most entities use or extend the default classes: \Drupal\Core\Entity\Sql\SqlContentEntityStorage for content entities, and \Drupal\Core\Config\Entity\ConfigEntityStorage for configuration entities. For these entities, there is a set of hooks that is invoked for each CRUD operation, which module developers can implement to affect these operations; these hooks are actually invoked from methods on \Drupal\Core\Entity\EntityStorageBase.

For content entities, viewing and rendering are handled by a view builder class; see the Entity API topic for more information. Most view builders extend or use the default class \Drupal\Core\Entity\EntityViewBuilder.

Entity editing (including adding new entities) is handled by entity form classes; see the Entity API topic for more information. Most entity editing forms extend base classes \Drupal\Core\Entity\EntityForm or \Drupal\Core\Entity\ContentEntityForm. Note that many other operations, such as confirming deletion of entities, also use entity form classes.

This topic lists all of the entity CRUD and view operations, and the hooks and other operations that are invoked (in order) for each operation. Some notes:

• Whenever an entity hook is invoked, there is both a type-specific entity hook, and a generic entity hook. For instance, during a create operation on a node, first hook_node_create() and then hook_entity_create() would be invoked.
• The entity-type-specific hooks are represented in the list below as hook_ENTITY_TYPE_... (hook_ENTITY_TYPE_create() in this example). To implement one of these hooks for an entity whose machine name is "foo", define a function called mymodule_foo_create(), for instance. Also note that the entity or array of entities that are passed into a specific-type hook are of the specific entity class, not the generic Entity class, so in your implementation, you can make the $entity argument something like $node and give it a specific type hint (which should normally be to the specific interface, such as \Drupal\Node\NodeInterface for nodes).
• $storage in the code examples is assumed to be an entity storage class. See the Entity API topic for information on how to instantiate the correct storage class for an entity type.
• $view_builder in the code examples is assumed to be an entity view builder class. See the Entity API topic for information on how to instantiate the correct view builder class for an entity type.
• During many operations, static methods are called on the entity class, which implements \Drupal\Entity\EntityInterface.

Create operations

To create an entity:

$entity = $storage->create();

// Add code here to set properties on the entity.

// Until you call save(), the entity is just in memory.
$entity->save();

There is also a shortcut method on entity classes, which creates an entity with an array of provided property values: \Drupal\Core\Entity::create().

Hooks invoked during the create operation:

• hook_ENTITY_TYPE_create()
• hook_entity_create()

See Save operations below for the save portion of the operation.

Read/Load operations

To load (read) a single entity:

$entity = $storage->load($id);

To load multiple entities:

$entities = $storage->loadMultiple($ids);

Since load() calls loadMultiple(), these are really the same operation. Here is the order of hooks and other operations that take place during entity loading:

• Entity is loaded from storage.
• postLoad() is called on the entity class, passing in all of the loaded entities.
• hook_entity_load()
• hook_ENTITY_TYPE_load()

When an entity is loaded, normally the default entity revision is loaded. It is also possible to load a different revision, for entities that support revisions, with this code:

$entity = $storage->loadRevision($revision_id);

This involves the same hooks and operations as regular entity loading.

Save operations

To update an existing entity, you will need to load it, change properties, and then save; as described above, when creating a new entity, you will also need to save it. Here is the order of hooks and other events that happen during an entity save:

• preSave() is called on the entity object, and field objects.
• hook_ENTITY_TYPE_presave()
• hook_entity_presave()
• Entity is saved to storage.
• For updates on content entities, if there is a translation added that was not previously present:
  • hook_ENTITY_TYPE_translation_insert()
  • hook_entity_translation_insert()
• For updates on content entities, if there was a translation removed:
  • hook_ENTITY_TYPE_translation_delete()
  • hook_entity_translation_delete()
• postSave() is called on the entity object.
• hook_ENTITY_TYPE_insert() (new) or hook_ENTITY_TYPE_update() (update)
• hook_entity_insert() (new) or hook_entity_update() (update)

Some specific entity types invoke hooks during preSave() or postSave() operations. Examples:

• Field configuration preSave(): hook_field_storage_config_update_forbid()
• Node postSave(): hook_node_access_records() and hook_node_access_records_alter()
• Config entities that are acting as entity bundles in postSave(): hook_entity_bundle_create()
• Comment: hook_comment_publish() and hook_comment_unpublish() as appropriate.

Editing operations

When an entity's add/edit form is used to add or edit an entity, there are several hooks that are invoked:

• hook_entity_prepare_form()
• hook_ENTITY_TYPE_prepare_form()
• hook_entity_form_display_alter() (for content entities only)

Delete operations

To delete one or more entities, load them and then delete them:

$entities = $storage->loadMultiple($ids);
$storage->delete($entities);

During the delete operation, the following hooks and other events happen:

• preDelete() is called on the entity class.
• hook_ENTITY_TYPE_predelete()
• hook_entity_predelete()
• Entity and field information is removed from storage.
• postDelete() is called on the entity class.
• hook_ENTITY_TYPE_delete()
• hook_entity_delete()

Some specific entity types invoke hooks during the delete process. Examples:

• Entity bundle postDelete(): hook_entity_bundle_delete()

Individual revisions of an entity can also be deleted:

$storage->deleteRevision($revision_id);

This operation invokes the following operations and hooks:

• Revision is loaded (see Read/Load operations above).
• Revision and field information is removed from the database.
• hook_ENTITY_TYPE_revision_delete()
• hook_entity_revision_delete()

View/render operations

To make a render array for a loaded entity:

// You can omit the language ID if the default language is being used.
$build = $view_builder->view($entity, 'view_mode_name', $language->getId());

You can also use the viewMultiple() method to view multiple entities.

Hooks invoked during the operation of building a render array:

• hook_entity_view_mode_alter()
• hook_ENTITY_TYPE_build_defaults_alter()
• hook_entity_build_defaults_alter()

View builders for some types override these hooks, notably:

• The Tour view builder does not invoke any hooks.
• The Block view builder invokes hook_block_view_alter() and hook_block_view_BASE_BLOCK_ID_alter(). Note that in other view builders, the view alter hooks are run later in the process.

During the rendering operation, the default entity viewer runs the following hooks and operations in the pre-render step:

• hook_entity_view_display_alter()
• hook_entity_prepare_view()
• Entity fields are loaded, and render arrays are built for them using their formatters.
• hook_entity_display_build_alter()
• hook_ENTITY_TYPE_view()
• hook_entity_view()
• hook_ENTITY_TYPE_view_alter()
• hook_entity_view_alter()

Some specific builders have specific hooks:

• The Node view builder invokes hook_node_links_alter().
• The Comment view builder invokes hook_comment_links_alter().

After this point in rendering, the theme system takes over. See the Theme system and render API topic for more information.

Other entity hooks

Some types of entities invoke hooks for specific operations:

• Searching nodes:
  • hook_ranking()
  • Query is executed to find matching nodes
  • Resulting node is loaded
  • Node render array is built
  • comment_node_update_index() is called (this adds "N comments" text)
  • hook_node_search_result()
• Search indexing nodes:
  • Node is loaded
  • Node render array is built
  • hook_node_update_index()

File

core/lib/Drupal/Core/Entity/entity.api.php, line 16

Hooks and documentation related to entities.

Functions