9.11.3. Hooks d’entité
Dans des articles précédents, nous avons déjà rencontré les hooks. Dans cet article, nous allons examiner de plus près les hooks qui vous aident à travailler avec les entités.
Dans cet article, vous pouvez lire en général ce que sont les hooks et pourquoi ils sont nécessaires :
http://drupalbook.org/drupal/92-what-hook-drupal-8
Nous utiliserons les hooks pour ajouter notre code personnalisé qui sera déclenché lors de certains événements liés aux entités : ajout, suppression, mise à jour.
Vous pouvez voir tous les hooks Drupal sur cette page :
https://api.drupal.org/api/drupal/core!core.api.php/group/hooks/8.2.x
Nous n'aborderons qu'une partie d'entre eux, ceux que l'on trouve le plus souvent dans les modules personnalisés pour travailler avec le contenu.
J'ai ajouté tout le code sur GitHub dans le module drupalbook_examples, vous pouvez télécharger ce module et l'ajouter à mon site :
https://github.com/levmyshkin/drupalbook8
hook_entity_presave()
/**
* Implémente hook_entity_presave().
*/
function drupalbook_examples_entity_presave(Drupal\Core\Entity\EntityInterface $entity) {
if ($entity->getEntityTypeId() == 'node' && $entity->getType() == 'article') {
$entity->title->value = $entity->title->value . 'by ' . date('d-m-Y');
}
}
Hook_entity_presave() est déclenché à chaque fois qu’une entité est sauvegardée.
Il n’est pas nécessaire d’appeler $entity->save() à l’intérieur du hook car l’objet entité sera modifié avant la sauvegarde. Dans cet exemple, nous ajoutons à titre de l’article la date actuelle à laquelle le nœud a été sauvegardé. Si nous mettons à jour l’article le lendemain, la nouvelle date sera ajoutée à nouveau. Si vous ne supprimez pas la date du titre avant la sauvegarde, le titre deviendra de plus en plus long à chaque nouvelle sauvegarde de l’article. La plupart du temps, nous vérifions la présence de certaines valeurs dans les champs de l’entité lors de la sauvegarde, ou vous pouvez envoyer un e-mail avec une notification du changement de l’article.
Notez que nous vérifions d’abord le type d’entité souhaité, car le code dans hook_entity_presave() fonctionne pour toutes les entités : contenu, blocs, commentaires, termes de taxonomie. Et nous vérifions aussi le bundle des nœuds dont nous avons besoin.
hook_entity_insert()
/**
* Implémente hook_entity_insert().
*/
function drupalbook_examples_entity_insert(Drupal\Core\Entity\EntityInterface $entity) {
if ($entity->getEntityTypeId() == 'node' && $entity->getType() == 'page') {
$node = Node::create([
'type' => 'article',
'title' => 'Nouvelle page créée : ' . $entity->title->value,
]);
$node->save();
}
}
Hook_entity_insert() est appelé lorsqu’une nouvelle entité est ajoutée. Par exemple, lors de la création d’une nouvelle page sur un site, un article sera créé. Et si vous avez les hooks précédents, alors la date sera ajoutée au titre de l’article créé.
Il convient de noter qu’il existe une différence entre les hooks hook_entity_insert() et hook_entity_presave(). Hook_entity_insert() est déclenché une seule fois lors de l’ajout d’une entité et ne modifie pas les valeurs des champs de l’entité. Autrement dit, si vous copiez le code du premier hook dans le second, ce code ne fonctionnera pas non plus :
/**
* Implémente hook_entity_insert().
*/
function drupalbook_examples_entity_insert(Drupal\Core\Entity\EntityInterface $entity) {
if ($entity->getEntityTypeId() == 'node' && $entity->getType() == 'article') {
$entity->title->value = $entity->title->value . 'by ' . date('d-m-Y');
}
}
Bien sûr, vous pouvez réussir à enregistrer la valeur du nœud :
function your_module_entity_insert(Drupal\Core\Entity\EntityInterface $entity){
if ($entity->getType() == 'article') {
drupal_register_shutdown_function('_your_module_post_insert', $entity);
}
}
function _your_module_entity_insert(Drupal\Core\Entity\EntityInterface $entity) {
if ($entity) {
$entity->save();
}
}
Mais ce n’est pas conseillé, il est préférable d’utiliser hook_entity_presave() pour modifier l’entité elle-même lors de la sauvegarde, et hook_entity_insert() pour modifier d’autres entités ou effectuer des actions.
hook_entity_update()
/**
* Implémente hook_entity_update().
*/
function drupalbook_examples_entity_update(Drupal\Core\Entity\EntityInterface $entity) {
if ($entity->getEntityTypeId() == 'node' && $entity->getType() == 'page') {
\Drupal::messenger()->addMessage('La page a été modifiée : ' . $entity->title->value);
}
}
Hook_entity_update() est déclenché chaque fois qu’une entité est mise à jour. Il faut préciser d’emblée qu’il ne faut pas modifier les champs de l’objet $entity ici, ce hook, comme hook_entity_insert(), sert à déclencher certaines actions qui ne sont pas liées aux données des champs de l’entité mise à jour. Ce hook doit être utilisé notamment pour le journalisation, l’envoi de messages ou d’autres actions.
De plus, ne faites pas appel à $entity->save() pour ne pas rappeler hook_entity_update(), mais si vous le faites, vous devez vous assurer que vous ne faites pas appel à $entity->save() en boucle.
hook_entity_delete()
Un autre hook pour la journalisation et l’exécution d’actions après la suppression d’entités.
hook_entity_access()
<?php
use Drupal\Core\Access\AccessResult;
...
/**
* Implémente hook_entity_access().
*/
function drupalbook_examples_entity_access(\Drupal\Core\Entity\EntityInterface $entity, $operation, \Drupal\Core\Session\AccountInterface $account) {
if ($entity->getEntityTypeId() == 'node' && $entity->getType() == 'article' && $operation == 'view' && in_array('administrator', $account->getRoles())) {
AccessResult::forbidden();
}
}
?>
Dans cet exemple, nous bloquons l’accès aux articles pour tous les utilisateurs qui n’ont pas le rôle administrateur. Bien sûr, si les permissions standard des rôles vous suffisent pour différencier l’accès au contenu, il est préférable d’utiliser les réglages de permissions. Hook_entity_access() est utile pour configurer de manière flexible l’accès au contenu, par exemple selon un planning, en respectant certaines conditions liées aux points utilisateur, karma, niveaux utilisateur, etc. De plus, si vous faites une restriction habituelle d’accès à certains contenus via ce hook, en réécrivant les droits d’accès standard, cela peut entraîner une confusion pour un autre développeur qui reprendra le projet. C’est là que réside le principal inconvénient des hooks, c’est le caractère non évident de l’exécution du code tiers. Si on suppose que l’on ignore l’existence d’un module avec des hooks implémentés, il sera mystérieux de comprendre pourquoi le titre de notre article change lors de sa sauvegarde. Bien sûr, nous savons que les hooks existent, et donc à chaque fois que vous rencontrez un comportement similaire, par exemple lors de la mise à jour d’un nœud, vous devrez rechercher dans tout le projet entity_presave ou entity_update. Souvent, les développeurs suivent la convention de code et laissent des commentaires sur les hooks "Implémente hook_entity_presave()", vous pouvez donc chercher par le nom du hook, mais gardez à l’esprit que tous les développeurs ne respectent pas la convention, surtout si vous avez hérité d’un projet de la dernière équipe qui a échoué.
Nous avons examiné seulement quelques hooks, mais je pense que vous devriez avoir une certaine idée d’où utiliser les hooks. Plus vous ferez de tâches Drupal, plus vous rencontrerez souvent le besoin d’écrire du code personnalisé. Si un des hooks semble un bon endroit pour ajouter du code, vous pouvez l’implémenter sans crainte dans votre module personnalisé.