Comprendre les crochets de mise à jour et de post-mise à jour pour des mises à jour de site réussies

Lors des mises à jour de base ou des mises à jour de modules, il est crucial de garantir la stabilité et l'intégrité de votre site Web Drupal. Heureusement, le module Update API et Update/Post Update Hooks sont là pour vous aider.

Le module Update API fournit les hooks nécessaires à la mise à jour du code et des modules sur votre site Drupal. Ces crochets ne sont rien d'autre que des crochets de mise à jour et de post-mise à jour qui permettent aux développeurs de personnaliser les mises à jour en fonction de leurs besoins.

Dans cet article, nous discuterons de l'API de mise à jour, de ce que sont les crochets de mise à jour et de post-mise à jour et quand et comment ils doivent être utilisés. En comprenant les deux types de crochets, vous pouvez mettre à jour avec succès votre site Drupal avec un minimum d'effort. Commençons!

L'API de mise à jour

Lorsque vous travaillez sur un site existant, lorsque vous mettez à jour le code dans un module, vous devrez peut-être mettre à jour les données stockées afin que les données stockées soient compatibles avec le nouveau code. Vous avez peut-être remarqué des erreurs telles que "Le site Web a rencontré une erreur inattendue" clignotent devant vous. Effrayant non ! ? Je sais! C'est là que l'API Update de Drupal vient à notre secours.

Si la mise à jour se situe entre deux versions mineures de votre module dans la même version majeure du noyau Drupal, vous pouvez utiliser l'API de mise à jour pour mettre à jour les données. L'API de mise à jour vous permet de fournir un code qui effectue une mise à jour des données stockées chaque fois que votre module modifie son modèle de données. La modification du modèle de données fait référence à toute modification qui rend les données stockées sur un site existant incompatibles avec la base de code mise à jour de ce site. Ces modifications du modèle de données impliquent :

Mise à jour du schéma de configuration

• Ajouter/supprimer/renommer une clé de configuration.
• Modification du type de données de la clé de configuration.
• Modification de la valeur par défaut attendue d'une clé de configuration, etc.

Mise à jour du schéma de la base de données

• Ajouter/modifier/supprimer une table ou un champ de base de données.
• Déplacer les données stockées vers un autre champ ou une autre table.
• Modification du format des données stockées, etc.

Mise à jour des entités et des champs

• Ajout d'un nouveau champ de base à un type d'entité existant.
• Mise à jour d'un champ d'un type obsolète vers un nouveau type, etc.

Mise à jour des données

• Manipuler les données stockées sur un site existant.

Travailler avec les crochets de mise à jour

Hook hook_update_N() est utilisé pour introduire une mise à jour entre les versions mineures d'un module. Ces crochets sont placés dans votre module dans le fichier *.install .

Le hook_update_N() est écrit sous la forme de (nom du module)_update_(numéro). Ici N comprend :

• 1 ou 2 chiffres font référence à la compatibilité du noyau Drupal (Drupal 8, 9, 10, etc.)
• Le chiffre 1 suivant correspond à la version majeure de votre module
• Les 2 derniers chiffres pour le comptage séquentiel, en commençant par 01

Exemple:

example_update_9201() : La première mise à jour pour les versions 9.x-2.x.
Où 'exemple' est le nom du module, le premier chiffre fait référence à la version principale de Drupal '9', le nombre '2' fait référence à la version majeure du module et les deux derniers chiffres '01' indiquent la première fonction de mise à jour écrite pour module 'exemple'.

La partie numérique de la fonction d'implémentation du hook (c'est-à-dire 9201 dans l'exemple ci-dessus) est stockée dans la base de données pour garder une trace des mises à jour qui ont déjà été exécutées. Vous ne devez donc jamais renuméroter les fonctions de mise à jour.
Pour connaître la version actuelle du schéma d'un module 'exemple stocké dans la base de données', utilisez :

drush php-eval "echo drupal_get_installed_schema_version('example');"

Pour redéfinir manuellement la version actuelle du schéma d'un module "exemple" sur "9201", utilisez :

drush php-eval "echo drupal_set_installed_schema_version('example', '9201');"

Remarque : veuillez essayer d'éviter d'utiliser la fonction drupal_set_installed_schema_version() sur les sites de production car elle met directement à jour votre base de données. Vous pouvez l'utiliser sur vos environnements de test locaux ou inférieurs pendant le développement pour réinitialiser la version du schéma.

