Manual:Hooks/ja



フックは特定のイベント（ページ保存や利用者ログインなど）が発生したとき、カスタム コードの実行を認めます. たとえば下記のコード スニペットにより、フックの  が走る場面で必ず関数  を呼び出し、 に特有の関数引数を渡します.

フックは、拡張機能の ファイル内で、フックの名前からコールバックにマッピングすることで登録できます:

MediaWikiはこのようなフックを用意し、MediaWiki ソフトウェアの機能を拡張しています. 特定の関数（ユーザー処理つまりイベントハンドラー）をフックに定義すると、メインのMediaWikiコードにおいて適切なタイミングでその関数を呼び出し、その時点で開発者が有効と判断した追加のタスクをいくつでも実行します. フックに定義できるハンドラーは複数で、定義順に呼び出した定義が行った変更を、一連の後続の関数に渡していきます.

フックに機能を割り当てるには の末尾またはファイル スコープの拡張機能 ( 関数や  フックではなく) で割り当てます. 拡張機能の場合、LocalSettings.php の設定がフックの機能の挙動に条件を付けるなら、フックに機能を割り当て、条件が適合しないときは早めに関数を停止する必要があります.

ご利用の拡張機能で新しくフックを作成することもできます. これは、拡張機能で使用する組み込みの MediaWiki フックを登録するのと同じ方法で、extension.json で登録されます. その後、拡張機能内で を呼び出すことでフックを実行できます. 最後に、 に追加するのも忘れないでください.

背景
フックは、HookContainer::run への呼び出しによって、通常は HookRunner のメソッドを介して起動されます. HookContainer は実行すべきフック ハンドラーを見つけ、HookContainer::run に与えられたパラメーターでそれらのハンドラーを呼び出します. フック ハンドラーは 経由で登録されます.

も参照してください.

この使用事例は の   関数で、HookRunner::onArticlePurge は doPurge に呼び出されると  フックを実行、引数として   を当てます:

多数のフックを呼び出すのは ですが、 からもフックを呼び出せます.



イベントハンドラーを書く
イベントハンドラーはフックに設定する関数で、 フックが代表するイベントが発生するたびに実行されます. 構成要素は次のとおりです.


 * 関数と、設定で有効にするデータを添えたもの.
 * method変数と、設定で有効にするデータを添えたオブジェクト.

イベント ハンドラーを、指定されたイベントのグローバル配列 に追加することで、登録します. フックは、フックが呼び出される前の実行中のどの時点でも追加できますが、最も一般的には、 やそのインクルード ファイル、または拡張機能の場合は extension.json というファイルで追加されます. 以下のすべては、2 つのパラメーターを渡されたイベント EventName (イベント名) に対するフック関数を定義する有効な方法であり、EventName が発生したときに実行されるコードを示しています:

拡張機能の場合、構文は ファイルと同様（前述の1番目と2番目の事例に対応）:

When an event occurs, the function (or object method) that you registered will be called, the event's parameters, along with any optional data you provided at registration. Note that when an object is the hook and you didn't specify a method, the method called is "onEventName". For other events this would be 'onArticleSave', 'onUserLogin', etc.

The optional data is useful if you want to use the same function or object for different purposes. For example:

This code would result in ircNotify being run twice when a page is saved: once for 'TimStarling', and once for 'brion'.

Event handlers can return one of three possible values:

(Before MediaWiki 1.23, returning true was required.) This will prevent further handlers from being run, and in some cases tells the calling function to skip normal processing.
 * no return value (or null): the hook handler has operated successfully.
 * "some string": an error occurred; processing should stop and the error should be shown to the user
 * false: the hook handler has done all the work necessary, or replaced normal handling.

操作が完了した場合はfalseを返しても無意味であり、通常、callerに無視されます.

Handling hooks in MediaWiki 1.35 and later
MediaWiki 1.35 introduces a system for handling hooks based on individual hook interfaces. This system allows for dependency injection, provides machine-readable parameter names and types, and integrates hook documentation with code editors.

