Manual:Erweiterungsregistrierung
| MediaWiki Version: | ≥ 1.25 Gerrit change 166705 |
Extension registration ist das Verfahren, das MediaWiki zum Laden von Erweiterungen und Skins nutzt.
Die Konfigurationsdaten werden in eine Datei namens extension.json oder skin.json geschrieben, welche im Stammverzeichnis der Erweiterung oder des Skins abgelegt wird. MediaWiki verwendet diese Dateien, um Erweiterungen und Skins zu registrieren.
If you were looking for documentation on installing extensions instead, see this guide.
Funktionen
Eigenschaften
Ein immer wieder auftretendes Problem ist, wie man etwas bei einer anderen Erweiterung "registriert".
For instance, the VisualEditor (VE) extension offers the $wgVisualEditorPluginModules hook, which other extensions can use to register a module with VE.
If the Math extension were to register a module with VE, it would have something like the following in its extension.json:
| manifest version 2 | manifest version 1 |
|---|---|
The attributes 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!
{
"attributes": {
"VisualEditor": {
"PluginModules": [
"ext.math.visualEditor"
]
}
},
"manifest_version": 2
}
|
Manifest version 1 does not have a separate section for attributes:
{
"VisualEditorPluginModules": [
"ext.math.visualEditor"
]
}
|
Wenn VisualEditor auf dieses Attribut zugreifen möchte, würde es folgendes verwenden:
ExtensionRegistry::getInstance()->getAttribute( 'VisualEditorPluginModules' );
Anforderungen (Abhängigkeiten)
Extension registration verfügt über einen requires-Abschnitt, der sich ähnlich zu Composers require-Abschnitt verhält.
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 extension.json eingefügt werden: [1]
{
"requires": {
"MediaWiki": ">= 1.26.0"
}
}
Der Schlüssel des requires Objekts ist der Name der Abhängigkeit ist (vor MediaWiki 1.29.0 war nur MediaWiki unterstützt), der Wert ist eine gültige Versions-Einschränkung (das Format muss dem von Composer verwendeten entsprechen).
In MediaWiki 1.29.0 und darüber können auch Abhängigkeiten von Skins und anderen Erweiterungen wie folgt hinzugefügt werden:
{
"requires": {
"MediaWiki": ">= 1.29.0",
"extensions": {
"ExampleExtension": "*"
},
"skins": {
"ExampleSkin": "*"
}
}
}
- Die Erweiterungen und Skins, die hier angegeben sind, müssen ebenfalls das Extension-registration-System verwenden, das auf dieser Seite beschrieben wird, damit dies funktioniert.
- Der String der hinzugefügt wurde, um die Erweitrung oder Skins anzugeben, müssen mit dem String in dem "name"-Feld der entsprechenden "extension.json" oder des entsprechenden "skin.json" identisch sein.
- Für Erweiterungen, die Wikimedias Continuous integration verwenden, müssen Abhängigkeiten auch zu zuul/parameter_functions.py hinzugefügt werden.
In MediaWiki 1.33.0(?!??) and above you can also add dependencies on PHP like so:
{
"requires": {
"MediaWiki": ">= 1.33.0",
"platform": {
"php": ">= 7.0.3"
}
}
}
Überprüfe, ob eine Erweiterung geladen ist, ohne sie tatsächlich zu benötigen
Many extensions may provide features that work only if another extension is loaded too, without really needing this feature for the core extension function to work. As an example: If extension B is loaded, extension A can provide a real WYSIWYG editor, otherwise it will use a simple textarea. Extension A can profit from extension B (if it is loaded), but doesn't require it to be loaded to work properly. For this, you generally check, if the extension is loaded, rather than adding it as a hard dependency.
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 isLoaded-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:
It implements an isLoaded method, which returns a simple boolean, if the extension is loaded or not (the extension needs to be loaded with extension registration for this to work).
Example:
if ( ExtensionRegistry::getInstance()->isLoaded( 'ExtensionB' ) ) {
// do things only, if extension B is loaded
}
| MediaWiki Version: | ≥ 1.32 Gerrit change 455752 |
Seit MediaWiki 1.32 ist es ebenfalls möglich, zu prüfen, ob eine Erweiterung geladen ist und eine angegebene Composer-Versionseinschränkunge erfüllt.
if ( ExtensionRegistry::getInstance()->isLoaded( 'ExtensionB', '>=1.2' ) ) {
// do things only, if extension B is loaded and has a version of 1.2 or greater.
}
Möchtest du in älteren Versionen von MediaWiki prüfen, ob eine Erweiterung geladen ist, kannst du diese Information mit der getAllThings-Methode erhalten, die auch Danksagungsinformationen (Credits) für alle geladenen Erweiterungen enthält. Zum Beispiel:
$bVersion = ExtensionRegistry::getInstance()->getAllThings()['ExtensionB']['version'] ?? null;
if ( $bVersion !== null && version_compare( $bVersion, '2.1.0', '>=' ) ) {
// do things only, if extension B is loaded and has a version number greater than or equal to 2.1.0
}
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:
if ( defined( 'ExtensionBVersion' ) ) { // You could also check for a version, if the constant holds the version
// do things only, if extension B is loaded
}
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:
if ( class_exists( 'ExtensionBHooks' ) ) {
// do things only, if extension B its classes exist
}
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 (Erweiterungs/Skin-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:
{
"config": {
"_prefix": "eg",
"MyExtSetting": true
}
}
Das verwendet das Präfix "eg" und setzt die globale Variable $egMyExtSetting auf true.
Seit manifest version 2 stellt der Einstellungs-Abschnitt der Extension registration deutlich mehr Features zur Verfügung und erlaubt dir, die Einstellungsmöglichkeiten viel detaillierter zu beschreiben. Anstelle eines einzelnen „Schlüssel -> Wert“-Feldes für Einstellungsmöglichkeiten kannst du auch die folgenden Informationen ergänzen:
Die allgemeine Struktur der config verändert sich ein wenig zu der folgenden, stärker objektorientierten Version:
{
"config_prefix": "eg",
"config": {
"MyExtSetting": {
"value": true,
"path": false,
"description": "The description for the configuration",
"descriptionmsg": "myextension-config-myextsetting",
"public": true
}
},
"manifest_version": 2
}
value
Der Konfigurationswert wird an diesen Ort verschoben. Dies ist der einzige notwendige Schlüssel eines Konfigurationsobjektes.
path
Der boolsche Wert des path-Schlüssels gibt an, ob der Wert der Einstellungsoption als Pfad im Dateisystem interpretiert werden soll, relativ zum Wurzelverzeichnis der Erweiterung.
Z. B., wenn der Wert der Einstellung myFile.png ist und path true ist, ist der tatsächliche Wert path.
description
Der description-Schlüssel für eine Einstellung kann einen nicht lokalisierten String erhalten, welcher verwendet werden kann, um sie anderen Entwicklern oder Benutzern (Systemadministratoren) deriner Erweiterung zu erklären.
It may also be used as tooltip text on the parameters section of the extension infobox on the MediaWiki.org extension description page.
Der Wert des description-Schlüssel wird normalerweise nicht im Wiki angezeigt; sieh dir allerdings den Ausblick an, um mehr Informationen darüber zu erhalten, wie dieses Feature in Zukunft verwendet werden könnte!
descriptionmsg
Es ist ebenfalls möglich, einen Nachrichten-Schlüssel (descriptionmsg) als Beschreibung in MediaWikis internes Lokalisierungssystem hinzufügen, der in Zukunft verwendet werden wird, um die Beschreibung im Wiki anzuzeigen.
public / private
Diese Option ist ein boolscher Wert, der standardmäßig auf false gesetzt ist, was bedeutet, dass die Einstellung und ihr Wert als "private" markiert sind. Dieser Wert wird im Moment nirgendwo verwendet; sieh dir den Ausblick an, um mehr über diese Option herauszufinden.
Ausblick
Die oben genannten Änderungen sind auch als Vorbereitungen für ein verbresserungs Konfigurations-Management in MediaWiki zu verstehen. Die obigen Informationen erlauben unns bspw., diese Optionen von Erweiterungen im MediaWiki-Benutzerinterface anzuzeigen. Zu diesem Zweck werden die lokalisierte Beschreibung (descriptionmsg und description) sowie der Hinweis, ob die Option gezeigt werden soll oder nicht (public) benötigt.
Automatisiertes Auffinden von Unit-Tests
MediaWiki erlaubt jeder Erweiterung, phpunit-Tests zu registrieren. Ohne Erweiterungsregistrierung wäre es nötig, einen Hook-Handler für den UnitTestsList-Hook zu registrieren, was in etwa so aussehen würde:
public static function onUnitTestsList( array &$paths ) {
$paths[] = __DIR__ . '/tests/phpunit/';
}
(wie auf der Handbuch-Seite beschrieben). Dieser Code ist allerdings für viele Erweiterungen identisch, sodass man ihn als unnötige Codedopplung bezeichnen könnte.
Wenn eine Erweiterung Erweiterungsregistrierung verwendet und die phpunit-Tests sich im tests/phpunit/-Unterverzeichnis der Erweiterung befinden, wird der phpunit-Wrapper von MediaWiki diese Unit-Tests mithilfe von Erweiterungsregistrierung automatisiert finden.
Daher ist es nicht mehr nötig, diesen Hook zu registrieren und anzugeben, dass die Unit-Tests im Standardverzeichnis gespeichert sind.
Tracking categories
| MediaWiki Version: | ≥ 1.25 |
Since MediaWiki 1.25, any categories that an extension wants listed at Special:TrackingCategories must be registered in extension.json:
{
"TrackingCategories": [
"myextension-tracking-category"
]
}
myextension-tracking-category is a system message which holds the category name, and is added to pages with Parser::addTrackingCategory().
Anpassen der Registrierung
Siehe auch composer.json
Wenn eine Erweiterung oder Skin Bibliotheksabhängigkeiten hat, kann es auch eine composer.json-Datei geben, siehe Manual:Composer.json best practices. Verwende das load_composer_autoloader -Feld, damit MediaWiki das automatische Laden von Composer verwendet, wenn dies angebracht ist.
Some metadata fields overlap between extension.json and composer.json (discussed in task T89456), including :
urlandhomepagelicense-nameandlicense
Code Stewardship
- Gewartet von Unknown or Unassigned[Maintainers page].
- Problem-Tracker: Phabricator MediaWiki-Configuration (Problem melden)
Siehe auch
Dokumentation
- Handbuch:extenstion.json/Schema
docs/extension.schema.v2.jsonist das Schema fürextension.json(und skin.json).
- Bekannte Einschränkungen
- Überblick über die Architektur
- Migration guide - some recommendations on updating older extensions
Feedback
- Melde Fehler dem MediaWiki-Configuration-Projekt.
- RfC zur Umsetzung der Registrierung von Erweiterungen