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 l'accroche   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'accroche) à une accroche fera que cette fonction sera appelée à l'endroit approprié du code principal MediaWiki, pour exécuter toute(s) tâche(s) supplémentaire(s) que le développeur pense être 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 nouvelles accroches dans votre propre extension. Il est enregistré dans extension.json de la même manière que si vous étiez en train d'enregistrer une accroche MediaWiki intégrée utilisée dans votre extension. Vous pouvez alors exécuter votre accroche 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'accroche
Un gestionnaire d'accroche est une fonction que vous enregistrez et qui sera appelée à chaque fois que l'accroche en question est exécutée.

Pour les extensions, enregistrez vos gestionnaires d'accroche dans le fichier  :

Les gestionnaires d'accroche peuvent également être enregistrés dans le tableau global. Ceci est utilisé en général pour les adaptations spécifiques aux sites dans, ou dans les anciennes extensions d'avant. Tout ce qui suit sont les manières valides pour définir un gestionnaire d'accroche pour l'accroche EventName à qui on passe deux paramètres :

Notez que lorsqu'un objet est assigné et que vous n'avez pas indiqué de méthode, la méthode appelée est "onEventName". Par exemple "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  quand une page est enregistrée : une fois pour 'TimStarling', et une fois pour 'brion'.



Valeurs renvoyées par le gestionnaire d'accroches
Les gestionnaires d'accroche peuvent retourner l'une des trois valeurs possibles :


 * (aucune valeur retournée, ou nul) - le gestionnaire d'accroche s'est bien exécuté. (Avant MediaWiki 1.23, il était nécessaire de renvoyer la valeur .)
 * "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'accroche a fait tout le travail nécessaire, 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.

Renvoyer  donne moins de sens aux accroches qui s'exécutent après que l'action soit terminée. Dans ces cas, la valeur de retour est souvent ignorée.

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 canonical names of these hooks have been changed to use underscores instead. For example, the interface for is. Hook handlers that are registered with the old names remain supported.

Registering hooks using HookHandlers
To adopt the new system, change your Hooks class to have regular methods instead of static methods and to be constructible. 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 en 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 - Différences - 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