Manual:Erweiterungsregistrierung
| MediaWiki Version: | ≥ 1.25 Gerrit change 166705 |
Extension registration ist das Verfahren, das MediaWiki zum Laden von Erweiterungen und Skins nutzt.
Du legst Konfigurationsdaten in einer Datei mit dem Namen extension.json oder skin.json im Stammverzeichnis deiner Erweiterung oder deines Skins ab, und MediaWiki benutzt diese, um Erweiterungen und Skins zu registrieren.
Wenn du stattdessen nach einer Dokumentation zur Installation von Erweiterungen suchst, siehe diese Anleitung.
Funktionen
Eigenschaften
Mit "Attributen" kannst du etwas, z. B. ein Modul, bei einer anderen Erweiterung registrieren.
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 |
|---|---|
Der attributes-Knoten muss ein Objekt mit dem Erweiterungsnamen als Schlüssel und einem Objekt mit Attribut/Wertpaaren als Wert sein. Beachte, dass der Schlüssel des Unterobjekts nicht den Namen der Erweiterung enthalten darf!
{
"attributes": {
"VisualEditor": {
"PluginModules": [
"ext.math.visualEditor"
]
}
},
"manifest_version": 2
}
|
Manifest Version 1 verfügt nicht über einen separaten Abschnitt für 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 eine Abhängigkeit von einer MediaWiki-Version größer als 1.26.0 hinzuzufügen, kannst du den folgenden Code zu extension.json hinzufügen: [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
Viele Erweiterungen bieten Funktionen, die nur funktionieren, wenn auch eine andere Erweiterung geladen ist, ohne dass diese Funktion wirklich für die Kernfunktion der Erweiterung benötigt wird. 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. Dazu überprüfst du in der Regel, ob die Erweiterung geladen ist, anstatt sie als feste Abhängigkeit hinzuzufügen.
Um eine standardisierte Methode zur Überprüfung zu implementieren, ob eine Erweiterung geladen ist oder nicht (ohne zusätzliche Arbeit in einer Erweiterung, die eine Soft-Abhängigkeit in einer anderen ist), kann die Registrierung der Erweiterung verwendet werden.
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).
Beispiel:
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 auch möglich, zu prüfen, ob eine Erweiterung geladen ist und einer bestimmten Composer-Versionsbeschränkung entspricht:
if ( ExtensionRegistry::getInstance()->isLoaded( 'ExtensionB', '>=1.2' ) ) {
// do things only, if extension B is loaded and has a version of 1.2 or greater.
}
Wenn du überprüfen möchtest, ob eine bestimmte Version einer Erweiterung in früheren Versionen von MediaWiki geladen ist, können solche Informationen mit der Methode getAllThings extrahiert werden, die Guthabeninformationen für alle geladenen Erweiterungen zurückgibt. 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": "Die Beschreibung für die Konfiguration",
"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.
Zudem kann er als Tooltip-Text im Abschnitt Parameter der Infobox der Erweiterung auf der MediaWiki.org-Erweiterungsbeschreibungsseite verwendet werden.
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 zudem vorbereitende Schritte für ein verbessertes Konfigurationsmanagement in MediaWiki. Die oben genannten Änderungen ermöglichen es uns z.B., die Konfigurationsoptionen von Erweiterungen in der MediaWiki-Benutzeroberfläche zu veröffentlichen. Dafür brauchen wir die lokalisierte Beschreibungsmeldung (descriptionmsg und description) und die Angabe, ob die Konfigurationsoption angezeigt werden soll oder nicht (public).
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-Kategorien
| MediaWiki Version: | ≥ 1.25 |
Seit MediaWiki 1.25 müssen alle Kategorien, die eine Erweiterung bei Special:TrackingCategories gelistet haben möchte, bei extension.json registriert werden:
{
"TrackingCategories": [
"myextension-tracking-category"
]
}
myextension-tracking-category is a system message which holds the category name. The extension adds it to pages by calling Parser::addTrackingCategory().
Anpassen der Registrierung
Siehe auch composer.json
Wenn eine Erweiterung oder ein Skin Bibliotheksabhängigkeiten hat, kann sie/er auch eine composer.json-Datei haben, siehe Manual:Composer.json best practices. Verwende das Feld load_composer_autoloader, um MediaWiki zu veranlassen, das automatische Laden des Composers zu verwenden, wenn es 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
- Migrationsleitfaden - some recommendations on updating older extensions
Feedback
- Melde Fehler dem MediaWiki-Configuration-Projekt.
- RfC zur Umsetzung der Registrierung von Erweiterungen