Manual:Extension registration/de

Extension registration ist der Mechanismus, den MediaWiki nutzt, um Erweiterungen und Skins zu laden. Konfigurationsdaten werden in eine Datei mit dem Namen  oder   im Stammverzeichnis deiner Erweiterung oder deines Skins eingetragen. MediaWiki verwendet diese Daten, um Erweiterungen und Skins zu registrieren.

Vor MediaWiki 1.25 wurde die Konfiguration für Erweiterungen und Skins in einer PHP-Datei vorgenommen, die den gleichen Namen wie die Erweiterung trug, zum Beispiel  oder. Dieses Vorgehen ist veraltet und Entwickler von vorhandenen Erweiterungen und Skins sollten beginnen, in das neue Format zu migrieren.

Migration für Systemadministratoren
Früher hätten Sie in Ihre LocalSettings.php etwa folgendes eingetragen:

Dies schreibt man jetzt so:

Wenn Sie Ihre Erweiterungen in einem anderen Verzeichnis als $IP/extensions gespeichert haben, müssen Sie  ändern. Wenn die Skins nicht im Verzeichnis  gespeichert sind, muss das ungünstig benannte  angepasst werden. Dies muss geschehen, bevor irgendeine Erweiterung oder ein Skin geladen wird.

Since MW 1.30, namespace IDs defined in extension.json can be overwritten locally, by defining the respective constant in LocalSettings.php before loading the extension. Consider for instance the following namespace declaration in a extension.json file: This would per default cause the constant NS_FOO to be defined to have the value 1212. However, this can be overwritten by defining the respective constant in LocalSettings.php: This would cause the "Foo" namespace to be registered with the ID 6688 instead of 1212. When overriding namespace IDs, don't forget that all talk namespaces must have odd IDs, and the ID of the talk namespace must always be the subject namespace's ID plus one.

Migration für Entwickler von Erweiterungen

 * Siehe auch die „wall of sadness“ (jetzt „wall of superpowers“)

Das Skript  hilft dabei, PHP-Eintrittspunkte in eine JSON-Metadaten-Datei zu migrieren. Wenn ihre Erweiterung ältere Versionen von MediaWiki unterstützt, sollten Sie Ihren PHP-Einsprungspunkt FooBar/FooBar.php beibehalten solange die Unterstützung für die älteren Versionen bestehen bleibt.

Beispiel für Befehlszeilen :

Wenn der Fehler angezeigt wird, dass Konstanten oder Funktionen nicht neu definiert werden konnten, müssen Sie Ihre Erweiterung in LocalSettings.php deinstallieren (d.h. auskommentieren).

Dokumentation erhalten
PHP Einsprungpunkte haben in der Regel eine Dokumentation der Konfigurationseinstellungen, die nützlich ist und nicht verloren gehen sollte. Leider unterstützt JSON keine Kommentare. Es wird empfohlen, dass Sie die Konfigurationsdokumentation in eine README Datei im Verzeichnis der Erweiterung übertragen. Sie sollten auch die Konfiguration in der Online-Wikiseite Ihrer Erweiterung dokumentieren: Auf der MyExtension Seite. Es ist möglich eine Dokumentation auch direkt in der extension.json Datei aufzunehmen. "Extension registration" ignoriert alle Schlüssel in extension.json in der obersten Ebene der Struktur die mit ' ' beginnen oder unter, so dass Sie Kommentare in diese Bereiche der JSON-Datei schreiben können. Beispielsweise:

Dies sollte nur für kurze Notizen und Kommentare verwendet werden.

Funktionen
Wenn Sie eine große Anzahl von Erweiterungen laden, bietet "extension registration" eine Leistungssteigerung, sofern APC (or APCu) installiert ist. Erweiterungen, die zusammen mit  (mit Plural -s) geladen werden, werden zusammen gecacht.

Eigenschaften
Ein immer wieder auftretendes Problem ist, wie man etwas bei einer anderen Erweiterung "registriert". Normalerweise hat dies bedeutet, dass man eine Erweiterung vor einer anderen laden musste. Zum Beispiel hat VisualEditor ein, das es Erweiterungen ermöglicht ihre Module hinzuzufügen. Allerdings sieht das Array beim Laden des VisualEditors so aus:

