Manual:Skin autodiscovery

From mediawiki.org
Other languages:
English  â€˘ 中文

Skin autodiscovery was a legacy skin installation mechanism used by MediaWiki since very early versions (around 2004) which has been removed in MediaWiki 1.25, after being superseded by an explicit installation method in MediaWiki 1.12 and after being officially deprecated in MediaWiki 1.23. See gerrit change Ib4bdda5ed3c133fce0113eb17fa39950aa812f87 for details.

MediaWiki 1.23 and 1.24 will emit warnings in production if a skin using the deprecated mechanism is found: 

A skin using autodiscovery mechanism, $aSkin, was found in your skins/ directory.
The mechanism will be removed in MediaWiki 1.25 and the skin will no longer be recognized.
See https://www.mediawiki.org/wiki/Manual:Skin_autodiscovery for information how to fix this.

Skins using autodiscovery will continue working in the 1.23 LTS release (with the aforementioned warnings). If you upgrade from one LTS version to the next one, you will even have time until 1.27 LTS is released, giving you plenty of time to migrate.

How did autodiscovery work?[edit]

It used to be possible to just put a <name>.php file in MediaWiki's skins/ directory, which would be loaded and expected to contain the Skin<name> class. It has been discouraged for a long time because of the limitations of this method (inability to add localisation messages, ResourceLoader modules, etc. without cluttering LocalSettings.php) and awkwardness in managing such skins ($wgSkipSkins had to be introduced to make it possible to disable an installed skin).

Since MediaWiki 1.23 this mechanism is officially deprecated.

What should I use instead?[edit]

The recommended way to create a skin is detailed on Manual:Skinning.

In short, you would create a subdirectory under skins/ containing your skin's PHP code and assets, define certain skin properties in the <name>.php file, which now is located inside that subdirectory, and require_once it like you do when installing extensions.

This has already been supported, with minor modifications, since MediaWiki 1.12.

Where do I get a new version of my skin?[edit]

The bundled skins which come with MediaWiki (like Vector or MonoBook) will continue to be updated with the MediaWiki Core. When you upgrade your installation to MediaWiki 1.24 or newer, you will also get a new version of these skins. (You should then remove the old copies from the skins/ folder, see Manual:Upgrading#Files remaining that may cause errors.)

If the skin you use was written by someone else (and you don't maintain it yourself), first try to find out if its maintainer has updated it already. Most of the skins that have description pages here on mediawiki.org (Category:All skins) use the new mechanism already.

If you maintain the skin yourself, or if you want to help its maintainer migrating it, go ahead with the next section.

Migration guide[edit]

Steps needed to switch a skin to the new mechanism, in short:

  1. Move the MySkin.php file into the MySkin directory with skin resources (or create one if it doesn't exist). In the past, skins often used camel-case for the PHP file name and lower-case for the directory. You should now make both names exactly the same - preferred is the camel-case version.
    • Optionally, split the classes defined by your skin (SkinMySkin, MySkinTemplate) to separate files and inside MySkin.php register them in $wgAutoloadClasses like so: $wgAutoloadClasses['SkinMySkin'] = __DIR__ . '/SkinMySkin.php'; and $wgAutoloadClasses['MySkinTemplate'] = __DIR__ . '/MySkinTemplate.php';. This will make the structure of the main file clearer, especially if you have a lot of code or used additional features (see below).
  2. Adjust paths in the PHP files if they were relative to file's directory, rather than $IP or $wgStyleDirectory.
  3. Add the skin to $wgValidSkinNames in the MySkin.php file, like so: $wgValidSkinNames['myskin'] = 'MySkin';. Note the capitalisation: The key is lower-case, the value is camel-case as in the class name "SkinMySkin" of the skin.
  4. If you used additional MediaWiki features:
    • If you have defined ResourceLoader modules for your skin (like $wgResourceModules['skins.myskin.styles'] = …), put them in the MySkin.php file as well. Remember to adjust the paths:
    1. Remove any prefixed "MySkin/" from the inclusion of the single CSS/JS files.
    2. Adjust the value of localBasePath and set it to __DIR__.
    3. Remove the line 'remoteBasePath' => &$GLOBALS['wgStylePath'],.
    4. Instead, add 'remoteSkinPath' => 'MySkin',.
    • If you have defined localization messages for your skin (using $wgMessagesDirs or, if you still use the old message format, using $wgExtensionMessagesFiles), move the messages file/directory into the MySkin directory, and change the definition (which then looks like $wgMessagesDirs['MySkin'] = __DIR__ . '/i18n'; or $wgExtensionMessagesFiles['MySkin'] = __DIR__ . '/MySkin.i18n.php';) and place it in the MySkin.php file.
  5. Add a require_once "$IP/skins/MySkin/MySkin.php"; to your LocalSettings.php file (similarly to how it's done for extensions).

As mentioned above, the "migrated" skins will work with your MediaWiki 1.23 installation, as well as many versions back.

In addition to the changes named above, since MediaWiki 1.25 there's a new way to register skins and extensions. See Manual:Extension registration.

Example[edit]

This patch set exemplarily shows how this migration works: gerrit:138795

See also[edit]

Retrieved from "https://www.mediawiki.org/w/index.php?title=Manual:Skin_autodiscovery&oldid=6415593"