Manual:Hooks/ru

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page Manual:Hooks and the translation is 40% complete.

Outdated translations are marked like this.
Other languages:
Bahasa Indonesia • ‎Deutsch • ‎English • ‎dansk • ‎español • ‎français • ‎português do Brasil • ‎čeština • ‎македонски • ‎русский • ‎中文 • ‎日本語 • ‎한국어
OOjs UI icon puzzle-ltr.svg Расширения: Разработка Теги расширений Руководство:Функции парсера Прерывания Служебные страницы Стили оформления (skins) Руководство:Волшебные слова API Content models
MediaWiki extensions

Хуки позволяют выполнять собственный код, при возникновении определенного события (например, сохранение страницы или вход пользователя). Например, следующий фрагмент кода вызовет функцию MyExtensionHooks::pageContentSaveComplete всякий раз, когда выполняется хук 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 это название хука, второй это массив аргументов для этого хука. Она найдйт обработчики событий для запуска в массиве $wgHooks. Она вызывает функцию PHP call_user_func_array, аргументы которой являются вызываемой функцией и её аргументами.

В этом примере из функции doEditContent в WikiPage.php, doEditContent вызывает Hooks::run для запуска хука PageContentSaveComplete, передавая $hook_args в качестве аргумента:

Hooks::run( 'PageContentSaveComplete', $hookArgs );

Ядро вызывает множество хуков, но расширения также могут вызвать хуки.

Запись обработчика событий

Обработчик событий - это функция, которую вы назначаете на хук, который будет выполняться всякий раз, когда происходит событие, представленное этим хуком. Он состоит из:

  • функция с некоторыми дополнительными сопутствующими данными, или
  • объект с методом и некоторыми дополнительными сопутствующими данными.

Зарегистрируйте обработчик событий, добавив его в глобальный массив $wgHooks для данного события. Хуки могут быть добавлены из любой точки выполнения до вызова хука, но чаще всего добавляются в LocalSettings.php, его включаемых файлов или для расширений в файле extension.json. Все приведенные ниже действия являются допустимыми способами определения функции хука для события EventName, которое передаётся двумя параметрами, отображающими код, который будет выполняться при возникновении EventName:

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:

Формат Синтаксис Результат вызова функции.
Статическая функция $wgHooks['EventName'][] = 'MyExtensionHooks::onEventName'; MyExtensionHooks::onEventName( $param1, $param2 );
Функция без данных $wgHooks['EventName'][] = 'someFunction'; someFunction( $param1, $param2 );
Функция с данными $wgHooks['EventName'][] = [ 'someFunction', $someData ]; someFunction( $someData, $param1, $param2 );
Функция без данных
(странный синтаксис, но ладно)
$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 );
Объект с методом $wgHooks['EventName'][] = [ $object, 'someMethod' ]; $object->someMethod( $param1, $param2 );
Объект с методом и данными $wgHooks['EventName'][] = [ $object, 'someMethod', $someData ]; $object->someMethod( $someData, $param1, $param2 );
Только объект
(странный синтаксис, но ладно)
$wgHooks['EventName'][] = [ $object ]; $object->onEventName( $param1, $param2 );

Для расширения, синтаксис похож на синтаксис в extension.json (соответствует первому и второму случаю выше):

{
	"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.
In many cases where an error message is expected, the hook will define a variable passed as a reference for extensions to store an error message and this is preferred over returning a string that will simply be displayed as an "internal error."

Returning false makes less sense for events where the action is complete, and will normally be ignored by the 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.

Before MediaWiki 1.22

public static function onBeforePageDisplay( OutputPage $out, Skin $skin ) {
    // some code
    return true; // explicit
}

or

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
}


Документация

Currently, hooks in MediaWiki core have to be documented both in docs/hooks.txt (in the source code repository) and here on MediaWiki.org. In some cases, one of these steps may not yet have been completed, so if a hook appears undocumented, check both.

To document a hook on-wiki, use {{MediaWikiHook}}.

Доступные хуки

For a complete list of hooks, use the category , which should be kept more up to date.

См. также