MediaWiki  master
MediaWiki\HookContainer\HookContainer Class Reference

HookContainer class. More...

Inheritance diagram for MediaWiki\HookContainer\HookContainer:
Collaboration diagram for MediaWiki\HookContainer\HookContainer:

Public Member Functions

 __construct (HookRegistry $hookRegistry, ObjectFactory $objectFactory)
 
 clear (string $hook)
 Clear hooks registered via Hooks::register(). More...
 
 emitDeprecationWarnings ()
 Will log a deprecation warning if: More...
 
 getHandlers (string $hook, array $options=[])
 Return array of handler objects registered with given hook in the new system. More...
 
 getLegacyHandlers (string $hook)
 Get all handlers for legacy hooks system, plus any handlers added using register(). More...
 
 isRegistered (string $hook)
 Return whether hook has any handlers registered to it. More...
 
 register (string $hook, $callback)
 Attach an event handler to a given hook. More...
 
 run (string $hook, array $args=[], array $options=[])
 Call registered hook functions through either the legacy $wgHooks or extension.json. More...
 
 salvage (SalvageableService $other)
 Salvage the state of HookContainer by retaining existing handler objects and hooks registered via HookContainer::register(). More...
 
 scopedRegister (string $hook, $callback, bool $replace=false)
 Register hook and handler, allowing for easy removal. More...
 

Private Member Functions

 callLegacyHook (string $hook, $handler, array $args, array $options)
 Run legacy hooks Hook can be: a function, an object, an array of $function and $data, an array of just a function, an array of object and method, or an array of object, method, and data (See hooks.txt for more details) More...
 
 normalizeHandler ( $handler, string $hook)
 Normalize/clean up format of argument passed as hook handler. More...
 

Private Attributes

array $dynamicHandlers = []
 Hooks and their callbacks registered through $this->register() More...
 
array $handlersByName = []
 handler name and their handler objects More...
 
int $nextScopedRegisterId = 0
 The next ID to be used by scopedRegister() More...
 
ObjectFactory $objectFactory
 
HookRegistry $registry
 
array $tombstones = []
 Tombstone count by hook name. More...
 

Detailed Description

HookContainer class.

Main class for managing hooks

Since
1.35

Definition at line 45 of file HookContainer.php.

Constructor & Destructor Documentation

◆ __construct()

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

Definition at line 75 of file HookContainer.php.

References MediaWiki\HookContainer\HookContainer\$objectFactory.

Member Function Documentation

◆ callLegacyHook()

MediaWiki\HookContainer\HookContainer::callLegacyHook ( string  $hook,
  $handler,
array  $args,
array  $options 
)
private

Run legacy hooks Hook can be: a function, an object, an array of $function and $data, an array of just a function, an array of object and method, or an array of object, method, and data (See hooks.txt for more details)

Parameters
string$hook
array | callable$handlerThe name of the hooks handler function
array$argsArguments for hook handler function
array$options
Returns
null|string|bool

Definition at line 322 of file HookContainer.php.

References $args, and wfDeprecated().

Referenced by MediaWiki\HookContainer\HookContainer\run().

◆ clear()

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

Clear hooks registered via Hooks::register().

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

Definition at line 190 of file HookContainer.php.

◆ emitDeprecationWarnings()

MediaWiki\HookContainer\HookContainer::emitDeprecationWarnings ( )

Will log a deprecation warning if:

  1. the hook is marked deprecated
  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 477 of file HookContainer.php.

References MWDebug\sendRawDeprecated().

◆ getHandlers()

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

Return array of handler objects registered with given hook in the new system.

This does not include handlers registered dynamically using register(), nor does it include hooks registered via the old mechanism using $wgHooks.

Definition at line 436 of file HookContainer.php.

Referenced by MediaWiki\HookContainer\HookContainer\run().

◆ getLegacyHandlers()

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

Get all handlers for legacy hooks system, plus any handlers added using register().

Definition at line 391 of file HookContainer.php.

References $keys.

Referenced by MediaWiki\HookContainer\HookContainer\isRegistered(), and MediaWiki\HookContainer\HookContainer\run().

◆ 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 343 of file HookContainer.php.

References MediaWiki\HookContainer\HookContainer\getLegacyHandlers().

◆ normalizeHandler()

MediaWiki\HookContainer\HookContainer::normalizeHandler (   $handler,
string  $hook 
)
private

Normalize/clean up format of argument passed as hook handler.

Parameters
array | callable$handlerExecutable handler function
string$hookHook name
Returns
array|false
  • handler: (callable) Executable handler function
  • functionName: (string) Handler name for passing to wfDeprecated() or Exceptions thrown
  • args: (array) handler function arguments

Definition at line 255 of file HookContainer.php.

Referenced by MediaWiki\HookContainer\HookContainer\run().

◆ register()

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

Attach an event handler to a given hook.

Parameters
string$hookName of hook
callable | string | array$callbackhandler object to attach

Definition at line 367 of file HookContainer.php.

References wfDeprecated().

◆ 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.

For hooks that are not abortable through a handler's return value, use runWithoutAbort() instead.

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 sequenece. 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 128 of file HookContainer.php.

References $args, MediaWiki\HookContainer\HookContainer\callLegacyHook(), MediaWiki\HookContainer\HookContainer\getHandlers(), MediaWiki\HookContainer\HookContainer\getLegacyHandlers(), MediaWiki\HookContainer\HookContainer\normalizeHandler(), and wfDeprecatedMsg().

◆ 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
Exceptions
MWException

Definition at line 93 of file HookContainer.php.

◆ scopedRegister()

MediaWiki\HookContainer\HookContainer::scopedRegister ( string  $hook,
  $callback,
bool  $replace = false 
)

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$callbackHandler object to attach
bool$replace(optional) By default adds callback to handler array. Set true to remove all existing callbacks for the hook.
Returns
ScopedCallback

Definition at line 215 of file HookContainer.php.

Member Data Documentation

◆ $dynamicHandlers

array MediaWiki\HookContainer\HookContainer::$dynamicHandlers = []
private

Hooks and their callbacks registered through $this->register()

Definition at line 49 of file HookContainer.php.

◆ $handlersByName

array MediaWiki\HookContainer\HookContainer::$handlersByName = []
private

handler name and their handler objects

Definition at line 60 of file HookContainer.php.

◆ $nextScopedRegisterId

int MediaWiki\HookContainer\HookContainer::$nextScopedRegisterId = 0
private

The next ID to be used by scopedRegister()

Definition at line 69 of file HookContainer.php.

◆ $objectFactory

ObjectFactory MediaWiki\HookContainer\HookContainer::$objectFactory
private

Definition at line 66 of file HookContainer.php.

Referenced by MediaWiki\HookContainer\HookContainer\__construct().

◆ $registry

HookRegistry MediaWiki\HookContainer\HookContainer::$registry
private

Definition at line 63 of file HookContainer.php.

◆ $tombstones

array MediaWiki\HookContainer\HookContainer::$tombstones = []
private

Tombstone count by hook name.

Definition at line 54 of file HookContainer.php.


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