Manual:フック
 拡張機能: |
開発 | タグ拡張機能 | パーサー関数 | フック | 特別ページ | 外装 | マジックワード | API | Content models |
Contents
フックは特定のイベント（ページ保存や利用者ログインなど）が発生したとき、カスタム コードの実行を認めます。
たとえば下記のコード スニペットにより、フックのPageContentSaveCompleteが走る場面で必ず関数MyExtensionHooks::pageContentSaveCompleteを呼び出し、PageContentSaveCompleteに特有の関数引数を渡します。
Hooks can be registered by mapping the name of the hook to the callback in the extension's extension.json file:
"Hooks": { "PageContentSaveComplete": "MyExtensionHooks::onPageContentSaveComplete" }
MediaWikiはこのようなフックを用意し、MediaWiki ソフトウェアの機能を拡張しています。特定の関数（ユーザー処理つまりイベントハンドラー）をフックに定義すると、メインのMediaWikiコードにおいて適切なタイミングでその関数を呼び出し、その時点で開発者が有効と判断した追加のタスクをいくつでも実行します。フックに定義できるハンドラーは複数で、定義順に呼び出した定義が行った変更を、一連の後続の関数に渡していきます。
フックに機能を割り当てるにはLocalSettings.phpの末尾もしくはファイルスコープの拡張機能（$wgExtensionFunctions 関数あるいはParserFirstCallInit フックではなく）で割り当てます。拡張機能の場合、LocalSettings.php の設定がフックの機能の挙動に条件を付けるなら、フックに機能を割り当て、条件が適合しないときは早めに関数を停止する必要があります。
ご利用の拡張機能で新しくフックを作成することもできます。作成したフックは拡張機能フックのレジストリに追加します。
背景
フックはHooks::run関数を呼び出すと作動します（説明は hooks.txt ファイルに、定義は GlobalFunctions.php のとおり）。Hooks::runの1番目の引数はフックの名前、2番目はそのフックの引数の配列です。$wgHooks 配列内で、実行すべきイベントハンドラーを検出します。call_user_func_array というPHP関数を呼び出し、その際、呼び出すべき関数とその引数を引数として渡します。
コアにあるフックの仕様も参照してください。
この使用事例は WikiPage.php の doEditContent 関数で、Hooks::run は doEditContent に呼び出されると PageContentSaveComplete フックを実行、引数として $hookArgs を当てます。
Hooks::run( 'PageContentSaveComplete', $hookArgs );
多数のフックを呼び出すのは コア ですが、拡張機能 からもフックを呼び出せます。
イベントハンドラーを書く
イベントハンドラーはフックに設定する関数で、 フックが代表するイベントが発生するたびに実行されます。構成要素は次のとおりです。
- 関数と、設定で有効にするデータを添えたもの。
- method変数と、設定で有効にするデータを添えたオブジェクト。
Register the event handler by adding it to the global $wgHooks array for a given event.
Hooks can be added from any point in the execution before the hook is called, but are most commonly added in LocalSettings.php, its included files, or, for extensions, in the file extension.json.
All the following are valid ways to define a hook function for the event EventName that is passed two parameters, showing the code that will be executed when EventName happens:
| 書式 | 構文 | 結果として呼び出す関数 |
|---|---|---|
| Static function | $wgHooks['EventName'][] = 'MyExtensionHooks::onEventName';
|
MyExtensionHooks::onEventName( $param1, $param2 );
|
| 関数 データ無 | $wgHooks['EventName'][] = 'someFunction';
|
someFunction( $param1, $param2 );
|
| 関数、データ有 | $wgHooks['EventName'][] = [ 'someFunction', $someData ];
|
someFunction( $someData, $param1, $param2 );
|
| Function, no data (weird syntax, but OK) |
$wgHooks['EventName'][] = [ 'someFunction' ];
|
someFunction( $param1, $param2 );
|
| インラインの無名関数 |
$wgHooks['EventName'][] = function( $param1, $param2 ) {
// ...function body
}
|
(the anonymous function is called with the hook's parameters) |
| オブジェクトのみ | $wgHooks['EventName'][] = $object;
|
$object->onEventName( $param1, $param2 );
|
| Object with method | $wgHooks['EventName'][] = [ $object, 'someMethod' ];
|
$object->someMethod( $param1, $param2 );
|
| Object with method and data | $wgHooks['EventName'][] = [ $object, 'someMethod', $someData ];
|
$object->someMethod( $someData, $param1, $param2 );
|
| Object only (weird syntax, but OK) |
$wgHooks['EventName'][] = [ $object ];
|
$object->onEventName( $param1, $param2 );
|
拡張機能の場合、構文はextension.jsonファイルと同様（前述の1番目と2番目の事例に対応）:
{
"Hooks": {
"EventName": [
"MyExtensionHooks::onEventName",
"someFunction"
]
}
}
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:
$wgHooks['PageContentSaveComplete'][] = [ 'ircNotify', 'TimStarling' ];
$wgHooks['PageContentSaveComplete'][] = [ 'ircNotify', 'brion' ];
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:
- no return value (or null): the hook handler has operated successfully. (Before MediaWiki 1.23, returning true was required.)
- "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. This will prevent further handlers from being run, and in some cases tells the calling function to skip normal processing.
操作が完了した場合はfalseを返しても無意味であり、通常、callerに無視されます。
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 e.preventDefault and e.stopImmediatePropagation in JavaScript events, it kills other listeners for the same event).
For example, if onBeforePageDisplay 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 onBeforePageDisplay.
MediaWiki 1.22 以前
public static function onBeforePageDisplay( OutputPage $out, Skin $skin ) {
<some code>
return true; // explicit
}
または
public static function onBeforePageDisplay( OutputPage $out, Skin $skin ) {
<some code>
return; // explicit
}
MediaWiki 1.22+
public static function onBeforePageDisplay( OutputPage $out, Skin $skin ) {
<some code>
// no need for a return true or return
}
説明文書
MediaWiki コアのフックは現状ではここMediaWiki.orgのほか docs/hooks.txt (ソースコード リポジトリ内) の2箇所に説明文書を置くことになっています。場合によってはどちらかで作業が未完了なことがあるため、フックの説明文書を確認するときは両方の場所を調べてください。
オンウィキでフックを開設するには{{MediaWikiHook}}を使います。
利用できるフック
フックの完全な一覧は、カテゴリを参照してください。こちらはさらに最新に近い状態に維持されています。
