Documentation

HookManager
in package

WordPress Hook Manager

Table of Contents

DEFAULT_ACCEPTED_ARGS  = 1
DEFAULT_PRIORITY  = 10
REGISTER_ALL  = 15
REGISTER_CALLBACK  = 1
REGISTER_CLASS  = 4
REGISTER_OBJECT  = 2
REGISTER_STATIC  = 8
addAction()  : bool
Adds a callback function to an action hook.
addFilter()  : bool
Adds a callback function to a filter hook.
applyFilters()  : mixed
Calls the callback functions that have been added to a filter hook.
applyFiltersRefArray()  : mixed
Calls the callback functions that have been added to a filter hook, specifying arguments in an array.
currentAction()  : string
Retrieves the name of the current action hook.
currentFilter()  : string
Retrieves the name of the current filter hook.
didAction()  : int
Retrieves the number of times an action has been fired during the current request.
doAction()  : void
Calls the callback functions that have been added to an action hook.
doActionRefArray()  : void
Calls the callback functions that have been added to an action hook, specifying arguments in an array.
doingAction()  : bool
Returns whether or not an action hook is currently being processed.
doingFilter()  : bool
Returns whether or not a filter hook is currently being processed.
hasAction()  : bool|int
Checks if any action has been registered for a hook.
hasFilter()  : bool|int
Checks if any filter has been registered for a hook.
register()  : void
Register a hook or set of hooks with WordPress. Automatically registers any callable, class or object according to $mode. May attempt to register multiple ways if applicable.
registerCallback()  : void
Registers hooks for a callback with WordPress.
registerClass()  : void
Registers hooks for a class with WordPress.
registerObject()  : void
Registers hooks for an object with WordPress.
removeAction()  : bool
Removes a callback function from an action hook.
removeAllActions()  : bool
Removes all of the callback functions from an action hook.
removeAllFilters()  : bool
Removes all of the callback functions from a filter hook.
removeFilter()  : bool
Removes a callback function from a filter hook.

Constants

DEFAULT_ACCEPTED_ARGS

public mixed DEFAULT_ACCEPTED_ARGS = 1

REGISTER_CALLBACK

public mixed REGISTER_CALLBACK = 1

Methods

addAction()

Adds a callback function to an action hook.

public static addAction(string $hookName, callable|string|array<string|int, mixed> $callback[, int $priority = null ][, int $acceptedArgs = null ]) : bool
Parameters
$hookName : string

The name of the action to add the callback to.

$callback : callable|string|array<string|int, mixed>

The callback to be run when the action is called.

$priority : int = null

Optional. Used to specify the order in which the functions associated with a particular action are executed. Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the action.

$acceptedArgs : int = null

Optional. The number of arguments the function accepts.

Return values
bool —

Always returns true.

addFilter()

Adds a callback function to a filter hook.

public static addFilter(string $hookName, callable|string|array<string|int, mixed> $callback[, int $priority = null ][, int $acceptedArgs = null ]) : bool
Parameters
$hookName : string

The name of the filter to add a the callback to.

$callback : callable|string|array<string|int, mixed>

The callback to be run when the filter is applied.

$priority : int = null

Optional. Used to specify the order in which the functions associated with a particular filter are executed. Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the filter.

$acceptedArgs : int = null

Optional. The number of arguments the function accepts.

Return values
bool —

Always returns true.

applyFilters()

Calls the callback functions that have been added to a filter hook.

public static applyFilters(string $hookName, mixed $value, mixed ...$args) : mixed
Parameters
$hookName : string

The name of the filter hook.

$value : mixed

The value to filter.

$args : mixed

Additional parameters to pass to the callback functions.

Tags
throws
UninitializedError

If WordPress has not been initialized.

Return values
mixed —

The filtered value after all hooked functions are applied to it.

applyFiltersRefArray()

Calls the callback functions that have been added to a filter hook, specifying arguments in an array.

public static applyFiltersRefArray(string $hookName, array<string|int, mixed> $args) : mixed
Parameters
$hookName : string

The name of the filter hook.

$args : array<string|int, mixed>