Wenn eine Erweiterung das Array erweitert bevor VisualEditor geladen ist, wird VE beim Laden alle Einträge aus dem Array löschen. Einige Erweiterungen hingen von einer bestimmten Ladereihenfolge ab, andere hackten um diese mit herum. Extension registration löst dieses Problem mit "Eigenschaften". In der Erweiterung Math ist in ihrer  etwa folgendes eingetragen:

Starting with manifest version 2, the attributes need to be defined in the separate section section.

The  node needs to be an object with the extension name as key and an object of attribute/value pairs as the value. Be aware that the key in the subobject must not contain the extension name!

Wenn VisualEditor auf dieses Attribut zugreifen möchte, ruft er folgende Funktion auf:

Anforderungen (Abhängigkeiten)
Extension registration has a  section, which acts similar to Composer's   section. Er erlaubt einem Erweiterungs-Entwickler mehrere Anforderungen für die Erweiterung, wie beispielsweise eine spezifische MediaWiki Version (oder größer / kleiner als) oder eine andere Erweiterung oder einen anderen Skin anzugeben. Um zum Beispiel die Abhängigkeit von einer MediaWiki-Version größer als 1.26.0 zu ergänzen, kann folgender Code in  eingefügt werden:

Der Schlüssel des  Objekts ist der Name der Abhängigkeit ist (vor MediaWiki 1.29.0 war nur   unterstützt), der Wert ist eine gültige Versions-Einschränkung (das Format muss dem von Composer verwendeten entsprechen).

In MediaWiki 1.29.0 and above you can also add dependencies on skins and other extensions like so:

Überprüfen Sie, ob eine Erweiterung geladen wird, ohne dass sie vorausgesetzt wird
Viele Erweiterungen können Funktionen bieten, die nur funktionieren, wenn eine andere Erweiterung auch geladen wird, aber ohne dass sie diese Funktion wirklich benötigen, um ihre Kernfunktionen bereitzustellen. Als Beispiel: Wenn Erweiterung B geladen ist, kann Erweiterung A einen echten WYSIWYG-Editor zur Verfügung stellen, andernfalls wird nur ein einfaches Textfeld verwendet. Erweiterung A kann von der Extension B profitieren (wenn sie geladen wird), aber B ist nicht erforderlich, damit A funktioniert. Zu diesem Zweck kann überprüft werdem, ob die Erweiterung geladen ist, anstatt sie als harte Abhängigkeit festzulegen.

Um eine standardisierte Möglichkeit der Überprüfung zu implementieren, ob eine Erweiterung geladen ist oder nicht (ohne die Notwendigkeit von Mehrarbeit in einer Erweiterung, die eine weiche Abhängigkeit von einer anderen hat), kann Extension registration verwendet werden. Sie implementiert eine -Methode, die über ein einfaches boolean zurückgibt, ob die Erweiterung geladen ist oder nicht (die Erweiterung muss mithilfe von "Extension registration" geladen werden, damit dies funktioniert). Beispiel:

Alternativ: Falls die Erweiterung B eine spezielle Konstante für diesen Zweck beim Laden definiert, ist es möglich zu überprüfen ob diese definiert ist:

Es ist eine unschöne Art und Weise, die vermieden werden sollte, zu überprüfen, ob eine bestimmte Klasse einer Erweiterung vorhanden ist oder nicht, z.B. mit diesem Code:

Es könnte zu Problemen führen, wenn die Erweiterung im Dateisystem vorhanden, jedoch nicht geladen ist, z.B. wenn Composer für das automatische Laden verwendet wurde. Wenn die Klasse umbenannt wurde oder nicht mehr besteht (zum Beispiel, weil sie nicht öffentlich ist), wird dies auch zu Problemen führen.

Im Allgemeinen wird es bevorzugt, Code über Composer-Bibliotheken anstelle von Erweiterungen zu teilen. Wenn die Klassen einer Erweiterung nur existieren müssen, aber die Erweiterung weder konfiguriert noch geladen sein muss, um das gewünschte zu tun, ist das ein starkes Indiz dafür, dass der Code in eine Composer-Bibliothek abgespalten werden sollte, zu der stattdessen eine Abhängigkeit bestehen sollte.

Konfigurationen (Ihre Erweiterung/Ekins Einstellungen)
Standardmäßig nimmt extension.json an, dass die Konfigurationseinstellungen mit einem "wg"-Präfix beginnen. Wenn das nicht der Fall ist, ist es möglich das Präfix mit einem speziellen Schlüssel zu überschreiben:

Das verwendet das Präfix "eg" und setzt die globale Variable  auf true.

