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
Comment #1
jhodgdonIn 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?
Comment #2
joachim commented> 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!
Comment #3
jhodgdonFeel free to update the title/summary and move this back to D8 then if you want.
Comment #4
joachim commentedDone!
Comment #5
jhodgdonThis is being taken care of on #2216535: Replace Node overview topic and Node API topic with Entity Hooks topic