For extensions, methods of registering and handling hooks in MediaWiki 1.34 and earlier are not being deprecated and will continue to work as expected. Extension authors who want to pilot the new system are welcome to do so. To learn more, see the hook specification in MediaWiki Core and the announcement on wikitech-l.

 Changes to hook names 

Prior to MediaWiki 1.35, several hooks included colons in their names. With the implementation of hook interfaces, colons in hook names have been replaced with underscores. For example, the interface for ApiFeedContributions::feedItem is. This does not impact extensions using the hook system in MediaWiki 1.34 and earlier.

 Registering hooks using HookHandlers 

To register a hook in an extension's extension.json file, the new system uses HookHandlers to specify how the handler object is created. Instead of mapping a hook directly to a function, a hook maps to a HookHandlers object which specifies the  and has the option to inject.

For example, to register the BeforePageDisplay hook:

 Handling hooks using interfaces 

To work with registration using HookHandlers, extensions should define an event handler class that implements the hook interface. Hook interfaces are named with the hook name with "Hook" appended.

 Converting extensions to the new hook system  Conversion to the new system is done by doing the following for each hook handler method:
 * identify the hook handler interface, and make the hook handler class implement this interface
 * change the name and signature of the hook handler method to be exactly the same as in the interface
 * change the hook registration in the "Hooks" section of extension.json to refer to the handler you specified in the "HookHandlers" section.

The process was demonstrated at the Wikimedia Hackathon 2021:
 * Recording on YouTube
 * Patch on Gerrit

Hook behavior before MediaWiki 1.22 vs after
Extracted from: change 500542: for non-abortable hooks (most hooks) returning true has been redundant since MediaWiki 1.22 (in 2015). This was done to reduce chances of accidental failure because we had experienced several outages and broken features due to silent failures where e.g. one hook callback somewhere accidentally returned a non-bool or false instead of true/void and thus short-circuits the whole system.

(Returning non-true/non-void in a MediaWiki Hook is equivalent to  and   in JavaScript events, it kills other listeners for the same event).

For example, if  hook were to return false in MobileFrontend, it would mean Popups stops because its callback would no longer run. See differences below, assuming the hook.

MediaWiki 1.22 以前

または

MediaWiki 1.22+

説明文書
MediaWiki コアのフックは現状ではここMediaWiki.orgのほか フック インターフェイス (ソースコード リポジトリ内) の2箇所に説明文書を置くことになっています. 場合によってはどちらかで作業が未完了なことがあるため、フックの説明文書の確認は両方の場所を調べてください.

Each hook provided by MediaWiki Core is defined in a hook interface. Typically, hook interfaces are located in a "Hook" sub-namespace inside the caller namespace. 例:. You can find a list of hook interfaces in the generated MediaWiki PHP documentation.

オンウィキでフックを開設するにはMediaWikiHookを使います.

 Hook interface doc template 

In hook interfaces, doc comments specify the status, purpose, parameters, and behavior of the hook.



利用できるフック


機能ごとに分類したフック
ここに一覧したフックの中には、機能ごとにいくつかのグループに分類できます.
 * 小分類: 記事の管理 - ページ編集 - ページのレンダリング - ユーザー インターフェイス - ファイル管理 - 特別ページ - 利用者管理 - ログ - 外装テンプレート - API - インポート/エクスポート - 差分 - その他



アルファベット順のフック一覧
フックの完全な一覧は、を参照してください. こちらはさらに最新に近い状態に維持されています.

脚注


関連項目

 * — フックシステムの特徴
 * MediaWiki コアにあるフック インタフェースの一覧
 * — contains examples of hooks
 * — フックの JavaScript/フロントエンド システム
 * — フックシステムの特徴
 * MediaWiki コアにあるフック インタフェースの一覧
 * — contains examples of hooks
 * — フックの JavaScript/フロントエンド システム