Manual:Extension registration/cs

Registrace rozšíření je mechanismus, který používá MediaWiki pro načítání rozšíření a vzhledů. Konfigurační data vložíte do souboru s názvem  nebo   do kořenového adresáře vašeho rozšíření nebo vzhledu a MediaWiki je použije k registraci rozšíření a vzhledů.

Migrace pro správce webu
Před MediaWiki 1.25 byla konfigurace pro rozšíření a vzhledy prováděna v souboru PHP pomocí názvu přípony nebo vzhledu, například  nebo.

To lze převést na:

Pokud svá rozšíření uchováváte na jiném místě než, musíte přepsat  nebo použít druhý parametr   k určení adresáře, ve kterém chcete rozšíření najít. Pokud vaše vzhledy nejsou v, musíte přepsat špatně pojmenované. Toto je nutné provést před načtením jakýchkoli rozšíření nebo vzhledů.

Migrace pro vývojáře rozšíření
Od MW 1.30 mohou být ID jmenného prostoru definovaná lokálně v  před načtením rozšíření přepsána definováním příslušné konstanty v. Zvažte například následující deklaraci jmenného prostoru v souboru :

To by ve výchozím nastavení způsobilo, že konstanta NS_FOO bude definována na hodnotu 1212. Toto však lze přepsat definováním příslušné konstanty v LocalSettings.php:

To by způsobilo, že jmenný prostor "Foo" bude registrován s ID 6688 namísto 1212. Při přepisování ID jmenného prostoru nezapomeňte, že všechny jmenné prostory talk musí mít lichá ID a ID jmenného prostoru talk musí být vždy ID jmenného prostoru subjektu plus jedna.


 * Viz také registrace na stránce rozšíření (nyní superschopnosti).

Skript  vám pomůže s migrací ze vstupních bodů PHP do souboru metadat JSON. Pokud vaše rozšíření podporuje starší verze MediaWiki, měli byste si ponechat vstupní bod PHP, dokud neukončíte podporu pro tyto starší verze.

Ukázky příkazových řádků:

Možná budete muset odinstalovat své rozšíření z, pokud se zobrazí chyby, že konstanty nebo funkce nelze předefinovat. Soubor vstupního bodu PHP (FooBar.php) byste měli nahradit něčím podobným, jako je následující, aby nedošlo k přerušení wiki během procesu upgradu.

Nebo vzhledů

Uchovávání dokumentace
Vstupní body PHP mají obvykle nějakou dokumentaci konfiguračních nastavení, která je užitečná a neměla by se ztratit. Bohužel JSON nepodporuje komentáře. Doporučuje se přenést konfigurační dokumentaci do souboru  v úložišti rozšíření. Konfiguraci byste také měli zdokumentovat na wiki na stránce Rozšíření:MyExtension. Část dokumentace je také možné zahrnout přímo do souboru. Registrace rozšíření ignoruje jakýkoli klíč v  začínající znakem ' ' ve struktuře nejvyšší úrovně, takže do těchto částí souboru JSON můžete vkládat komentáře. Například:

Verze 1 formátu  také umožňovala   v sekci , ale to již není doporučeno ani podporováno ve verzi 2. Místo toho by mělo být použito pole  konfigurační proměnné.

Toto by mělo být použito pouze pro krátké poznámky a komentáře.

Funkce
Pokud načítáte velký počet rozšíření, registrace rozšíření poskytne zvýšení výkonu, pokud máte nainstalováno APC (nebo APCu). Rozšíření načtená společně s  (s množným číslem -s) budou uložena do mezipaměti společně.

Atributy
Opakujícím se problémem je, jak něco "zaregistrovat" s jinou příponou. Obvykle to znamenalo, že jste museli načíst jedno rozšíření před druhým. VisualEditor má například, který umožňuje rozšířením přidávat své moduly. Ve vstupním bodě VisualEditoru však má:

This means that if any extension appends to the array before VisualEditor is loaded, VE will wipe out its entry in this array. Some extensions depended upon a specific load order, others hacked around this with. Extension registration solves this problem with "attributes". In the Math extension, its  would have something like:

Starting with manifest version 2, the attributes need to be defined in the separate 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!

When VisualEditor wants to access this attribute it uses:

Requirements (dependencies)
Extension registration has a  section, which acts similar to Composer's   section. It allows an extension developer to specify several requirements for the extension, such as a specific MediaWiki version (or greater/less than) or another extension/skin. For example, to add a dependency on a MediaWiki version that is greater than 1.26.0, you can add the following code to :

The key of the  object is the name of the dependency (prior to MediaWiki 1.29.0 only   was supported), the value is a valid version constraint (the format has to match the one used by composer).

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

In MediaWiki 1.33.0(?!??) and above you can also add dependencies on PHP like so:

Check if an extension is loaded without actually requiring it
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.

To implement a standardized way of checking, if an extension is loaded or not (without the need of extra work in an extension that is a soft-dependency in another one), extension registration can be used. It implements an  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:

Since MediaWiki 1.32 it's also possible to check if an extension is loaded and satisfies a given composer version constraint:

If you would like to check if a specific version of an extension is loaded in earlier versions of MediaWiki, information like that can be extracted with the  method, which returns credit information for all loaded extensions. Example:

Alternatively, if the extension B defines a special constant meant for this purpose during loading, it is possible to check, if it is defined:

A more brittle way, that should be avoided is to check if a specific class of extension B exists or not, e.g. using this code:

This might break if the extension exists in the file system but is not loaded, e.g. if composer was used for autoloading. If the class was renamed or ceases to exist (e.g. because it is not package public) this will also break.

In general it is preferred to share code via composer components instead of extensions. If the classes of an extension only need to exist, but the extension does not need to be configured nor loaded, for what you want to do, that is a strong indicator that that code should be split off into a composer component you should depend on instead.

Configs (Your extension/skins settings)
By default,  assumes that your config settings start with a "wg" prefix.

If that's not the case, you can override the prefix by using a special key:

That would use a prefix of "eg", and set the global variable  to 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 with much more detail. 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. It may also be used as tooltip text on the parameters section of the extension infobox on the MediaWiki.org extension description page. 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 future!

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 allow 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 will 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.

Customizing registration

 * See Manual:Extension.json/Schema.

Also composer.json
If an extension or skin has library dependencies, it may have a  file as well, see. Use the  field to make MediaWiki use Composer's autoloading when appropriate.

Some metadata fields overlap between  and   (discussed in ), including :
 * and
 * and