README

Inspired by WordPress, action hooks are functions that you define to be triggered in specific places of your code, it helps you maintain an organized code by slicing giant code blocks into separated files and/or classes.

Installation

You can install the package via composer:

composer require magdicom/hooks

Usage

Quick Start

use Magdicom\Hooks;

$hooks = new Hooks();

# Register our functions
$hooks->register("Greetings", function($vars){
    return "Hi There,";
}, 1);

$hooks->register("Greetings", function($vars){
    return "This is the second line of greetings!";
}, 2);

# Later we run it
echo $hooks->all("Greetings")->toString("<br>");

The above example will output

Hi There,
This is the second line of greetings!

Output

When you call any of all, first or last methods, the corresponding hook functions will be executed and their output will be saved in a special property to be exported later using toString or toArray methods.

Callbacks

Closure

$hooks->register("Callback", function($vars) {
    return "Closure";
});

Function Name

function simple_function_name($vars){
    //
}

$hooks->register("Callback", "simple_function_name");

Object Method

class FooBar {
    public function methodName($vars){
        //
    }
}

$object = new FooBar;

$hooks->register("Callback", [$object, 'methodName']);

$hooks->register("Callback", [(new FooBar), 'methodName']);

Static Method

class FooBar {
    public static function staticMethodName($vars){
        //
    }
}

$hooks->register("Callback", ['FooBar', 'staticMethodName']);

in case this is not a static method, an object will be created and the provided method will be called.

Parameters

With each of hook callback functions execution an array of parameters could be passed to it to help it perform the required action.

Global Parameters

Global parameters could be defined using setParameter and setParameters methods and these parameters will be available across all hook points and callbacks.

Scoped parameters

The opposite of global parameters, the scoped parameters only available for the specified action hook point, and could be provided as the second argument of all, first and last methods.

When you provide it as an array, the values of scoped parameters will temporarily replace (similar key entries) global parameters and passed to the register methods' callback as a merged array.

When the parameter provided as a class object it will be accessible from the register method as the first argument, and the global parameters will be accessible via the second argument.

class FooBarBaz {
    public $id;

    public function __construct(int $id){
        $this->id = $id;
    }
}

$hooks = new Hooks();

$hooks->setParameters([
    "name" => "Bar",
]);

$hooks->register("ParameterAsObject", function ($fooBarBaz, $params) {
    return [$fooBarBaz->id, $params['name']];
});

echo $hooks->all("ParameterAsObject", (new FooBarBaz(100))->toString("\n");

// Output will be
100
Bar

Priority

When you need to ensure that certain hook functions should be executed in sequence order, here it comes $priority which is the 3rd and last argument of register method.

Methods

__construct

$hooks = new Hooks(?array $parameters);

The class constructor method will optionally accept a name, value pair array.

register

$hooks->register(string $hookName, array|callable $callback, ?int $priority): self

$hookName this can be anything you want, its like a group name where all other related action hook functions will be attached to.
$callback only accepts callable functions.
$priority (optional) used to sort callbacks before being executed.

all

$hooks->all(string $hookName, array|object|null $parameters): self

Will execute all callback functions of the specified hook name, by default it will return the output as string, check output section for more options.

$hookName the hook name you want to execute its callback functions.
$parameters optional key, value pair array (or object) that you want to provide for all callback functions related to the same hook point.

Please Note: parameters provided via this method will be available only in the scope of the specified hook point, to specify global parameters use setParameter, setParameters methods instead.

first

$hooks->first(string $hookName, array|object|null $parameters): self

Similar to all method in every aspect with the exception that only the first callback (after sorting) will be executed.

last

$hooks->last(string $hookName, array|object|null $parameters): self

Similar to all method in every aspect with the exception that only the last callback (after sorting) will be executed.

toArray

$hooks->toArray(): array

Will return output of the last executed hook name functions as an array.

toString

$hooks->toString(?string $separator): string

Will return output of the last executed hook name functions as one string.

$separator could be used to separate the output as you need (e.g: "\n", "<br>").

setParameter

$hooks->setParameter(string $name, mixed $value): self

Use this method to define a parameter that will be accessible from any hook function.

$name name of the parameter.
$value value of the parameter could be string, array or even an object.

P.S: if the parameter already defined then its old value will be replaced by the value provided here.

setParameters

$hooks->setParameters(array $parameters): self

Same as setParameter but here it accepts a name, value pair array as its only argument.

setSourceFile

$hooks->setSourceFile(?string $path): self

Used in conjunction with the debug method.

debug

$hooks->debug(callable|null $callback): self

To enable the debug feature you need to call this method by providing a callback function, this function should accept a single argument that will be the debug info/message.

$hooks->debug(function($message){
    // Will print debug message(s)
    echo $message . PHP_EOL;
});

$hooks->setSourceFile("/path/to/file/filename.php");

$hooks->register("Greetings", "FooBar::log");

$hooks->all("Greetings");

will output

+ Added Source File: /path/to/file/filename.php
+ Hook Point: Greetings, New Callback Defined:
        -- Source: /path/to/file/filename.php
        -- Callback: FooBar::log
        -- Priority: 1
+ Hook Point: Greetings, Callback Functions Sorted!
+ Hook Point: Greetings, Output Generated For All Callback Functions!

Testing

composer test

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Credits

Mohamed Magdi

License

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

magdicom / hooks

Maintainers

Details