Manual:Hooks/de



Hooks (dt. Haken) ermöglichen die Ausführung von benutzerdefiniertem Code, wenn ein definiertes Ereignis (wie das Speichern einer Seite oder die Anmeldung eines Benutzers) eintritt. Beispielsweile löst der folgende Codeausschnitt einen Aufruf der Funktion  aus, wenn der  -Hook ausgeführt wird, wobei ihm Funktionsargumente übergeben werden, die spezifisch für  sind.

Hooks können registriert werden, indem der Name des Hooks dem Callback in der -Datei der Erweiterung zugeordnet wird:

""

MediaWiki bietet viele solcher Hooks, um die Funktionalität der MediaWiki-Software zu erweitern. Die Zuweisung einer Funktion (bekannt als Ereignisbehandler) zu einem Hook bewirkt, dass diese Funktion an der entsprechenden Stelle im MediaWiki-Hauptcode aufgerufen wird, um die zusätzliche(n) Aufgabe(n) auszuführen, die der Entwickler an dieser Stelle für nützlich hält. Jedem Hook können mehrere Handler zugewiesen werden. In diesem Fall ruft er die Funktionen in der Reihenfolge auf, in der sie zugewiesen sind, wobei alle Änderungen, die von einer Funktion vorgenommen werden, an nachfolgende Funktionen in der Kette weitergegeben werden.

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.

You can also create new hooks in your own extension; if you do so, add them to the Extension hook registry.

Hintergrund
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, doPurge calls Hooks::run to run the  hook, passing   as argument:

""

Der ruft viele Hooks auf, aber  können auch Hooks aufrufen.

Schreiben eines Ereignishandler
Ein Event-Handler ist eine Funktion, die zu einem Hook zugeordnet ist, der ausgeführt wird, wenn das Ereignis von diesem Hook vertreten auftritt wird. Es besteht aus:


 * eine Funktion mit einigen optionalen begleitenden Daten, oder
 * einer Aufgabe mit einem Verfahren und einigen optionalen zugehörigen Daten.

Eventhandler werden registriert, indem sie sie zum globalen Array für ein gegebenes Ereignis hinzufügen. Hooks können von jedem beliebigen Punkt in der Ausführung hinzugefügt werden, bevor der Hook aufgerufen ist, sind aber am häufigsten in hinzugefügt oder seiner enthaltenen Dateien. Alle die folgenden sind gültige Möglichkeiten, um Hooks zu definieren, mit dem Code der ausgeführt wird, wenn 'EventName' passiert:

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

Wenn ein Ereignis eintritt, wird die Funktion (oder Objekt-Methode) mit den optional zur Verfügung gestellten Daten sowie Event-spezifischen Parametern aufgerufen werden. Beachten Sie, dass wenn ein Objekt der Hook ist und es keine festgelegte Methode gibt, die Standard-Methode namens 'OnEventName' ist. Für verschiedene Ereignisse wäre dies anders: 'onArticleSave', 'onUserLogin', etc.

Die zusätzlichen Daten sind sinnvoll, wenn wir die gleiche Funktion oder ein Objekt für unterschiedliche Zwecke nutzen wollen. Zum Beispiel:

Dieser Code würde in ircNotify resultieren, zweimal zu laufen wenn ein Artikel gespeichert: einmal für 'TimStarling', und einmal für "Brion".

Event-Handler können einen von drei möglichen Werten zurückgeben:


 * no return value (or null): the hook handler has operated successfully. (Before MediaWiki 1.23, returning true was required.)
 * "some string": ein Fehler ist aufgetreten; die Verarbeitung sollte abbrechen, und der Fehler sollte dem Benutzer angezeigt werden
 * 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.

Handling hooks in MediaWiki 1.35 and later
MediaWiki 1.35 introduces a system for handling hooks based on individual hook interfaces. This system allows for dependency injection, provides machine-readable parameter names and types, and integrates hook documentation with code editors.

For extensions, methods of registering and handling hooks in MediaWiki 1.34 and earlier are not being deprecated and will continue to work as expected. Extension authors who want to pilot the new system are welcome to do so. To learn more, see the hook specification in MediaWiki Core and the announcement on wikitech-l.

 Changes to hook names 

Prior to MediaWiki 1.35, several hooks included colons in their names. With the implementation of hook interfaces, colons in hook names have been replaced with underscores. For example, the interface for ApiFeedContributions::feedItem is ApiFeedContributions__feedItemHook. This does not impact extensions using the hook system in MediaWiki 1.34 and earlier.

 Registering hooks using HookHandlers 

To register a hook in an extension's extension.json file, the new system uses HookHandlers to specify how the handler object is created. Instead of mapping a hook directly to a function, a hook maps to a HookHandlers object which specifies the  and has the option to inject.

For example, to register the BeforePageDisplay hook:

 Handling hooks using interfaces 

To work with registration using HookHandlers, extensions should define an event handler class that implements the hook interface. Hook interfaces are named with the hook name with "Hook" appended.

Hook-Verhalten vor MediaWiki 1.22 und danach
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. Siehe Unterschiede unten, unter der Annahme des Hooks.

Vor MediaWiki 1.22

oder

MediaWiki 1.22+

Dokumentation
Currently, hooks in MediaWiki core have to be documented both in hook interface (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.

Each hook provided by MediaWiki Core is defined in a hook interface. Typically, hook interfaces are located in a "Hook" sub-namespace inside the caller namespace. For example,. You can find a list of hook interfaces in the generated MediaWiki PHP documentation.

Um einen Hook im Wiki zu dokumentieren, verwende MediaWikiHook.

Hook interface doc template

In hook interfaces, doc comments specify the status, purpose, parameters, and behavior of the hook.

Hooks grouped by function
Some of these hooks can be grouped into multiple functions.
 * Sections: Article Management - Edit Page - Page Rendering - User Interface - Special Pages - User Management - Logging - Skinning Templates - API - Import/Export - Miscellaneous

Alphabetical list of hooks
Für eine vollständige Liste der Hooks, benutzen Sie die, welche mehr auf dem Laufenden gehalten werden sollte

Siehe auch

 * — documentation of the hooks in MediaWiki core
 * List of hook interfaces in MediaWiki Core
 * — contains examples of hooks
 * — the JavaScript/front-end system of hooks
 * — documentation of the hooks in MediaWiki core
 * List of hook interfaces in MediaWiki Core
 * — contains examples of hooks
 * — the JavaScript/front-end system of hooks