MediaWiki

Manual:拡張機能の登録

This page is a translated version of the page Manual:Extension registration and the translation is 36% complete.
Languages:
拡張機能:
外装:
extension.json はここにリダイレクトされます。仕様の一覧は、Extension.json/スキーマを直接参照してください。
MediaWiki バージョン:
≧ 1.25
Gerrit change 166705

拡張機能の登録 (Extension registration) は、MediaWiki が拡張機能や外装を読み込むときに使うしくみです。 設定データは、extension.json や skin.json の名前をつけたファイルに書いて拡張機能や外装のルートディレクトリに置きます。MediaWikiはこれを使って拡張機能や外装を登録します。

拡張機能のインストールに関する説明文書を探している場合は、こちらのガイドを参照してください。

特徴

属性

"Attributes" let you register something, such as a module, with another extension. 例えば、ビジュアルエディター (VE) 拡張機能は VisualEditorPluginModules フックを提供しており、他の拡張機能はこれを使用して VE にモジュールを登録できます。 Math 拡張が VE にモジュールを登録する場合、その extension.json には以下のような記述が含まれているでしょう:

manifest version 2 manifest version 1
attributes ノードは、拡張の名前をキーとして、属性/値のペアを値として持つオブジェクトである必要があります。 下位オブジェクト内のキーには、拡張の名前を含めてはいけません。 
{
	"attributes": {
		"VisualEditor": {
			"PluginModules": [
				"ext.math.visualEditor"
			]
		}
	},
	"manifest_version": 2
}
マニフェスト バージョン 1 には、attributes のための別の節はありません: 
{
	"VisualEditorPluginModules": [
		"ext.math.visualEditor"
	]
}

ビジュアルエディターがこの属性にアクセスするには、以下のように使用します: 

ExtensionRegistry::getInstance()->getAttribute( 'VisualEditorPluginModules' );


要件 (依存関係)

Extension registration has a requires section, which acts similar to Composer's require section. これにより、拡張機能の開発者は、特定のMediaWikiバージョン (またはそれより新しい/古いバージョン) や他の拡張機能/外装のような、拡張機能に対するいくつかの要件を指定できます。 For example, to add a dependency on a MediaWiki version that is greater than 1.26.0, you can add the following code to extension.json: [1] 

{
	"requires": {
		"MediaWiki": ">= 1.26.0"
	}
}

