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 provides many hooks like this to extend the functionality of the MediaWiki software. Assigning a function (known as an event handler) to a hook will cause that function to be called at the appropriate point in the main MediaWiki code, to perform whatever additional task(s) the developer thinks would be useful at that point. Each hook can have multiple handlers assigned to it, in which case it will call the functions in the order that they are assigned, with any modifications made by one function passed on to subsequent functions in the chain.

Assign functions to hooks at the end of or in your own extension file at the file scope (not in a  function or the  hook). For extensions, if the hook function's behavior is conditioned on a setting in LocalSettings.php, the hook should be assigned and the function should terminate early if the condition was not met.

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
A hook is triggered by a call to the function Hooks::run (described in file, and defined in . The first argument to Hooks::run is the name of the hook, the second is the array of arguments for that hook. It will find the event handlers to run in the array . It calls the PHP function call_user_func_array with arguments being the function to be called and its arguments.

See also the.

In this example from the  function in, doEditContent calls Hooks::run to run the  hook, passing   as argument:

""

The calls many hooks, but  can also call hooks.

Ecrire un gestionnaire d'événements
An event handler is a function you assign to a hook, which will be run whenever the event represented by that hook occurs. It consists of:


 * a function with some optional accompanying data, or
 * an object with a method and some optional accompanying data.

Register the event handler by adding it to the global array for a given event. Hooks can be added from any point in the execution before the hook is called, but are most commonly added in, its included files, or, for extensions, in the file extension.json. All the following are valid ways to define a hook function for the event EventName that is passed two parameters, showing the code that will be executed when EventName happens:

For extensions, the syntax is similar in the file  (corresponding to the first and second case above):

When an event occurs, the function (or object method) that you registered will be called, the event's parameters, along with any optional data you provided at registration. Note that when an object is the hook and you didn't specify a method, the method called is 'onEventName'. For other events this would be 'onArticleSave', 'onUserLogin', etc.

The optional data is useful if you want to use the same function or object for different purposes. For example:

This code would result in ircNotify being run twice when a page is saved: once for 'TimStarling', and once for 'brion'.

Event handlers can return one of three possible values:


 * no return value (or null): the hook handler has operated successfully. (Before MediaWiki 1.23, returning true was required.)
 * "some string": an error occurred; processing should stop and the error should be shown to the user
 * false: the hook handler has done all the work necessary, or replaced normal handling. This will prevent further handlers from being run, and in some cases tells the calling function to skip normal processing.

Returning false makes less sense for events where the action is complete, and will normally be ignored by the caller.

Documentation
Currently, hooks in MediaWiki core have to be documented both in (in the source code repository) and here on MediaWiki.org. In some cases, one of these steps may not yet have been completed, so if a hook appears undocumented, check both.

To document a hook on-wiki, use MediaWikiHook.

Available hooks
For a complete list of hooks, use the category, which should be kept more up to date