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  quand l'accroche   est sollicitée, en passant à sa fonction, les arguments 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' accoches comme celle-ci pour étendre les fonctionalités du lociciel 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 atachés, auquel cas elle appellera les fonctions dans l'ordre où elles ont été assignées, les modifications laissées par une function é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 aussi créer de nouvelles accroches dans votre propre extension; si vous le faites, ajoutez les au registre des accroches des extensions.

Contexte
Une accroche est déclenchée par un appel à la fonction Hooks::run (décrite dans le fichier, et définie dans . Le premier argument de Hooks::run est le nom de l'accroche, le second est le tableau des arguments de cette accroche. Elle trouvera les gestionnaires d'événements à exécuter dans le tableau . Elle appelle la fonction PHP call_user_func_array avec les arguments qui seront ceux de la fonction appelée.

Voir aussi la.

Dans cet exemple de la fonction  de, doEditContent appelle Hooks::run 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 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 extension.json. 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
 * faux : 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 faux donne moins de sens aux événements pour lesquels l'action est terminée, et sera normalement ignoré par l'appelant.

Hook behavior before MediaWiki 1.22 vs after
Extracted from: change 500542: for non-abortable hooks (most hooks) returning true has been redundant since MediaWiki 1.22 (in 2015). This was done to reduce chances of accidental failure because we had experienced several outages and broken features due to silent failures where e.g. one hook callback somewhere accidentally returned a non-bool or false instead of true/void and thus short-circuits the whole system. (Returning non-true/non-void in a MediaWiki Hook is equivalent to  and   in JavaScript events, it kills other listeners for the same event).

For example, if  hook were to return false in MobileFrontend, it would mean Popups stops because its callback would no longer run. See differences below, assuming the hook ;

Before MediaWiki 1.22

public static function onBeforePageDisplay( OutputPage $out, Skin $skin ) {

return true; // explicit }

or

public static function onBeforePageDisplay( OutputPage $out, Skin $skin ) {

return; // explicit }

MediaWiki 1.22 and above

public static function onBeforePageDisplay( OutputPage $out, Skin $skin ) { // no need for a return true or return }

Documentation
Actuellement, les accroches du coeur de MediaWiki doivent être documentées à la fois dans (dans le dépôt de 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.

Pour documenter une accroche de wiki, utilisez MediaWikiHook.

Accroches disponibles
Pour une liste complète des accroches, utilisez la, qui devrait être plus à jour.

Voir aussi

 * Quelques exemples
 * Quelques exemples
 * Quelques exemples
 * Quelques exemples
 * Quelques exemples
 * Quelques exemples