Problem/Motivation

The entity system fires many hooks when an entity is created or updated:

- hook_entity_insert/update/pre_save
- hook_ENTITYTYPE_insert/update/pre_save

The documentation for some of these is unclear about the precise order in which they are invoked, the status of the entity at that point (ie, has it been saved yet? does it have an ID yet?), and what it's legitimate to do at that point (may the entity be altered?)

Proposed resolution

Add a new documentation topic for entity hooks. This should:

- give the order in which hooks are fired for basic entity operations such as insert, update, and delete
- mention there are both the common entity hooks and the specific entity type hooks

The documentation for all these hooks should be added to this topic.

Original report by joachim

API page: https://api.drupal.org/api/drupal/modules!system!system.api.php/function...

hook_entity_insert() is invoked just after an entity has been saved for the first time. This means it will have an ID.

The docs could also do to point the reader at hook_entity_presave(), in case that is better suited to what they're looking for.

Comments

jhodgdon’s picture

Version: 8.x-dev » 7.x-dev
Issue tags: -Needs backport to D7

In 8.x the docs do say "This hook runs once the entity has been stored. Note that hook implementations may not alter the stored entity data.". That actually seems pretty clear to me.

Let's just make this a 7.x issue, where the docs are less clear, unless you think a @see to other entity hooks is necessary in 8.x... the better way to take care of that would probably be a group/topic page explaining all of the entity save/delete/etc. hooks, if so?

joachim’s picture

> the better way to take care of that would probably be a group/topic page explaining all of the entity save/delete/etc. hooks, if so?

An overview of entity hooks and the order they fire in would be very nice, yes!

jhodgdon’s picture

Feel free to update the title/summary and move this back to D8 then if you want.

joachim’s picture

Title: hook_entity_insert() doesn't give details about precisely when it is invoked » add documentation topic on entity hooks
Version: 7.x-dev » 8.x-dev
Issue summary: View changes
Issue tags: +Needs backport to D7

Done!

jhodgdon’s picture

Status: Active » Closed (duplicate)