MediaWiki master
MediaWiki\HookContainer\HookContainer Class Reference

HookContainer class. More...

Inherits SalvageableService.

Collaboration diagram for MediaWiki\HookContainer\HookContainer:

Public Member Functions

 __construct (HookRegistry $hookRegistry, ObjectFactory $objectFactory)
 
 clear (string $hook)
 Clear handlers of the given hook.
 
 emitDeprecationWarnings ()
 For each hook handler of each hook, this will log a deprecation if:
 
 getHandlerCallbacks (string $hook)
 Get handler callbacks.
 
 getHandlerDescriptions (string $hook)
 Return the array of strings that describe the handler registered with the given hook.
 
 getHookNames ()
 Returns the names of all hooks that have at least one handler registered.
 
 isRegistered (string $hook)
 Return whether hook has any handlers registered to it.
 
 register (string $hook, $handler)
 Attach an event handler to a given hook.
 
 run (string $hook, array $args=[], array $options=[])
 Call registered hook functions through either the legacy $wgHooks or extension.json.
 
 salvage (SalvageableService $other)
 Salvage the state of HookContainer by retaining existing handler objects and hooks registered via HookContainer::register().
 
 scopedRegister (string $hook, $handler)
 Register hook and handler, allowing for easy removal.
 

Public Attributes

const NOOP = '*no-op*'
 

Detailed Description

HookContainer class.

Main class for managing hooks

Since
1.35

Definition at line 57 of file HookContainer.php.

Constructor & Destructor Documentation

◆ __construct()

MediaWiki\HookContainer\HookContainer::__construct ( HookRegistry $hookRegistry,
ObjectFactory $objectFactory )
Parameters
HookRegistry$hookRegistry
ObjectFactory$objectFactory

Definition at line 93 of file HookContainer.php.

Member Function Documentation

◆ clear()

MediaWiki\HookContainer\HookContainer::clear ( string $hook)

Clear handlers of the given hook.

This is intended for use while testing and will fail if MW_PHPUNIT_TEST and MW_PARSER_TEST are not defined.

Parameters
string$hookName of hook to clear
Access: internal
For testing only

Definition at line 189 of file HookContainer.php.

◆ emitDeprecationWarnings()

MediaWiki\HookContainer\HookContainer::emitDeprecationWarnings ( )

For each hook handler of each hook, this will log a deprecation if:

  1. the hook is marked deprecated and
  2. the "silent" flag is absent or false, and
  3. an extension registers a handler in the new way but does not acknowledge deprecation

Definition at line 610 of file HookContainer.php.

◆ getHandlerCallbacks()

MediaWiki\HookContainer\HookContainer::getHandlerCallbacks ( string $hook)

Get handler callbacks.

Deprecated
since 1.41.
Access: internal
For use by FauxHookHandlerArray. Delete when no longer needed.
Parameters
string$hookName of hook
Returns
callable[]

Definition at line 465 of file HookContainer.php.

◆ getHandlerDescriptions()

MediaWiki\HookContainer\HookContainer::getHandlerDescriptions ( string $hook)

Return the array of strings that describe the handler registered with the given hook.

Access: internal
Only public for use by ApiQuerySiteInfo.php and SpecialVersion.php
Parameters
string$hookName of the hook
Returns
string[] A list of handler descriptions

Definition at line 547 of file HookContainer.php.

◆ getHookNames()

MediaWiki\HookContainer\HookContainer::getHookNames ( )

Returns the names of all hooks that have at least one handler registered.

Returns
string[]

Definition at line 492 of file HookContainer.php.

◆ isRegistered()

MediaWiki\HookContainer\HookContainer::isRegistered ( string $hook)

Return whether hook has any handlers registered to it.

The function may have been registered via Hooks::register or in extension.json

Parameters
string$hookName of hook
Returns
bool Whether the hook has a handler registered to it

Definition at line 405 of file HookContainer.php.

◆ register()

MediaWiki\HookContainer\HookContainer::register ( string $hook,
$handler )

Attach an event handler to a given hook.

The handler should be given in one of the following forms:

1) A callable (string, array, or closure) 2) An extension hook handler spec in the form returned by HookRegistry::getExtensionHooks

Several other forms are supported for backwards compatibility, but should not be used when calling this method directly.

Note
This method accepts "broken callables", that is, callable structures that reference classes that could not be found or could not be loaded, e.g. because they implement an interface that cannot be loaded. This situation may legitimately arise when implementing hooks defined by extensions that are not present. In that case, the hook will never fire and registering the "broken" handlers is harmless. If a broken hook handler is registered for a hook that is indeed called, it will cause an error. This is intentional: we don't want to silently ignore mistakes like mistyped class names in a hook handler registration.
Parameters
string$hookName of hook
string | array | callable$handlerhandler

Definition at line 435 of file HookContainer.php.

◆ run()

MediaWiki\HookContainer\HookContainer::run ( string $hook,
array $args = [],
array $options = [] )

Call registered hook functions through either the legacy $wgHooks or extension.json.

For the given hook, fetch the array of handler objects and process them. Determine the proper callback for each hook and then call the actual hook using the appropriate arguments. Finally, process the return value and return/throw accordingly.

Parameters
string$hookName of the hook
array$argsArguments to pass to hook handler
array$optionsoptions map:
  • abortable: (bool) If false, handlers will not be allowed to abort the call sequence. An exception will be raised if a handler returns anything other than true or null.
  • deprecatedVersion: (string) Version of MediaWiki this hook was deprecated in. For supporting Hooks::run() legacy $deprecatedVersion parameter. New core code should add deprecated hooks to the DeprecatedHooks::$deprecatedHooks array literal. New extension code should use the DeprecatedHooks attribute.
  • silent: (bool) If true, do not raise a deprecation warning
  • noServices: (bool) If true, do not allow hook handlers with service dependencies
Returns
bool True if no handler aborted the hook
Exceptions
UnexpectedValueExceptionif handlers return an invalid value

Definition at line 142 of file HookContainer.php.

◆ salvage()

MediaWiki\HookContainer\HookContainer::salvage ( SalvageableService $other)

Salvage the state of HookContainer by retaining existing handler objects and hooks registered via HookContainer::register().

Necessary in the event that MediaWikiServices::resetGlobalInstance() is called after hooks have already been registered.

Parameters
HookContainer | SalvageableService$otherThe object to salvage state from. $other be of type HookContainer

Definition at line 110 of file HookContainer.php.

◆ scopedRegister()

MediaWiki\HookContainer\HookContainer::scopedRegister ( string $hook,
$handler )

Register hook and handler, allowing for easy removal.

Intended for use in temporary registration e.g. testing

Parameters
string$hookName of hook
callable | string | array$handlerHandler to attach
Returns
ScopedCallback

Definition at line 205 of file HookContainer.php.

Member Data Documentation

◆ NOOP

const MediaWiki\HookContainer\HookContainer::NOOP = '*no-op*'

Definition at line 60 of file HookContainer.php.


The documentation for this class was generated from the following file: