Manual:Hooks/fr



Les accroches permettent au code utilisateur d'être exécuté lorsqu'un événement prédéfini (tel que l'enregistrement d'une page ou la connexion d'un utilisateur) se produit. Par exemple, l'extrait de code suivant déclenche un appel à la fonction chaque fois que le hook   s'exécute, en lui transmettant des arguments de fonction spécifiques à.

Les accroches peuvent être enregistrées en établissant une correspondance entre le nom de l'accroche et la procédure de callback dans le fichier de l'extension:

MediaWiki fournit beaucoup d'accroches comme celle-ci pour étendre les fonctionnalités du logiciel MediaWiki. Assigner une fonction (appelée gestionnaire d'événements) à une accroche fera que cette fonction sera appelée à l'endroit approprié du code principal MediaWiki, afin d'exécuter toute(s) tâche(s) supplémentaire(s) que le développeur pense utile(s) à cet endroit. Chaque accroche peut avoir de multiples gestionnaires qui lui sont attachés, auquel cas elle appellera les fonctions dans l'ordre où elles ont été assignées, les modifications laissées par une fonction étant passées à la fonction suivante de la chaîne.

Assignez les fonctions aux accroches à la fin de ou dans votre fichier personnel d'extension à la portée du fichier (non pas dans une fonction  ni dans l'accroche de ). Pour les extensions, si le comportement de la fonction de l'accroche est conditionné par une valeur de LocalSettings.php, l'accroche devra être assignée et la fonction se terminer plus tôt lorsque la condition n'est pas satisfaite.

Vous pouvez également créer de nouveaux crochets dans votre propre extension. Il est enregistré dans extension.json de la même manière que si vous étiez en train d'enregistrer un hook MediaWiki intégré à utiliser dans votre extension. Vous pouvez alors exécuter votre crochet dans votre extension en appelant. Enfin, n'oubliez pas de les ajouter au Registre de hook d'extension.

Contexte
Une accroche est déclenchée par un appel à HookContainer::run, et souvent par une méthode dans HookRunner. HookContainer trouvera les gestionnaires d'accroches à exécuter, et les appellera avec les paramètres donnés à HookContainer::run. Gestionnaires d'accroches enregistrés via.

Voir aussi la.

Dans cet exemple de la fonction  de, doPurge appelle HookRunner::onArticlePurge pour exécuter l'accroche , en lui passant   comme argument :

Le appelle beaucoup d'accoches, mais  peut aussi appeler des accroches.

Ecrire un gestionnaire d'événements
Un gestionnaire d'événements est une fonction que vous assignez à une accroche, et qui sera exécutée à chaque fois que l'événement représenté par cette accroche se produit. Il consiste en :


 * une fonction avec quelques données optionnelles qui l'accompagnent, ou
 * un object avec une méthode et quelques données optionnelles qui l'accompagnent.

Enregistrez le gestionnaire d'événements en l'ajoutant au tableau global pour un événement donné. Les attaches peuvent être ajoutées en tout point de l'exécution avant que l'accroche ne soit appellée, mais sont en général ajoutées dans, ses fichiers inclus, ou, pour les extensions, dans le fichier. Tout ce qui suit sont des manières valides pour définir une fonction d'accroche pour l'événement EventName à qui on passe deux paramètres, montrant le code qui sera exécuté quand l'événement EventName se produit:

Pour les extensions, la syntaxe est similaire dans le fichier  (correspondant au premier et au second cas ci-dessus):

