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 Ihrer Erweiterung oder Skins eingetragen und 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 mit gleichem Namen wie die Erweiterung oder der Skin geschrieben, zum Beispiel  oder. Dieses Vorgehen ist veraltet und Entwickler von vorhandenen Erweiterungen und Skins sollten beginnen ihre Erweiterungen 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 Ihr Skin nicht im Verzeichnis $IP/skins gespeichert ist, müssen sie ändern. Dies muss geschehen, bevor Sie irgendeine Erweiterung oder einen Skin laden.

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
Das Skript maintenance/convertExtensionToRegistration.php hilft Ihnen PHP Einsprungspunkte in eine JSON-Metadatendatei 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</tt> 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 Sie APC (or APCu) installiert haben. Erweiterungen, die zusammen mit  (mit Mehrzahl -s) geladen werden, werden zusammen zwischengespeichert.

Eigenschaften
Ein immer wieder auftretendes Problem ist, wie man etwas bei einer anderen Erweiterung "registriert". Normalerweise bedeutet dies, dass Sie eine Erweiterung vor einer anderen laden müssen. 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 extension.json</tt> 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 einer andere Erweiterung (noch nicht implementiert, siehe ) zu spezifizieren. Um zum Beispiel eine Abhängigkeit von einer Erweiterung auf eine MediaWiki-Version größer als 1.26.0 zu ergänzen, können Sie den folgenden Code in  einfügen:

Der Schlüssel des  Objekts ist der Name der Abhängigkeit ist (derzeit wird nur MediaWiki unterstützt), der Wert ist eine gültige Versions-Einschränkung (das Format muss einem der vom "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 tatsächlich benötigt 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 mit der Kern-Erweiterungsfunktion zu arbeiten. Als Beispiel: Wenn Erweiterung B geladen ist, kann Erweiterung A einen echten WYSIWYG-Editor zur Verfügung stellen, andernfalls wird nur eine einfache Text-Eingabe verwendet. Erweiterung A kann von der Extension B profitieren (wenn sie geladen wird), aber B ist nicht erforderlich damit A funktioniert. Dazu überprüfen Sie in der Regel, 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 ist), kann "extension registration" verwendet werden. Es implementiert ein  Methode, die ein einfaches boolean zurückgibt, wenn die Erweiterung geladen ist oder nicht (die Erweiterung muss mit der "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 zum Abbruch führen, wenn die Erweiterung im Dateisystem vorhanden, jedoch nicht geladen ist, z.B. wenn der "composer" für das automatische Laden verwendet wurde. Wenn die Klasse umbenannt wurde oder nicht mehr besteht (zum Beispiel, weil sie nicht öffentlich gepackt ist), wird dies auch zum Abbruch führen.

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

Konfigurationen (Ihre Erweiterung/Ekins Einstellungen)
Standardmäßig setzt extension.json voraus, dass Ihre Konfigurationseinstellungen mit einem "wg" Präfix beginnen. Wenn das nicht der Fall ist, können Sie das Präfix mit einem speziellen Schlüssel ü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:

Value
The value of the configuration moved to this place. This is the only required key for a configuration object.

Path
The boolean value of the  key identifies, if the value of the configuration option should be interpreted as a filesystem path, relative to the extension directory root. 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
This option is a boolean, which defaults to false, which means, that the configuration option and the value is marked as "private". This value is not used anywhere at the moment, take a look to the outlook to find out more about this option.

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</tt> angeben, wenn Sie PHP-Code ausführen müssen. Der Wert sollte auf einen gültigen PHP callable gesetzt werden, zum Beispiel :. wird diesen callback ausführen, nachdem es die extension.json</tt> Datei verarbeitet hat.

Der callback ist keine normale hook Funktion, er läuft in einer frühen Initialisierung-Phase.

Siehe in was alles für die benutzerdefinierte Registrierung erforderlich ist.

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 auch eine composer.json</tt> geben. Hier finden Sie eine Manual:Composer.json bewährte Vorgehensweise. Einige Metadatenfelder in diesen Dateien überlappen (diskutiert in T89456), einschließlich
 * und
 * und

Siehe auch

 * Melden Sie Fehler des MediaWiki-Configuration Projektes.
 * 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.