Starting with manifest version 2, the configuration section of extension registration provides a lot more features and allows you to describe your configuration options much more detailed. Instead of having a single key -> value store for your configuration options, you can also add the following information.

The general structure of the  changes slightly to the following, more object-oriented version:

Wert
Der Konfigurationswert wird an diesen Ort verschoben. Dies ist der einzige notwendige Schlüssel eines Konfigurationsobjektes.

Pfad
Der boolsche Wert des -Schlüssels gibt an, ob der Wert der Einstellungsoption als Pfad im Dateisystem interpretiert werden soll, relativ zum Wurzelverzeichnis der Erweiterung. E.g., if the value of the configuration is  and the   is true, the actual value will be.

Description
The  key for a configuration option can hold a non-localized string, which can be used to explain the configuration option to other developers or the users (system administrators) of your extension. The value of the description key is usually not exposed to the frontend of the wiki, however, take a look to the outlook for more information how this feature could be used in the feature!

There's also the possibility to add a message key of MediaWiki's internal localisation system as a description, which, in the future, will be used to expose the description in the frontend of the MediaWiki installation.

public / private
Diese Option ist ein boolscher Wert, der standardmäßig auf false gesetzt ist, was bedeutet, dass die Einstellung und ihr Wert als „privat“ markiert sind. Dieser Wert wird im Moment nirgendwo verwendet; sieh dir den Ausblick an, um mehr über diese Option herauszufinden.

Outlook
The mentioned changes above are also preparation steps for an improved configuration management in MediaWiki. The above changes allows us to, e.g., expose the configuration options of extensions in the MediaWiki UI. For this, the localised description message ( and  ) and the indication, if the configuration option should be exposed or not  is needed.

Unit tests auto-discovery
MediaWiki allows any extension to register phpunit tests. Without extension registration, you would need to register a hook handler for the hook, which would look something like:

(as described on the manual page). However, this code looks the same for a lot of extensions, so you could call it unnecessary code duplication. If your extension uses extension registration and your phpunit tests are located in the  subdirectory of your extension, the phpunit wrapper of MediaWiki wil autodiscover the unit tests with the help of extension registration. Therefore, you don't need to register the hook anymore and you don't need to specify, that your unit tests are saved in the default directory.

Anpassen der Registrierung
Manchmal müssen Erweiterungen bei der Registrierung etwas tun, das nicht dem Standard entspricht, oder sind nur sehr kompliziert. Sie können einen 'callback' Schlüssel in ihrer extension.json angeben, wenn PHP-Code ausgeführt werden muss. Der Wert sollte auf einen gültigen PHP callable gesetzt werden, zum Beispiel:. wird diesen callback ausführen, nachdem es die -Datei verarbeitet hat.

Der callback ist keine normale Hook-Funktion, er wird in einer frühen Initialisierung-Phase ausgeführt.

In ist aufgeführt, für welche Dinge benutzerdefinierte Registrierung erforderlich sein kann.

See ExtensionFunctions and the SetupAfterCache, BeforeInitialize and ApiBeforeMain hooks for other ways of programmatically interacting with configuration.

Siehe auch composer.json
Wenn eine Erweiterung oder ein Skin Abhängigkeiten zu einer Bibliothek hat, kann es dort auch eine composer.json</tt> geben, siehe. Verwende das -Feld, um MediaWiki Composers Autoloading verwenden zu lassen, sofern dies angebracht ist.

Einige Felder von Metadaten überlappen sich zwischen  und   (in T89456 diskutiert), darunter:
 * und
 * und

Siehe auch

 * Melde Fehler dem MediaWiki-Configuration-Projekt.
 * Alte Versionen der Manual:Developing extensions#Setup (vor Mai 2015) und beschreiben den alten Ansatz, Erweiterungsinformationen in PHP-Code und Variablen zu deklarieren
 * ist das Schema für  (und skin.json). Es gibt ein Werkzeug, das diese Dokumentation erzeugt.
 * RfC zur Umsetzung der Registrierung von Erweiterungen
 * Extension registration wall of superpowers! — summary of which extensions are still to be converted.
 * T98668 — Tracking ticket for converting all extensions and skins on Git to use extension registration.
 * RfC zur Umsetzung der Registrierung von Erweiterungen
 * Extension registration wall of superpowers! — summary of which extensions are still to be converted.
 * T98668 — Tracking ticket for converting all extensions and skins on Git to use extension registration.