Quand une erreur survient, la fonction (ou la méthode de l'objet) que vous avez enregistrée est appelée, avec les paramètres de l'événement, et toutes les données facultatives que vous avez fournies à l'enregistrement. Notez que lorsqu'un objet est l'accroche et que vous n'avez pas indiqué de méthode, la méthode appelée est 'onEventName'. Pour les autres événements cela serait 'onArticleSave', 'onUserLogin', etc.

Les données optionnelles sont utiles si vous voulez utiliser la même fonction ou objet pour différents objectifs. Par exemple :

Ce code résulterait en une double exécution de ircNotify quand une page est enregistrée : une fois pour 'TimStarling', et une fois pour 'brion'.

Les gestionnaires d'événements peuvent retourner l'une des trois valeurs possibles :


 * aucune valeur retournée (ou nul): le gestionnaire de l'attache s'est bien exécuté. (Avant MediaWiki 1.23, il était nécessaire de retourner la valeur vrai.)
 * "une chaîne de caractères": une erreur est survenue; le traitement doit s'arrêter et l'erreur doit être affichée à l'utilisateur
 * : le gestionnaire de l'attache a fait le travail demandé, ou s'est substitué au traitement normal. Cela empêche les autres gestionnaires d'être exécutés, et dans certains cas cela permet à la fonction appelante de sauter le traitement normal.

Retourner  donne moins de sens aux événements pour lesquels l'action est terminée, et sera normalement ignoré par l'appelant.

Handling hooks in MediaWiki 1.35 and later
MediaWiki 1.35 introduces a system for handling hooks based on individual hook interfaces. This system allows for dependency injection, provides machine-readable parameter names and types, and integrates hook documentation with code editors.

For extensions, methods of registering and handling hooks in MediaWiki 1.34 and earlier are not being deprecated and will continue to work as expected. Extension authors who want to pilot the new system are welcome to do so. To learn more, see the hook specification in MediaWiki Core and the announcement on wikitech-l.

 Changes to hook names 

Prior to MediaWiki 1.35, several hooks included colons in their names. With the implementation of hook interfaces, colons in hook names have been replaced with underscores. For example, the interface for ApiFeedContributions::feedItem is. This does not impact extensions using the hook system in MediaWiki 1.34 and earlier.

 Registering hooks using HookHandlers 

To register a hook in an extension's extension.json file, the new system uses HookHandlers to specify how the handler object is created. Instead of mapping a hook directly to a function, a hook maps to a HookHandlers object which specifies the  and has the option to inject.

For example, to register the BeforePageDisplay hook:

 Handling hooks using interfaces 

To work with registration using HookHandlers, extensions should define an event handler class that implements the hook interface. Hook interfaces are named with the hook name with "Hook" appended.

 Converting extensions to the new hook system  Conversion to the new system is done by doing the following for each hook handler method:
 * identify the hook handler interface, and make the hook handler class implement this interface
 * change the name and signature of the hook handler method to be exactly the same as in the interface
 * change the hook registration in the "Hooks" section of extension.json to refer to the handler you specified in the "HookHandlers" section.

The process was demonstrated at the Wikimedia Hackathon 2021:
 * Recording on YouTube
 * Patch on Gerrit

Comportement de l'accroche avant MediaWiki 1.22 et après
Extrait de : change 500542: pour les accroches non abortables (cas de la plupart des accroches) retourner vrai est redondant depuis MediaWiki 1.22 (en 2015). Ceci a été fait pour réduire les chances d'un disfonctionnement accidentel parce que nous avons expérimenté plusieurs pannes et fonctionalités cassées à cause de fautes silencieuses où par exemple une fonction de callback quelque part a involontairement retourné un non booléen ou bien  au lieu de   ou 'void' et a ainsi court-circuité tout le système.

(Retourner non-vrai/non-void dans une accroche MediaWiki est équivalent à  et   pour les événements JavaScript, cela tue les autres écouteurs du même événement).

Par exemple, si l'accroche  devait retourner faux dans MobileFrontend, cela signifierait que Popups s'est arrêté car son callback ne s'exécute plus. Voir les différences ci-dessous, en supposant que l'accroche est.

Avant MediaWiki 1.22

ou

MediaWiki 1.22+

Documentation
Actuellement, les accroches du coeur de MediaWiki doivent être documentées à la fois dans l'interface des accroches (dépôt du code source) et ici sur MediaWiki.org. Dans certaines situations, un de ces endroits peut ne pas encore être finalisé, aussi si une accroche paraît non documentée, vérifiez les deux cas.

Chaque accroche fournie par le noyau de MediaWiki est définie par un interface d'accroche. Les interfaces d'accroches sont typiquement situés dans un sous-espace de noms « Hook » de l'espace de noms de l'appelant. Par exemple,. Vous pouvez trouver une liste d'interfaces d'accroches dans la documentation PHP générée de MediaWiki.

Pour documenter une accroche du wiki, utilisez MediaWikiHook.

Modèle de doncumentation de l'interface des accroches

Dans les interfaces d'accroches, la documentation décrit le statut, la fonction, les paramètres et le comportement de l'accroche.

Accroches groupées par fonction
Certaines de ces accroches peuvent être groupées dans plusieurs fonctions.
 * Sections: Gestion des articles - Modification de page - Génération de page - Interface utilisateur - Gestion des fichiers - Pages spéciales - Gestion des utilisateurs - Journalisation - Modèles d'habillages - API - Import/Export - Differences - Divers

Liste alphabétique des accroches
Pour une liste complète des accroches, utilisez la, qui devrait être plus à jour.

Voir aussi

 * — spécification du système des accroches
 * Liste des interfaces d'accroches du noyau de MediaWiki
 * — contient des exemples d'accroches
 * — le système d'accroches de JavaScript ou de l'interface utilisateur
 * — spécification du système des accroches
 * Liste des interfaces d'accroches du noyau de MediaWiki
 * — contient des exemples d'accroches
 * — le système d'accroches de JavaScript ou de l'interface utilisateur