Manual:Hooks/ru



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

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

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

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

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

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

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

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

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



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

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

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

Обратите внимание, что когда объект является крючком, и вы не указали метод, вызываемый метод - "EventName". Для других событий это было бы 'onArticleSave', 'onUserLogin' и т.д.

Дополнительные данные полезны, если вы хотите использовать одну и ту же функцию или объект для разных целей. Например:

Этот код приведет к тому, что ircNotify будет выполняться дважды при сохранении страницы: один раз для 'TimStarling' и один раз для 'brion'.

Hook handler return values
Обработчики событий могут возвращать одно из трех возможных значений:


 * * нет возвращаемого значения (или null): обработчик перехвата успешно сработал. (До MediaWiki 1.23 требовалось возвращать значение true.)
 * "некоторая строка": произошла ошибка; обработка должна быть остановлена, и ошибка должна быть показана пользователю
 * - * false: обработчик хуков выполнил всю необходимую работу или заменил обычную обработку. Это предотвратит запуск дальнейших обработчиков и в некоторых случаях укажет вызывающей функции пропустить обычную обработку.

Возврат false имеет меньше смысла для событий, в которых действие завершено, и обычно игнорируется вызывающей стороной. In those cases, the return value is often ignored.

Handling hooks in MediaWiki 1.35 and later
MediaWiki 1.35 introduces the HookHandlers system. This includes per-hook interfaces for improved static validation and discovery of parameter documentation. It also enables dependency injection by introducing an intermediary class instance that accepts a number of specified services (instead of static callbacks that explicitly access services from global state).

The approach from MediaWiki 1.34 and earlier, of registering hook handlers directly as static methods, remains supported and is not deprecated. Extension authors may opt-in to the new system are welcome to do so. To learn more, see the MediaWiki core: Hook specification and the announcement on wikitech-l.

Changes to hook names

Prior to MediaWiki 1.35, hooks sometimes included characters that could not be used in a class or method name, such as colons and dashes. With the introduction of per-hook interfaces, the canoncal names of these hooks have been changed to use underscores instead. For example, the interface for ApiFeedContributions::feedItem is. Hook handers that are registered with the old names remain supported.

Registering hooks using HookHandlers

To adopt the new system, changes your Hooks class to have regular methods instead of static methods and be contructable. This class is then registered once, via the HookHandlers attribute in extension.json, using the  option as part of an ObjectFactory description where you can use the   option.

For example, to register the BeforePageDisplay hook:

Handling hooks using interfaces

To use hook interfaces, extensions should define a Hooks class in their namespace and implement one or more hook interfaces. Hook interfaces are named with the hook name followed by the word "Hook".

Convert an extension to the new hook system:

Follow these steps for each hook handling method:
 * identify the hook handler interface, and make the Hooks class implement this interface.
 * update the method name and signature to be exactly the same as in the interface.
 * change 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:
 * Example patch for an extension
 * Recording on YouTube



Поведение хуков до MediaWiki 1.22 по сравнению с после
Извлечено из: change 500542: для не прерываемых хуков (большинство хуков) возврат true был избыточным с MediaWiki 1.22 (в 2015 году). Это было сделано, чтобы уменьшить вероятность случайного сбоя, потому что мы столкнулись с несколькими сбоями и сбоями функций из-за тихих сбоев, когда, например, один обратный вызов где-то случайно возвращал значение, отличное от bool, или false вместо true / void и, таким образом, замыкал всю систему.

(Возврат значения non-true/non-void в хук MediaWiki эквивалентен  и   в событиях JavaScript, он убивает других слушателей для того же события).

Например, если бы хук  возвращал "false" в MobileFrontend, это означало бы, что всплывающие окна останавливаются, потому что его обратный вызов больше не будет выполняться. Смотрите различия ниже, предполагая, что хук.

До MediaWiki 1.22

или

MediaWiki 1.22+

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

Каждый хук, предоставляемый ядром MediaWiki, определяется в интерфейсе хук. Как правило, интерфейсы хук расположены в подпространстве имен "Hook" внутри пространства имен вызывающего абонента. Например,. Вы можете найти список интерфейсов хуков в документации MediaWiki PHP [сгенерированной https://doc.wikimedia.org/mediawiki-core/master/php/group__Hooks.html].

Чтобы задокументировать хук в вики, используйте MediaWikiHook.

Шаблон документа интерфейса хука

В интерфейсах хуков комментарии doc определяют статус, назначение, параметры и поведение хука.



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


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



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

Примечания


См. также

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