The arguments supplied to the functions hooked to $hookName.

Tags
throws
UninitializedError

If WordPress has not been initialized.

Return values
mixed —

The filtered value after all hooked functions are applied to it.

currentAction()

Retrieves the name of the current action hook.

public static currentAction() : string
Tags
throws
UninitializedError

If WordPress has not been initialized.

Return values
string —

Hook name of the current action.

currentFilter()

Retrieves the name of the current filter hook.

public static currentFilter() : string
Tags
throws
UninitializedError

If WordPress has not been initialized.

Return values
string —

Hook name of the current filter.

didAction()

Retrieves the number of times an action has been fired during the current request.

public static didAction(string $hookName) : int
Parameters
$hookName : string

The name of the action hook.

Tags
throws
UninitializedError

If WordPress has not been initialized.

Return values
int —

The number of times the action hook has been fired.

doAction()

Calls the callback functions that have been added to an action hook.

public static doAction(string $hookName, mixed ...$args) : void
Parameters
$hookName : string

The name of the action to be executed.

$args : mixed

Optional. Additional arguments which are passed on to the functions hooked to the action. Default empty.

Tags
throws
UninitializedError

If WordPress has not been initialized.

Return values
void —

doActionRefArray()

Calls the callback functions that have been added to an action hook, specifying arguments in an array.

public static doActionRefArray(string $hookName, array<string|int, mixed> $args) : void
Parameters
$hookName : string

The name of the action to be executed.

$args : array<string|int, mixed>

The arguments supplied to the functions hooked to $hookName.

Tags
throws
UninitializedError

If WordPress has not been initialized.

Return values
void —

doingAction()

Returns whether or not an action hook is currently being processed.

public static doingAction([string|null $hookName = null ]) : bool
Parameters
$hookName : string|null = null

Optional. Action hook to check. Defaults to null, which checks if any action is currently being run.

Tags
throws
UninitializedError

If WordPress has not been initialized.

Return values
bool —

Whether the action is currently in the stack.

doingFilter()

Returns whether or not a filter hook is currently being processed.

public static doingFilter([null|string $hookName = null ]) : bool
Parameters
$hookName : null|string = null

Optional. Filter hook to check. Defaults to null, which checks if any filter is currently being run.

Tags
throws
UninitializedError

If WordPress has not been initialized.

Return values
bool —

Whether the filter is currently in the stack.

hasAction()

Checks if any action has been registered for a hook.

public static hasAction(string $hookName[, callable|string|array<string|int, mixed>|false $callback = false ]) : bool|int
Parameters
$hookName : string

The name of the action hook.

$callback : callable|string|array<string|int, mixed>|false = false

Optional. The callback to check for. This function can be called unconditionally to speculatively check a callback that may or may not exist. Default false.

Return values
bool|int —

If $callback is omitted, returns boolean for whether the hook has anything registered. When checking a specific function, the priority of that hook is returned, or false if the function is not attached.

hasFilter()

Checks if any filter has been registered for a hook.

public static hasFilter(string $hookName[, callable|string|array<string|int, mixed>|false $callback = false ]) : bool|int

Note: the native WP_Hook functions will result in overriding if the callback signature matches an existing callback, but this funtion will allow duplicates. This should be irrelevant since the duplicated callback will be overridden when wordpress loads the filters.

Parameters
$hookName : string

The name of the filter hook.

$callback : callable|string|array<string|int, mixed>|false = false

Optional. The callback to check for. This function can be called unconditionally to speculatively check a callback that may or may not exist. Default false.

Return values
bool|int —

If $callback is omitted, returns boolean for whether the hook has anything registered. When checking a specific function, the priority of that hook is returned, or false if the function is not attached.

register()

Register a hook or set of hooks with WordPress. Automatically registers any callable, class or object according to $mode. May attempt to register multiple ways if applicable.

public static register(callable|string|object $target[, int $mode = self::REGISTER_ALL ]) : void

Anything registerable with registerCallback, registerObject, or registerClass can be registered using HookManager::register(), by default it will support all registration modes.