The key of the requires object is the name of the dependency (prior to MediaWiki 1.29.0 only MediaWiki 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: 

{
	"requires": {
		"MediaWiki": ">= 1.29.0",
		"extensions": {
			"ExampleExtension": "*"
		},
		"skins": {
			"ExampleSkin": "*"
		}
	}
}
  • The extensions and skins specified here must also use the extension registrations system described on this page for this to work.
  • The string added to specify the extension or skin must be identical to the string specified in the "name" field of the respective "extension.json" or "skin.json" file.

In MediaWiki 1.32.0 (since Gerrit change 458940) and above you can also add dependencies on PHP like so: 

{
	"requires": {
		"MediaWiki": ">= 1.33.0",
		"platform": {
			"php": ">= 7.0.3"
		}
	}
}


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.

拡張機能が読み込まれているかどうかを確認する標準化された方法を実装するために (他の拡張機能でソフトな依存関係として追加の作業を必要としないように)、拡張機能登録 (extension registration) が使用されます。 これにより、isLoaded メソッドが実装され、拡張が読み込まれているかどうかを示すシンプルな真偽値が返されます (この機能が動作するためには、拡張機能が拡張機能登録 (extension registration) で読み込まれている必要があります)。 例: 

if ( ExtensionRegistry::getInstance()->isLoaded( 'ExtensionB' ) ) {
	// do things only if extension B is loaded
}
MediaWiki バージョン:
≧ 1.32
Gerrit change 455752

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

if ( ExtensionRegistry::getInstance()->isLoaded( 'ExtensionB', '>=1.2' ) ) {
	// do things only if extension B is loaded and has a version of 1.2 or greater.
}

MediaWiki の以前のバージョンで特定のバージョンの拡張が読み込まれているか確認したい場合、そのような情報は getAllThings メソッドを使用して抽出できます。このメソッドは、読み込まれているすべての拡張のクレジット情報を返します。例: 

$bVersion = ExtensionRegistry::getInstance()->getAllThings()['ExtensionB']['version'] ?? null;
if ( $bVersion !== null && version_compare( $bVersion, '2.1.0', '>=' ) ) {
	// do things only if extension B is loaded and has a version number greater than or equal to 2.1.0
}

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

if ( defined( 'ExtensionBVersion' ) ) { // You could also check for a version if the constant holds the version
	// do things only if extension B is loaded
}

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: 

if ( class_exists( 'ExtensionBHooks' ) ) {
	// do things only if extension B's classes exist
}

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.

一般的に、コードは拡張機能ではなく、Composer コンポーネントを通じて共有することが推奨されます。拡張機能のクラスが存在するだけでよく、拡張機能が設定されている必要もなく、読み込まれる必要もない場合、それはそのコードを Composer コンポーネントに分割して、代わりにそのコンポーネントに依存すべき強い指標です。

Configs (Your extension/skins settings)

関連項目: Manual:Configuration for developers および Manual:Extension.json/Schema#config

By default, extension.json 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: 

{
	"config": {
		"_prefix": "eg",
		"MyExtSetting": true
	}
}

That would use a prefix of "eg", and set the global variable $egMyExtSetting to true.

マニフェスト バージョン 2 から、拡張の登録の構成の節は多くの新しい機能を提供し、構成オプションをより詳細に記述できるようになりました。構成オプションのための単一のキー -> 値 ストアを持つ代わりに、次の情報を追加できます。

The general structure of the config changes slightly to the following, more object-oriented version: 

{
	"config_prefix": "eg",
	"config": {
		"MyExtSetting": {
			"value": true,
			"path": false,
			"description": "The description for the configuration",
			"descriptionmsg": "myextension-config-myextsetting",
			"public": true
		}
	},
	"manifest_version": 2
}

value

The value of the configuration moved to this place. This is the only required key for a configuration object.

path

path キーの真偽値は、構成オプションの値が拡張機能ディレクトリのルートを基準としたファイルシステム パスとして解釈されるべきかどうかを識別します。 E.g., if the value of the configuration is myFile.png and the path is true, the actual value will be /path/to/the/wiki/extensions/MyExtension/myFile.png.

description

構成オプションの description キーには、構成オプションを他の開発者や拡張の利用者 (システム管理者) に説明するために使用できる、地域化されていない文字列を保持できます。 これは、拡張機能の説明文書ページの MediaWiki.org 拡張機能のパラメーター節にツールチップ テキストとして使用される場合もあります。 説明キーの値は通常、ウィキのフロントエンドには公開されませんが、今後この機能がどのように使用されるかについては、外観を参照してください。

descriptionmsg

また、説明として MediaWiki の内部の地域化システムのメッセージ キー (descriptionmsg) を追加することもでき、将来的には MediaWiki のインストレーションのフロントエンドで説明を公開するために使用される予定です。

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

Phabricator で追跡中
タスク T155155

上記の変更は、MediaWiki の改善された設定管理のための準備手順でもあります。これらの変更により、例えば、拡張機能の設定オプションを MediaWiki のユーザー インターフェースで公開できるようになります。このためには、地域化された説明メッセージ (descriptionmsg と description) と、設定オプションを公開するかどうかを示す情報 (public) が必要です。

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 UnitTestsList hook, which would look something like: 

public static function onUnitTestsList( array &$paths ) {
	$paths[] = __DIR__ . '/tests/phpunit/';
}

(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. 拡張機能が拡張機能登録 (extension registration) を使用しており、phpunit のテストが拡張機能の tests/phpunit/ 下位ディレクトリにある場合、MediaWiki の phpunit ラッパーは拡張機能登録の助けを借りて単体テストを自動的に発見します。 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.

Tracking categories

関連項目: Help:Tracking categories および Manual:Extension.json/Schema#TrackingCategories
MediaWiki バージョン:
≧ 1.25

Since MediaWiki 1.25, any categories that an extension wants listed at Special:TrackingCategories must be registered in extension.json: 

{
	"TrackingCategories": [
		"myextension-tracking-category"
	]
}

myextension-tracking-category is a system message which holds the category name. The extension adds it to pages by calling Parser::addTrackingCategory().


登録のカスタマイズ

See Manual:Extension.json/Schema#callback.

Also composer.json

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

Some metadata fields overlap between extension.json and composer.json (discussed in T89456), including:

  • url および homepage
  • license-name および license

Code stewardship

関連項目

Documentation

Feedback

  • RfC about implementing extension registration

脚注

  1. ↑ https://github.com/wikimedia/mediawiki/blob/78091899db2315916502421fdd2972f1d73237b3/docs/extension.schema.json#L273-L282
Retrieved from "https://www.mediawiki.org/w/index.php?title=Manual:Extension_registration/ja&oldid=7680468"