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 amphibee/hookable

Usage

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

Actions

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

Registering actions:

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

use AmphiBee\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 AmphiBee\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 AmphiBee\Hooks\Action;

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

Removing actions:

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

use AmphiBee\Hooks\Action;

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

Filters

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

Registering filters:

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

use AmphiBee\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 AmphiBee\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 AmphiBee\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 AmphiBee\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 AmphiBee\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 / hookable

Maintainers

Details