Mode flags:

  • HookManager::REGISTER_CALLBACK If set and passed a callable, register hooks for all attached Hook attributes.
  • HookManager::REGISTER_OBJECT If set and passed an object, register all public methods with Hook attributes.
  • HookManager::REGISTER_CLASS If set and passed a valid classname, register all static methods with Hook attributes.
  • HookManager::REGISTER_STATIC If passed an object, also register the object's static class methods in addition to instance context methods.

Special Cases:

  • Closures are callables and objects. They can only be registered as callbacks.
  • Objects with the '__invoke' function are both callables and objects. Will register __invoke function as a callback, and the object separately.
  • Objects with static functions have their instance context functions registered and their static functions registered as well if REGISTER_STATIC is set.
Parameters
$target : callable|string|object

Target to register.

$mode : int = self::REGISTER_ALL

Registration mode.

Tags
see
HookManager::registerCallback()

For examples of callback hook attribute configuration.

see
HookManager::registerObject()

For examples of object hook attribute configuration.

see
HookManager::registerClass()

For examples of static class hook attribute configuration.

Return values
void —

registerCallback()

Registers hooks for a callback with WordPress.

public static registerCallback(callable $callback) : void

Will only register callables with Hook attributes.

Examples
Global Function Callback

With all callback types, multiple hooks can be applied.

use ShineUnited\WordPress\Hooks\Action;
use ShineUnited\WordPress\Hooks\Filter;
use ShineUnited\WordPress\Hooks\HookManager;

#[Filter('example-filter-1', 5)]
#[Filter('example-filter-2')]
#[Action('example-action', 15)]
function global_callback($value) {
    // code
}

HookManager::registerCallback('global_callback');
// add_filter('example-filter-1', 'global_callback', 5, 1);
// add_filter('example-filter-2', 'global_callback', 10, 1);
// add_action('example-action', 'global_callback', 15, 1);
Closure Callback
use ShineUnited\WordPress\Hooks\Filter;
use ShineUnited\WordPress\Hooks\HookManager;

$closure =
    #[Filter('example-filter', 5)]
    function($value) {
        // code
    }
;

HookManager::registerCallback($closure);
// add_filter('example-filter', $closure, 5, 1);
Object Method Callback
use ShineUnited\WordPress\Hooks\Filter;
use ShineUnited\WordPress\Hooks\HookManager;

class ObjectHooks {
    #[Filter('example-filter', 5)]
    public function callback($value, $opts) {
        // code
    }
}

$hooks = new ObjectHooks();
HookManager::registerCallback([$hooks, 'callback']);
// add_filter('example-filter', [$hooks, 'callback'], 5, 2);
Static Method Callback
use ShineUnited\WordPress\Hooks\Filter;
use ShineUnited\WordPress\Hooks\HookManager;

class StaticHooks {
    #[Filter('example-filter', 5)]
    public static function callback($value, $opts) {
        // code
    }
}

HookManager::registerCallback([StaticHooks::class, 'callback']);
// add_filter('example-filter', [StaticHooks::class, 'callback'], 5, 2);
Invokable Object Callback

Note: for invokable objects the hook attributes must be applied to the class rather than the '__invoke' function.

use ShineUnited\WordPress\Hooks\Filter;
use ShineUnited\WordPress\Hooks\HookManager;

#[Filter('example-filter', 5)]
class InvokableObject {
   public function __invoke($value, $opts, $flags) {
       // code
   }
}

$callback = new InvokableObject();
HookManager::registerCallback($callback);
// add_filter('example-filter', $callback, 5, 2);
Parameters
$callback : callable

The callback to register.

Return values
void —

registerClass()

Registers hooks for a class with WordPress.

public static registerClass(string $classname) : void

Will only register publically accessible static methods with Hook attributes.

Examples
Multiple Callbacks
use ShineUnited\WordPress\Hooks\Filter;
use ShineUnited\WordPress\Hooks\HookManager;

class StaticCallbacksExample {
    #[Filter('lowercase')]
    public static function lowercase($value) {
        return strtolower($value);
    }

    #[Filter('uppercase')]
    public static function uppercase($value) {
        return strtoupper($value);
    }
}

