Accroches

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 MyExtensionHooks::pageContentSaveComplete quand l'accroche PageContentSaveComplete est sollicitée, en passant à sa fonction, les arguments spécifiques à PageContentSaveComplete.

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 extension.json de l'extension:

"Hooks": {
    "PageContentSaveComplete": "MyExtensionHooks::onPageContentSaveComplete"
}

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 LocalSettings.php ou dans votre fichier personnel d'extension à la portée du fichier (non pas dans une fonction $wgExtensionFunctions ni dans l'accroche de ParserFirstCallInit). 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 hooks.txt, et définie dans GlobalFunctions.php. 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 $wgHooks. Elle appelle la fonction PHP call_user_func_array avec les arguments qui seront ceux de la fonction appelée.

Voir aussi la spécification des accroches du système.

Dans cet exemple de la fonction doEditContent de WikiPage.php, doEditContent appelle Hooks::run pour exécuter l'accroche PageContentSaveComplete, en lui passant $hookArgs comme argument :

Hooks::run( 'PageContentSaveComplete', $hookArgs );

Le Noyau appelle beaucoup d'accoches, mais Manuel:Extensions 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 $wgHooks 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 LocalSettings.php, 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:

Format	Syntaxe	Appel de fonction résultant
Fonction statique	$wgHooks['EventName'][] = 'MyExtensionHooks::onEventName';	MyExtensionHooks::onEventName( $param1, $param2 );
Fonction sans données	$wgHooks['EventName'][] = 'someFunction';	someFunction( $param1, $param2 );
Fonction avec données	$wgHooks['EventName'][] = [ 'someFunction', $someData ];	someFunction( $someData, $param1, $param2 );
Fonction sans données (syntaxe bizarre mais OK)	$wgHooks['EventName'][] = [ 'someFunction' ];	someFunction( $param1, $param2 );
fonction anonyme en ligne	$wgHooks['EventName'][] = function ( $param1, $param2 ) { // ...function body }	(the anonymous function is called with the hook's parameters)
Objet seul	$wgHooks['EventName'][] = $object;	$object->onEventName( $param1, $param2 );
Objet avec méthode	$wgHooks['EventName'][] = [ $object, 'someMethod' ];	$object->someMethod( $param1, $param2 );
Objet avec méthode et données	$wgHooks['EventName'][] = [ $object, 'someMethod', $someData ];	$object->someMethod( $someData, $param1, $param2 );
Objet seul (syntaxe bizarre mais OK)	$wgHooks['EventName'][] = [ $object ];	$object->onEventName( $param1, $param2 );

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

{
	"Hooks": {
		"EventName": [
			"MyExtensionHooks::onEventName",
			"someFunction"
		]
	}
}

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 :

$wgHooks['PageContentSaveComplete'][] = [ 'ircNotify', 'TimStarling' ];
$wgHooks['PageContentSaveComplete'][] = [ 'ircNotify', 'brion' ];

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.

Dans la plupart des cas où un message d'erreur est attendu, l'accroche va définir une variable passée par référence pour que les extensions y enregistrent un message d'erreur ce qui est préférable plutôt que de renvoyer une chaîne de caractères qui ne sera qu'affichée en tant qu' "erreur interne".

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

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 faux au lieu de vrai/void et a ainsi court-circuité tout le système.

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

Par exemple, si l'accroche onBeforePageDisplay 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 onBeforePageDisplay.

Avant MediaWiki 1.22

public static function onBeforePageDisplay( OutputPage $out, Skin $skin ) {
    // some code
    return true; // explicit
}

ou

public static function onBeforePageDisplay( OutputPage $out, Skin $skin ) {
    // some code
    return; // explicit
}

MediaWiki 1.22+

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

Documentation

Actuellement, les accroches du coeur de MediaWiki doivent être documentées à la fois dans docs/hooks.txt (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 catégorie , qui devrait être plus à jour.

Voir aussi

• $wgHooks
• Category:Extensions d'accroches
• Manuel:Extensions de balise
• Fonctions d'analyse
• hooks.txt — documentation of the hooks in MediaWiki core
• Extension:Example — contains examples of hooks
• mw.hook — the JavaScript/front-end system of hooks