Manual:Extension registration/en

Extension registration is the mechanism that MediaWiki uses to load extensions and skins. You put configuration data in a file named  or   in the root directory of your extension or skin, and MediaWiki uses this to register extensions and skins.

Before MediaWiki 1.25, configuration for extensions and skins was done in a PHP file using the extension's or skin's name, for example  or. This usage is deprecated, and developers of existing extensions and skins should start migrating to the new format.

Migration for system administrators
Previously your LocalSettings.php would include something like:

This can be converted to:

If you keep your extensions in a location different from $IP/extensions, you need to override. If your skins are not in $IP/skins you need to override the poorly named. This must be done before you load any extensions or skins.

or if you want to do it within one line:

Migration for extension developers
The script maintenance/convertExtensionToRegistration.php helps you migrating from PHP entry points to a JSON metadata file. If your extension supports older versions of MediaWiki, you should keep your PHP entry point FooBar/FooBar.php until you drop support for those older versions.

Sample command lines:

You may need to uninstall your extension from LocalSettings.php if you receive errors that constants or functions cannot be redefined. You should replace your PHP entry point file (FooBar.php) with something like the following to not break wikis during the upgrade process. If you need to keep pre-1.25 compatibility, remove the die line and instead keep the old PHP setup.

Or skins

Retaining documentation
PHP entry points usually have some documentation of configuration settings that is useful and shouldn't be lost. Unfortunately JSON doesn't support comments. It is recommended that you transfer configuration documentation to a README file in the extension's repository. You should also document configuration on-wiki in your Extension:MyExtension page. It is possible to include some documentation directly in the extension.json file as well. Extension registration ignores any key in extension.json starting with ' ' in the top-level structure or under, so you can put comments in those parts of the JSON file. For example:

This should only be used for brief notes and comments.

Features
If you are loading a large number of extensions, extension registration will provide a performance boost as long as you have APC (or APCu) installed. Extensions that are loaded together with  (with plural -s) will be cached together.

Attributes
A recurring problem is how to "register" something with another extension. Usually this meant that you had to load one extension before another. For example, VisualEditor has a  which allows extensions to add their modules. However, in VisualEditor's entry point it has:

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 extension.json</tt> would have something like:

When VisualEditor wants to access this attribute it uses:

Requirements (Dependencies)
Extension regsitartion 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 (not implemented yet, see ). To, e.g., add a dependency of an extension to 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 (currently only MediaWiki supported), the value is a valid version constraint (the format has to match the one used by composer).

Customizing registration
Sometimes extensions need to do non-standard things during registration, or are just very complex. You can specify a 'callback' key in your extension.json</tt> if you need to execute some PHP code. The value should be set to a valid PHP callable, for example:. will execute this callback after it processes the extension.json</tt> file.

The callback isn't a normal hook function, it runs in early initialization.

See for what sort of things may require custom registration.

Also composer.json
If an extension or skin has library dependencies, it may have a composer.json</tt> file as well, see Manual:Composer.json best practices. Some metadata fields in these files overlap (discussed in T89456), including
 * and
 * and