Manual:Hooks/ru



Хуки позволяют выполнять собственный код, при возникновении определенного события (например, сохранение страницы или вход пользователя). Например, следующий фрагмент кода будет запускать вызов функции всякий раз, когда выполняется перехват , передавая ему аргументы функции, специфичные для.

Крючки могут быть зарегистрированы путем сопоставления имени крючка с обратным вызовом в файле расширения :

MediaWiki предоставляет множество хуков как это расширение функциональности программного обеспечения MediaWiki. Назначение функции (известной как обработчик событий) крюку приведет к тому, что эта функция будет вызвана в соответствующей точке основного кода MediaWiki для выполнения любых дополнительных задач, которые разработчик сочтет полезными в этот момент. Каждому хуку может быть назначено несколько обработчиков, и в этом случае он будет вызывать функции в том порядке, в котором они назначены, при этом любые изменения, внесенные одной функцией, передаются последующим функциям в цепочке.

Назначьте функции крючкам в "конце" или в вашем собственном файле расширения в области действия файла ("не" в функции  или крючке ). Для расширений, если поведение функции перехвата обусловлено параметром в LocalSettings.php, перехват должен быть назначен, и функция должна завершиться досрочно, если условие не было выполнено.

Вы также можете создавать новые хуки в своем собственном расширении. Он регистрируется в extension.json так же, как если бы вы регистрировали встроенный хук MediaWiki для использования в вашем расширении. Затем вы можете запустить свой хук в своем расширении, вызвав. Наконец, не забудьте добавить их к.

Введение
Перехват запускается вызовом HookContainer::run, обычно с помощью метода в HookRunner. HookContainer найдет обработчики хуков для запуска и вызовет их с параметрами, заданными для HookContainer::run. Обработчики крючков регистрируются через.

Смотрите также.

В этом примере из функции  в, doPurge вызывает HookRunner::onArticlePurge для запуска хука , передавая   в качестве аргумента:

вызывает много хуков, но также может вызывать хуки.

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


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

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

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

Когда происходит событие, будет вызвана функция (или метод объекта), которую вы зарегистрировали, параметры события, а также любые дополнительные данные, которые вы указали при регистрации. Обратите внимание, что когда объект является крючком, и вы не указали метод, вызываемый метод - "EventName". 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:

This will prevent further handlers from being run, and in some cases tells the calling function to skip normal processing.
 * нет возвращаемого значения (или null): обработчик перехвата успешно сработал. (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.

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

Поведение хуков до MediaWiki 1.22 по сравнению с после
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 должны быть задокументированы как в [интерфейс хука https://doc.wikimedia.org/mediawiki-core/master/php/group__Hooks.html] (в репозитории исходного кода), так и в здесь на MediaWiki.org. В некоторых случаях один из этих шагов, возможно, еще не завершен, поэтому, если крючок кажется недокументированным, проверьте оба.

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. For example,. You can find a list of hook interfaces in the generated MediaWiki PHP documentation.

To document a hook on-wiki, use MediaWikiHook.

 Hook interface doc template 

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

Хуки сгруппированные по функциям
Некоторые из этих хуков могут быть сгруппированы в несколько функций.
 * Разделы: Управление статьями - Редактировать страницу - Рендеринг страницы - Пользовательский интерфейс - Управление файлами - Специальные страницы - Управление пользователями - Регистрация - Шаблоны для скинов - API - Импорт/Экспорт - Различия - Разное

Алфавитный список крюков
Для получения полного списка хуков используйте, который следует поддерживать в актуальном состоянии.

См. также

 * — спецификация системы хуков
 * Список интерфейсов хуков в ядре MediaWiki
 * — содержит примеры хуков
 * — JavaScript/интерфейсная система хуков
 * — спецификация системы хуков
 * Список интерфейсов хуков в ядре MediaWiki
 * — содержит примеры хуков
 * — JavaScript/интерфейсная система хуков