Ajoutez une description appropriée dans le commentaire du bloc de document avant la fonction de crochet de mise à jour car elle sera imprimée pour les utilisateurs lors de son exécution.

 Structure of hook_update_N(): /** * A aimple hook_update_N() hook. */ function example_update_9201() { // Code goes here. }

Ces crochets sont exécutés dans un ordre trié, c'est-à-dire que le crochet example_update_9201() s'exécute avant example_update_9202(), le suivant est 9203, 9204 et ainsi de suite.

Vous pouvez également modifier l'ordre de tri de ces crochets, en introduisant des dépendances entre les crochets. Utilisez le crochet hook_update_dependencies() pour exécuter des mises à jour entre deux crochets de mise à jour.

Tous les crochets de mise à jour sont exécutés par lots et prennent également en charge le traitement par lots des éléments. Tous les crochets de mise à jour ont accès à un paramètre $sandbox qui peut être utilisé pour créer des processus par lots dans les crochets de mise à jour afin de traiter d'énormes données à la fois sans provoquer l'expiration de PHP.

Un exemple simple de crochet de mise à jour pour ajouter une nouvelle clé de configuration :

Actuellement, le fichier example_module.settings.yml contient :

Pour ajouter une nouvelle "description" de clé à la configuration :

• Ajouter la clé 'description' au fichier de paramètres

• Ajoutez le update_hook dans le fichier example_module.install :

• Utilisez drush updb pour exécuter le hook.

• Vérifiez la configuration mise à jour, la nouvelle clé 'description' est mise à jour.

Travailler avec les hooks de post-mise à jour

Hook hook_post_update_NAME(), similaire au hook de mise à jour, est utilisé pour introduire une mise à jour. Mais ce crochet est principalement destiné à mettre à jour des données, comme des entités. Ces hooks sont exécutés après l'exécution de tous les hooks hook_update_N(). À ce stade, Drupal est déjà entièrement réparé, vous pouvez donc utiliser n'importe quelle API du site.

Ces crochets sont placés dans un fichier *.post_update.php de votre module.

Le hook_post_update_NAME() est écrit sous la forme de (nom du module)_post_update_(n'importe quel nom). Ici, NAME peut être n'importe quel nom de machine arbitraire. Cette dénomination alphanumérique des fonctions dans le fichier est la seule chose qui assure l'ordre d'exécution de ce crochet.

Comme pour les crochets de mise à jour, ajoutez une description appropriée dans le commentaire docblock avant le crochet post_update. Aussi, ne réutilisez pas le même nom de hook.

Structure de hook_post_update_NAME() :

 /** * A aimple hook_post_update_NAME() hook. */ function example_post_update_test() { // Code goes here. }

Tout comme avec les crochets de mise à jour, utilisez le paramètre $sandbox pour indiquer que l'API Batch doit être utilisée pour vos crochets post_update.

Un exemple simple sur l'utilisation du crochet post-mise à jour pour mettre à jour les données de terme :

• Actuellement, tous les termes sous le vocabulaire des balises ont un champ "Exemple de test" désactivé.

• Ajoutez un hook post_update dans le fichier example_module.post_update.php pour activer le champ 'Test example' pour tous les termes existants.

• Utilisez drush updb pour exécuter le hook.

• Vérifiez les données terminologiques mises à jour, la case 'Test example' doit être cochée.

Comment exécuter ces crochets !

Vous pouvez utiliser la commande Drush pour exécuter ces crochets, drush updb. Il construit le lot selon les étapes suivantes :

• Tous les crochets de mise à jour sont découverts.
• Résout les dépendances et trie leur ordre.
• Des crochets sont placés pour le traitement par lots.
• Ensuite, tous les crochets Post sont découverts.
• S'il existe des hooks post_update et si update_hook a déjà été exécuté, les caches sont effacés.
• Ensuite, poussez chaque crochet post_update dans le lot.
• Exécutez le lot.

L'un des principaux avantages du hook post-mise à jour par rapport au hook de mise à jour est que Drupal est entièrement fonctionnel au moment de l'exécution de la post-mise à jour. Cela permet aux développeurs d'utiliser n'importe quel service Drupal tout en utilisant le crochet post-mise à jour. Avec le crochet de mise à jour, il ne faut pas supposer que Drupal est entièrement réparé et éviter d'invoquer d'autres crochets, API d'entité, etc.

Dernières pensées

Lorsque vous essayez de réparer votre site en mettant à jour le schéma de configuration/base de données, essayez d'utiliser des hooks de mise à jour. Lorsqu'il s'agit de manipuler des données stockées, de réenregistrer des configurations, de mettre à jour des entités de contenu, de vider le cache, etc., les crochets post-mise à jour sont plus appropriés à utiliser.

Pour être honnête, il n'y a pas de documentation claire sur Drupal.org concernant quand utiliser quel hook ! Il y a un problème ouvert demandant d'améliorer la documentation sur l'utilisation de ces deux crochets auquel vous pouvez contribuer si vous le souhaitez.

Mais sur la base de l'expérience des développeurs et en prenant comme exemple les modules principaux de Drupal 9 et 10, utilisez les crochets de mise à jour pour effectuer des opérations CRUD sur les configurations ou les bases de données (c'est-à-dire réparer le site) et utilisez les crochets post-mise à jour pour les entités de contenu CRUD ( puis corrigez les données sur le site mis à jour), car les hooks post-mise à jour sont exécutés après les hooks de mise à jour.

Vous avez apprécié la lecture de cet article ? Montrez-nous un peu d'amour et abonnez-vous à notre newsletter hebdomadaire dès aujourd'hui !