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 à.

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 :

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

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:

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'.

Hook handler return values
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. In those cases, the return value is often ignored.

Handling hooks in MediaWiki 1.35 and later
MediaWiki 1.35 introduces the HookHandlers system. This includes per-hook interfaces for improved static validation and discovery of parameter documentation. It also enables dependency injection by introducing an intermediary class instance that accepts a number of specified services (instead of static callbacks that explicitly access services from global state).

The approach from MediaWiki 1.34 and earlier, of registering hook handlers directly as static methods, remains supported and is not deprecated. Extension authors may opt-in to the new system are welcome to do so. To learn more, see the MediaWiki core: Hook specification and the announcement on wikitech-l.

Changes to hook names

Prior to MediaWiki 1.35, hooks sometimes included characters that could not be used in a class or method name, such as colons and dashes. With the introduction of per-hook interfaces, the canoncal names of these hooks have been changed to use underscores instead. For example, the interface for ApiFeedContributions::feedItem is. Hook handers that are registered with the old names remain supported.

Registering hooks using HookHandlers

To adopt the new system, changes your Hooks class to have regular methods instead of static methods and be contructable. This class is then registered once, via the HookHandlers attribute in extension.json, using the  option as part of an ObjectFactory description where you can use the   option.

For example, to register the BeforePageDisplay hook:

Handling hooks using interfaces

To use hook interfaces, extensions should define a Hooks class in their namespace and implement one or more hook interfaces. Hook interfaces are named with the hook name followed by the word "Hook".

Convert an extension to the new hook system:

Follow these steps for each hook handling method:
 * identify the hook handler interface, and make the Hooks class implement this interface.
 * update the method name and signature to be exactly the same as in the interface.
 * change 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:
 * Example patch for an extension
 * Recording on YouTube



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 disponibles


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