README

This package provides an object-oriented API for use with the WordPress Plugin API. The package also includes automatic "number of arguments" calculation and chainable callbacks.

Installation

You can install the package via composer:

composer require digitalbitdev/hooks

Usage

There is a dedicated class for each type of "hook".

Actions

To interact with actions, you need to use the \DigitalBit\Hooks\Action class.

Registering actions:

To register an action, call the Action::add() method. This method takes 3 arguments:

use DigitalBit\Hooks\Action;

Action::add($name, $callback, $priority);

You do not need to provide the number of parameters that the callback takes. This is automatically resolved using the Reflection API.

Chained callbacks:

It is possible to provide extra callbacks that run after your initial callback. For example, you may wish to call one of your application helpers to do something extra.

use DigitalBit\Hooks\Action;

Action::add('init', function () {
    // do something here...
})->then([MyPlugin::class, 'checkUserIsAdmin']);

The chained callbacks will receive the return value and all arguments that the initial callback received.

class MyPlugin
{
    public static function checkUserIsAdmin($resultFromInitialCallback, ...$extraArgs)
    {
        // ...
    }
}

Running actions:

You can fire / run an action using the Action::do() method, as well as pass in arguments just like you would with do_action.

use DigitalBit\Hooks\Action;

Action::do('my_plugin_action', $argument, $another);

Removing actions:

To remove an action, use the Action::remove() method:

use DigitalBit\Hooks\Action;

Action::remove('init', $callbackToRemove, $priority);

Filters

To interact with filters, you need to use the \DigitalBit\Hooks\Filter class.

Registering filters:

To register a filter, use the Filter::add() method:

use DigitalBit\Hooks\Filter;

Filter::add('the_title', function ($title) {
    return $title . ' is the title.';
});

Chained callbacks:

It is possible to provide extra callbacks that run after your initial callback. For example, you may wish to call one of your application helpers to do something extra.

use DigitalBit\Hooks\Filter;

Filter::add('the_title', function ($title) {
    return $title . ' is the title.';
})->then('strtoupper');

The chained callbacks will behave the same way as actions and will receive the return value of the initial callback and then any arguments that were passed to the initial callback.

The example above will pass the return value of $title . ' is the title' to the strtoupper method.

Applying filters:

You can apply filters using the Filter::do() or Filter::apply() methods (Filter::apply() is an alias of Filter::do()). These behave in the same way as the Action::do() method and take the same arguments.

use DigitalBit\Hooks\Filter;

$title = Filter::do('the_title', 'Hello, World!');

// or..
$title = Filter::apply('the_title', 'Hello, World!');

Removing filters:

You can remove filters using the Filter::remove() method. This behaves the same as the Action::remove() method and both use the same underlying logic.

$callback = function () {

};

// logic here...

Filter::remove('the_title', $callback);

Hookable classes

This package provides a convenient Hookable interface that can be used to register single-use class callbacks.

use DigitalBit\Hooks\Contracts\Hookable;

class InitAction implements Hookable
{
    public function execute()
    {
        // ...
    }
}

Action::add('init', InitAction::class);

Receiving hook arguments:

To receive the arguments passed from the caller, define a constructor on your class and assign them to properties:

use DigitalBit\Hooks\Contracts\Hookable;

class TheTitleFilter implements Hookable
{
    private string $title;

    public function __construct(string $title)
    {
        $this->title = $title;
    }

    public function execute()
    {
        if ($this->title !== 'My First Post') {
            return $this->title;
        }

        return "{$this->title} is Amazing!";
    }
}

Filter::add('the_title', TheTitleFilter::class);

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email ryan@digitalbit.dev instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

amphibee / hooks

Maintainers

Details