構造

最小限の拡張機能は、以下の構造で構成されます:

MyExtension/extension.json

セットアップの指示を保持します。 ファイル名は必ず extension.json にします。 （MediaWiki 1.25以前では、セットアップの指示は拡張機能から名前を取った MyExtension/MyExtension.php ファイル内に記述されていました。 依然として拡張機能の多くには、このPHPファイルに下位互換性のあるシム (shim) があります。)

MyExtension/includes/ (or MyExtension/src/)

拡張機能のための PHP 実行コードを格納します。

MyExtension/resources/ (or MyExtension/modules/)

拡張機能に必要となるJavaScript、CSSやLESSのようなクライアント側に必要なリソースを保存します。

MyExtension/i18n/*.json

これは拡張機能の地域化に関わる情報を格納したページです。

MyExtension/README.md

いい実践としては、拡張機能のインストールと設定方法に関する基本情報が記載された README ファイルを追加することが推奨されています。 Use either plain text or Markdown. 例えば、Extension:Page Forms について Phabricator Diffusion ページを参照してください。 Markdown が使用される場合は、ファイル拡張子に .md を追加してください。 例えば、Phabricator Diffusion 上の Parsoid 向けの README.md ファイルを参照してください。

拡張機能の開発時には上記の MyExtension の代わりにご利用の拡張機能名を記入します。 ディレクトリ名と PHP ファイル名はアッパーキャメルケースにします。これは標準的なファイル命名規約に準じています。^[1]

登録

The extension.json file contains the configuration data for the extension. Here is an example of a minimal extension.json:

{
	"name": "MyExtension",
	"author": "John Doe",
	"url": "https://www.mediawiki.org/wiki/Extension:MyExtension",
	"description": "This extension is an example.",
	"version": "1.5",
	"license-name": "GPL-2.0-or-later",
	"type": "validextensiontype",
	"manifest_version": 2
}

項目の多くは設定任意ですが、すべて指定しておく方がいいでしょう。 For a more complete example of extension.json, see the BoilerPlate extension.

manifest_version は extension.json のファイルが書き込まれるスキーマのバージョンを示しています。 この機能に関する文書はこちらを参照してください。 以前のMediaWikiバージョンをサポートする必要がない限り、最新バージョンを選択してください。

Once you have an extension.json file set up for your extension, the extension will appear on your local Special:Version page.

ライセンス

MediaWiki はオープンソース プロジェクトであり、オープンソース イニシアティブ (OSI) 承認済みライセンスの下で任意の MediaWiki extensions を GPL-2.0-or-later (ウィキメディアの標準ソフトウェア ライセンス) と互換性のあるものにすることをお勧めします。

Gerrit のプロジェクトには、以下の互換ライセンスのいずれかを採用することをお勧めします:

• GNU 一般公衆利用許諾書 2.0 以降 (GPL-2.0-or-later)
• MIT ライセンス (MIT)
• BSD ライセンス (BSD-3-Clause)
• Apache ライセンス 2.0 (Apache-2.0)

互換性のあるライセンスを持つ拡張機能の場合、拡張機能の MediaWiki ソース リポジトリへの開発者アクセスを申請できます。 コード内で「license-name」でライセンスを指定するには、短い名前を提供するために、spdx.orgの識別子一覧に準拠するキー (例:「GPL-2.0-or-later」「MIT」) を使用する必要があります。

拡張機能を利用者が構成可能にする

wfLoadExtension( 'MyExtension' );

ユーザーが拡張機能の設定を変更できるようにするには設定パラメータの設定と説明文書作成が必要で、ユーザ設定はたとえば下記の例のようになります。

wfLoadExtension( 'MyExtension' );
$wgMyExtensionConfigThis = 1;
$wgMyExtensionConfigThat = false;

利用者が拡張機能を構成できるようにするには、1 つ以上の構成変数を用意する必要があります。 これらの変数には、固有の名前を付けるといいでしょう。 また、MediaWiki の命名規約に従わなければなりません (例: グローバル変数は $wg で始まる)。

例えば、拡張機能の名前が MyExtension の場合、すべての設定変数を $wgMyExtension で始めるようにすることを検討するかもしれません。 重要なのは、MediaWikiのコアがそのような変数名を使用していないことを確認することであり、公開されている拡張機能の中でもそのような変数名を使用していないかを確認することです。 重複する変数名を選択したために、あなたの拡張機能と他の拡張機能のどちらかを選択しなければならなくなったとしたら、利用者は快く思わないでしょう。

また、インストールの注記には、構成変数の詳細を記載することをお勧めします。

{
	"config": {
		"BoilerPlateEnableFoo": {
			"value": true,
			"description": "Enables the foo functionality"
		}
	}
}

wfLoadExtension( 'BoilerPlate' ); を呼び出した後、グローバル変数 $wgBoilerPlateEnableFoo は存在しないことに注意してください。 例えば LocalSettings.php で変数を設定した場合、extension.json に記載された既定値は使用されません。

カスタム拡張機能内でグローバル変数を使用する方法の詳細については、Configuration for developers を参照してください。

クラスのオートローディングの準備

拡張機能を実装するためにクラスを使用することを選択した場合、MediaWiki は PHP がクラスの定義が格納されているソース ファイルを見つけるのを支援する簡素化された仕組みを提供します。 多くの場合、__autoload($classname)の手順を自作しなくて済みます。

MediaWikiのオートローディング機構を使用するには、AutoloadClasses フィールドにエントリを追加します。 各エントリのキーはクラス名で、値はクラスの定義が格納されているファイルです。 シンプルな 1 クラスの拡張機能では、クラス名は通常拡張機能の名前と同じにされるため、オートローディングの節は以下のようになる場合があります (拡張機能名は MyExtension):

{
	"AutoloadClasses": {
		"MyExtension": "includes/MyExtension.php"
	}
}

ファイル名は extension.json ファイルが格納されているディレクトリに対して相対的です。

より複雑な拡張機能では、名前空間を考慮する必要があります。 詳細は Manual:Extension.json/Schema#AutoloadNamespaces を参照してください。

拡張機能が別の拡張機能の存在を必要とすると仮定してください。例えば、機能やデータベース テーブルを使用するため、存在しない場合のエラー メッセージを避けるためです。

	if ( ExtensionRegistry::getInstance()->isLoaded( 'HitCounters', '>=1.1' ) {
		/* do some extra stuff, if extension HitCounters is present in version 1.1 and above */
	}

