README

This is a laravel 9 magdicom/hooks wrapper that lets easily use action hooks in your laravel project.

Installation

You can install the package via composer:

composer require magdicom/laravel-hooks

Usage

To call any of the available method you can use the facade:

use Magdicom\LaravelHooks\Facade\Hooks;

Hooks::register("HookName", function($vars){}, 1);

or use the helper function as below:

hooks()->register("HookName", function($vars){}, 1);

Quick Start

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

Parameters split into two types:

Global parameters will be available across all hook names and callbacks, and these can be defined using setParameter and setParameters methods.
Scoped parameters which will be only available to the requested hook name, and could be provided as the second argument of all, first and last methods.

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

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 $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 that you want to provide for all callback functions related to the same hook name.

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

first

Hooks::first(string $hookName, ?array $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 $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.

Testing

composer test

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

Mohamed Magdi

License

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

magdicom / laravel-hooks

Maintainers

Details