HookManager::registerClass(StaticCallbacksExample::class);
// add_filter('lowercase', [StaticCallbacksExample::class, 'lowercase'], 10, 1);
// add_filter('uppercase', [StaticCallbacksExample::class, 'uppercase'], 10, 1);
Parameters
$classname : string

The full classname.

Return values
void —

registerObject()

Registers hooks for an object with WordPress.

public static registerObject(object $object[, bool $includeStatic = true ]) : void

Will only register publically accessible methods with relevant attributes.

Examples
Multiple Callbacks
use ShineUnited\WordPress\Hooks\Filter;
use ShineUnited\WordPress\Hooks\HookManager;

class MultipleCallbacksExample {
    #[Filter('lowercase')]
    public function lowercase($value) {
        return strtolower($value);
    }

    #[Filter('uppercase')]
    public function uppercase($value) {
        return strtoupper($value);
    }
}

$callbacks = new MultipleCallbacksExample();
HookManager::registerObject($callbacks);
// add_filter('lowercase', [$callbacks, 'lowercase'], 10, 1);
// add_filter('uppercase', [$callbacks, 'uppercase'], 10, 1);
Static and Instance Callbacks
use ShineUnited\WordPress\Hooks\Action;
use ShineUnited\WordPress\Hooks\Filter;
use ShineUnited\WordPress\Hooks\HookManager;

class MixedTypeExample {
    #[Filter('lowercase')]
    public function lowercase($value) {
        return strtolower($value);
    }

    #[Filter('uppercase')]
    public function uppercase($value) {
        return strtoupper($value);
    }

    #[Action('static-action', 15)
    public static function trigger() {
        // code
    }
}

$callbacks = new MixedTypeExample();
HookManager::registerObject($callbacks, true);
// add_filter('lowercase', [$callbacks, 'lowercase'], 10, 1);
// add_filter('uppercase', [$callbacks, 'uppercase'], 10, 1);
// since $includeStatic is true, the static callback will also be registered
// add_action('static-action', [MixedTypeExample::class, 'trigger'], 15, 0);
Parameters
$object : object

Object to register.

$includeStatic : bool = true

Optional. If false static methods will not be registered.

Return values
void —

removeAction()

Removes a callback function from an action hook.

public static removeAction(string $hookName, callable|string|array<string|int, mixed> $callback[, int $priority = self::DEFAULT_PRIORITY ]) : bool
Parameters
$hookName : string

The action hook to which the function to be removed is hooked.

$callback : callable|string|array<string|int, mixed>

The name of the function which should be removed. This function can be called unconditionally to speculatively remove a callback that may or may not exist.

$priority : int = self::DEFAULT_PRIORITY

Optional. The exact priority used when adding the original action callback. Default 10.

Return values
bool —

Whether the function is removed.

removeAllActions()

Removes all of the callback functions from an action hook.

public static removeAllActions(string $hookName[, int|false $priority = false ]) : bool
Parameters
$hookName : string

The action to remove callbacks from.

$priority : int|false = false

Optional. The priority number to remove them from. Default false.

Return values
bool —

Always returns true.

removeAllFilters()

Removes all of the callback functions from a filter hook.

public static removeAllFilters(string $hookName[, int|bool $priority = false ]) : bool
Parameters
$hookName : string

The filter to remove callbacks from.

$priority : int|bool = false

Optional. The priority number to remove them from. Default false.

Return values
bool —

Always returns true.

removeFilter()

Removes a callback function from a filter hook.

public static removeFilter(string $hookName, callable|string|array<string|int, mixed> $callback[, int $priority = self::DEFAULT_PRIORITY ]) : bool
Parameters
$hookName : string

The filter hook to which the function to be removed is hooked.

$callback : callable|string|array<string|int, mixed>

The callback to be removed from running when the filter is applied. This function can be called unconditionally to speculatively remove a callback that may or may not exist.

$priority : int = self::DEFAULT_PRIORITY

Optional. The exact priority used when adding the original filter callback. Default 10.

Return values
bool —

Whether the function existed before it was removed.

Search results