Manual:Hooks/id

MediaWiki menyediakan beberapa pengait yang dapat digunakan untuk meluaskan fungsi perangkat lunak MediaWiki. Memberikan suatu fungsi (dikenal dengan event handler) kepada suatu pengait akan menyebabkan fungsi tersebut dipanggil pada titik tertentu dalam kode MediaWiki untuk melakukan tugas tambahan apa pun yang dibutuhkan pengembang pada titik tersebut. Setiap pengait dapat memperoleh beberapa pengendali yang masing-masing akan dijalankan sesuai urutan pemberiannya dan tiap perubahan yang dibuat satu fungsi diteruskan kepada fungsi selanjutnya dalam rantai.

Pengait harus diberikan pada akhir LocalSettings.php atau pada berkas ekstensi di lingkup berkas (tidak dalam fungsi $wgExtensionFunctions atau pada pengait ParserFirstCallInit). Cara terbaik untuk menugaskan suatu fungsi pada suatu pengait adalah:

yang menambahkan satu elemen pada larik $wgHooks. Anda juga dapat membuat pengait baru pada ekstensi Anda. Pengait yang dibuat dengan cara ini harus ditambahkan ke dalam Extension Hook Registry.

Background
Each hook is represented in the code by a call of function wfRunHooks, which is defined in file Hooks.php. The first argument of wfRunHooks is the name of the hook, the second is the array of arguments of the hook. Function wfRunHooks finds the tasks to be done from the array $wgHooks. It calls the PHP function call_user_func_array with arguments being the function to be called and its arguments.

See also the hook specification in SVN.

In this example from the  function in Article.php, wfRunHooks is used to call the ArticleSaveComplete hook using several arguments:

The core calls many hooks, but extensions can also call hooks.

Writing an event handler
An event handler is a function that is assigned to a hook, which will be run whenever the event represented by that hook occurs. It consists of:


 * a function with some optional accompanying data, or
 * an object with a method and some optional accompanying data.

Event handlers are registered by adding them 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 or its included files. All the following are valid ways to define hooks, with the code that will be executed when 'EventName' happens:

When an event occurs, the function (or object method) will be called with the optional data provided as well as event-specific parameters. Note that when an object is the hook, and there's no specified method, the default method called is 'onEventName'. For different events this would be different: 'onArticleSave', 'onUserLogin', etc.

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

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

Event handlers can return one of three possible values:


 * true: the hook has operated successfully
 * "some string": an error occurred; processing should stop and the error should be shown to the user
 * false: the hook has successfully done the work necessary and the calling function should skip

The last result would be for cases where the hook function replaces the main functionality. For example, if you wanted to authenticate users to a custom system (LDAP, another PHP program, whatever), you could do:

Returning false makes less sense for events where the action is complete, and will normally be ignored.

Available hooks
This page contains a list of hooks that are made available by the MediaWiki software, and is known to be complete to version 1.8.2. There is a lot of detail missing for the more recent hooks in particular, as their purpose/usage has not yet been documented by the developers. If you have any further information on any of these then please add it in the appropriate place.

In the tables, the first column gives the MediaWiki version that the hook was introduced in; use the link in the second column to find out more information about the hook and how to use it.

Hooks grouped by version
To see hooks grouped by version go to the table above and click the arrow symbol in the version table header.

Lihat pula

 * Manual:$wgHooks
 * Category:Hook extensions
 * Manual:Tag extensions
 * Manual:Parser functions
 * SVN hooks.txt