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á:

To znamená, že pokud se nějaké rozšíření připojí k poli před načtením VisualEditoru, VE vymaže svůj záznam v tomto poli. Některá rozšíření závisela na konkrétním pořadí načítání, jiná to obcházela pomocí. Registrace rozšíření řeší tento problém pomocí "atributů". V rozšíření Math by jeho  mělo něco jako:

Počínaje verzí 2 musí být atributy definovány v samostatné sekci.

musí být objekt s názvem rozšíření jako klíčem a objektem párů atribut/hodnota jako hodnotou. Pamatujte, že klíč v podobjektu nesmí obsahovat název rozšíření!

Když chce VisualEditor získat přístup k tomuto atributu, použije:

Požadavky (závislosti)
Registrace rozšíření má sekci  (vyžaduje), která funguje podobně jako sekce   Composeru. Umožňuje vývojáři rozšíření specifikovat několik požadavků na rozšíření, jako je konkrétní verze MediaWiki (nebo vyšší/menší než) nebo jiné rozšíření/vzhled. Chcete-li například přidat závislost na verzi MediaWiki, která je větší než 1.26.0, můžete do  přidat následující kód:

Klíč objektu  je název závislosti (před MediaWiki 1.29.0 byla podporována pouze  ), hodnota je platné omezení verze (formát je podle volby autora).

V MediaWiki 1.29.0 a vyšší můžete také přidat závislosti na vzhledech a dalších rozšířeních, jako jsou:

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

Zkontrolujte, zda je rozšíření načteno, aniž by bylo ve skutečnosti vyžadováno
Mnoho rozšíření může poskytovat funkce, které fungují pouze v případě, že je načteno i jiné rozšíření, aniž by tuto funkci skutečně potřebovali pro fungování základní funkce rozšíření. Jako příklad: Pokud je načteno rozšíření B, může rozšíření A poskytovat skutečný WYSIWYG editor, jinak bude používat jednoduchou textovou oblast. Rozšíření A může těžit z rozšíření B (pokud je načteno), ale ke správnému fungování nevyžaduje, aby bylo načteno. Za tímto účelem obvykle zkontrolujete, zda je rozšíření načteno, spíše než jej přidáte jako tvrdou závislost.

Pro implementaci standardizovaného způsobu kontroly, zda je rozšíření načteno nebo ne (bez nutnosti práce navíc v rozšíření, která je v jiném rozšíření měkkou závislostí), lze použít registraci rozšíření. Implementuje metodu, která vrací jednoduchý boolean, pokud je rozšíření načteno nebo ne (aby to fungovalo, musí být rozšíření načteno s registrací rozšíření). Příklad:

Od MediaWiki 1.32 je také možné zkontrolovat, zda je rozšíření načteno a zda splňuje dané omezení verze:

Pokud byste chtěli zkontrolovat, zda je v dřívějších verzích MediaWiki načtena konkrétní verze rozšíření, lze podobné informace extrahovat pomocí metody, která vrací informace o kreditu pro všechna načtená rozšíření. Příklad:

Alternativně, pokud rozšíření B definuje speciální konstantu určenou pro tento účel během načítání, je možné zkontrolovat, zda je definována:

Křehčím způsobem, kterému je třeba se vyhnout, je zkontrolovat, zda specifická třída rozšíření B existuje nebo ne, např. pomocí tohoto kódu:

To může přestat fungovat, pokud přípona existuje v systému souborů, ale není načtena, např. pokud byl pro automatické načítání použit composer. Pokud byla třída přejmenována nebo přestane existovat (např. protože není balíček public), dojde také k přerušení.

Obecně je upřednostňováno sdílení kódu prostřednictvím komponent pro composer namísto rozšíření. Pokud třídy rozšíření potřebují pouze existovat, ale rozšíření nemusí být konfigurováno ani načteno, pro to, co chcete dělat, je to silný indikátor toho, že by tento kód měl být rozdělen na komponentu composer, na kterou byste se měli spolehnout. namísto.

Configs (Vaše nastavení rozšíření/vzhledů)
Ve výchozím nastavení  předpokládá, že vaše konfigurační nastavení začíná předponou "wg".

Pokud tomu tak není, můžete předponu přepsat pomocí speciálního klíče:

To by použilo předponu "eg" a nastavilo globální proměnnou  na hodnotu true.

Počínaje zveřejněním verze 2 poskytuje konfigurační sekce registrace rozšíření mnohem více funkcí a umožňuje vám popsat možnosti konfigurace mnohem podrobněji. Namísto jediného klíče -> úložiště hodnot pro možnosti konfigurace můžete také přidat následující informace.

Obecná struktura  se mírně mění na následující, více objektově orientovanou verzi:

Hodnota
Hodnota konfigurace se přesunula na toto místo. Toto je jediný požadovaný klíč pro konfigurační objekt.

Cesta
Booleovská hodnota klíče  identifikuje, zda má být hodnota konfigurační volby interpretována jako cesta souborového systému vzhledem ke kořenu adresáře rozšíření. Pokud je například hodnota konfigurace  a   je pravdivá, skutečná hodnota bude.

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