Currently (as of February 2024, MediaWiki 1.41.0) the name of the extension-to-be-checked needs to exactly match the name in their extension.json.^[2][3]

例: if you want to check the load status of extension OpenIDConnect, you have to use it with a space

	if ( ExtensionRegistry::getInstance()->isLoaded( 'OpenID Connect' ) {
    ...
	}

ページ

• Display a special page : 特別ページは、システムの状態、データベースのクエリ、利用者からの入力などに基づいて動的に生成されるコンテンツを提供します。
• Perform a page action : The action URL parameter generates a custom page based on the current page, usually to provide information (such as page history) or to perform an action (such as edit the page). In addition to the default actions provided by MediaWiki core, extensions can define a new page action.
• Add a tracking category : Help users find pages with similar characteristics by automatically adding pages to custom categories.

• Extend wiki markup : Extensions can add custom functionality to MediaWiki's wikitext markup using template syntax ({{...}}) or tags (‎<example />). These customizations are used to generate content and to interact with MediaWiki during page rendering.
• Support a content model : By default, wiki pages can be stored using a few standard content models, such as wikitext and JSON. Extensions can provide support for new content models by adding a content handler.
• Support a media type : Extensions can add to the default set of supported media file types by adding a media handler.

• Log a user or system action : On wiki, actions are tracked for transparency and collaboration. To support this feature, extensions can add custom entries and functionality to Special:Log.
• Add a recent-changes flag : Extensions can add custom flags to the following special pages to help moderators track page changes: Special:RecentChanges, Special:Watchlist, Special:RecentChangesLinked
• Add a revision tag : 拡張機能は、例えばビジュアルエディター拡張機能を使って行われた編集に対してなど、版や記録項目に関連付けられた注釈を追加できます。

• Add a provider : Extensions can add support for new login mechanisms and session management methods.

データベース テーブルの追加

Make sure the extension doesn't modify the core database tables. Instead, extension should create new tables with foreign keys to the relevant MW tables.

警告:	If your extension is used on any production WMF-hosted wiki please follow the Schema change guide.

If your extension needs to add its own database tables, use the LoadExtensionSchemaUpdates hook. 使用法のより詳細な情報はマニュアルページを参照してください。

Attributes allow extensions to register something, such as a module, with another extension. For example, extensions can use attributes to register a plugin module with the VisualEditor extension. For more information, see 拡張機能の登録 .

Store messages in <language-key>.json

Store message definitions in a localisation JSON file, one for each language key your extension is translated in. The messages are saved with a message key and the message itself using standard JSON format. Each message id should be lowercase and may not contain spaces. Each key should begin with the lowercased extension name. An example you can find in the MobileFrontend extension. Here is an example of a minimal JSON file (in this case en.json):

en.json

{
	"myextension-desc": "Adds the MyExtension great functionality.",
	"myextension-action-message": "This is a test message"
}

The documentation for message keys can be stored in the JSON file for the pseudo language with code qqq. A documentation of the example above can be:

qqq.json:

{
	"myextension-desc": "The description of MyExtension used in Extension credits.",
	"myextension-action-message": "Adds 'message' after 'action' triggered by user."
}

地域化ファイルの読み込み

{
	"MessagesDirs": {
		"MyExtension": [
			"i18n"
		]
	}
}

PHP での wfMessage の使用

In your setup and implementation code, replace each literal use of the message with a call to wfMessage( $msgID, $param1, $param2, ... ). In classes that implement IContextSource (as well as some others such as subclasses of SpecialPage), you can use $this->msg( $msgID, $param1, $param2, ... ) instead. 例:

wfMessage( 'myextension-addition', '1', '2', '3' )->parse()

JavaScript での mw.message の使用

It's possible to use i18n functions in JavaScript too. 詳細は Manual:メッセージAPI を参照してください。

ヘルプの説明文書

You should provide public domain help documentation for features provided by your extension. The convention is for extensions to have their user-focused help pages under a pseudo-namespace of Help:Extension:<ExtensionName>, with whatever subpages are required (the top level page will be automatically linked from the extension infobox if it exists). Help:CirrusSearch is a example of good documentation. You should give users a link to the documentation via the addHelpLink() function.

There are a number of common approaches to releasing updates to extensions. These are generally defined according to the compatibility policy of the extension (master, rel, or ltsrel):

• master – Releases may be tagged with version numbers on the master branch, and documentation provided on the extension's homepage describing which extension versions are compatible with which core versions. Release branches will still be created automatically, and you may wish to delete these if they are not intended to be used.
• rel および ltsrel – Release by backporting changes to the REL1_* branches (either all changes, or only critical ones). Version numbers are generally not needed unless the extension is a dependency of another (the version number can then be provided in the other extension's configuration to ensure that incompatible combinations aren't installed). Many extensions will stay at the same version number for years.

異なるコアバージョンのサポート

• Master: the master branch of the extension is compatible with as many old versions of core as possible. This results in a maintenance burden (backwards-compatibility hacks need to be kept around for a long time, and changes to the extension need to be tested with several versions of MediaWiki), but sites running old MediaWiki versions benefit from functionality recently added to the extension.
• Release branches: release branches of the extension are compatible with matching branches of core, e.g. sites using MediaWiki 1.43 need to use the REL1_43 branch of the extension. (For extensions hosted on Gerrit, these branches are automatically created when new versions of MediaWiki are released.) This results in cleaner code and faster development but users on old core versions do not benefit from bugfixes and new features unless they are backported manually.

Extension developers should open an account on Wikimedia's Phabricator , and request a new project for the extension. これは、利用者が問題や提案を提出できる公開の場を提供し、利用者や他の開発者と協力してバグの優先順位付けや拡張機能の機能計画を行えます。