Manual:Extension registration/Migration

Migration for extension developers

namespace IDs

Since MW 1.30, namespace IDs defined in extension.json can be overwritten locally, by defining the respective constant in LocalSettings.php before loading the extension. Consider for instance the following namespace declaration in a extension.json file:

	"namespaces": [
		{
			"id": 1212,
			"constant": "NS_FOO",
			"name": "Foo"
		},
		{
			"id": 1213,
			"constant": "NS_FOO_TALK",
			"name": "Foo_Talk"
		}
	]

This would per default cause the constant NS_FOO to be defined to have the value 1212. However, this can be overwritten by defining the respective constant in LocalSettings.php:

define( 'NS_FOO', 6688 );
define( 'NS_FOO_TALK', 6689 );
wfLoadExtension( "Foo" );

This would cause the "Foo" namespace to be registered with the ID 6688 instead of 1212. When overriding namespace IDs, don't forget that all talk namespaces must have odd IDs, and the ID of the talk namespace must always be the subject namespace's ID plus one.

See also the extension registration wall of sadness (now superpowers).

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:

$ cd core
$ php maintenance/convertExtensionToRegistration.php extensions/MassMessage/MassMessage.php
$ php maintenance/convertExtensionToRegistration.php skins/MonoBook/MonoBook.php --skin

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 happens to not break wikis during the upgrade process.

<?php
if ( function_exists( 'wfLoadExtension' ) ) {
	wfLoadExtension( 'FooBar' );
	// Keep i18n globals so mergeMessageFileList.php doesn't break
	$wgMessagesDirs['FooBar'] = __DIR__ . '/i18n';
	$wgExtensionMessagesFiles['FooBarAlias'] = __DIR__ . '/FooBar.alias.php';
	wfWarn(
		'Deprecated PHP entry point used for the FooBar extension. ' .
		'Please use wfLoadExtension() instead, ' .
		'see https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Extension_registration for more details.'
	);
	return;
} else {
	die( 'This version of the FooBar extension requires MediaWiki 1.29+' );
}

Or skins

<?php
if ( function_exists( 'wfLoadSkin' ) ) {
	wfLoadSkin( 'FooBar' );
	// Keep i18n globals so mergeMessageFileList.php doesn't break
	$wgMessagesDirs['FooBar'] = __DIR__ . '/i18n';
	$wgExtensionMessagesFiles['FooBarAlias'] = __DIR__ . '/FooBar.alias.php';
	wfWarn(
		'Deprecated PHP entry point used for the FooBar skin. Please use wfLoadSkin instead, ' .
		'see https://www.mediawiki.org/wiki/Extension_registration for more details.'
	);
	return;
} else {
	die( 'This version of the FooBar skin requires MediaWiki 1.25+' );
}

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, so you can put comments in those parts of the JSON file. For example:

{
	"@note": "This file must be kept in sync with LocalisationUpdate.php",
	"@name": ...

Version 1 of the extension.json format also allowed @note in config section, but this is no longer recommended or supported in version 2. description field of the config variable should be used instead.

This should only be used for brief notes and comments.