Hooks
, (*1)
Hooks component for the SlaxWeb/Framework, to execute arbitrary code in regular
application execution. Even when the component is meant for the
SlaxWeb/Framework it can be used outside of it as well. It the SlaxWeb/Logger as
an additional component., (*2)
For ease of use the component provides a Factory and a Service Provider for the
Pimple/Container., (*3)
Installation
Easiest form of installation is through composer, edit your composer.json file
to contain:, (*4)
{
"require": {
"slaxweb/hooks": "~0.5.*@dev"
},
"minimum-stability": "dev"
}
Usage
This section will cover instantiation of the Hooks container, and adding simple
hook definitions to the container, as well as execution of this definition, and
advanced execution of hook definitions., (*5)
Instantiation
You do not need to instantiate the Logger component it self, but you do have to
instantiate the Config component, and make sure that the logger configuration is
loaded, refer to Logger documentation on
how to get this done., (*6)
When you got the dependencies instantiated the usage is pretty straight forward:, (*7)
<?php
use SlaxWeb\Hooks\Container as Hooks;
require_once "vendor/autoload.php";
// instantiate Config object..
// initiate the Hooks container
$hooks = \SlaxWeb\Hooks\Factory::init($config);
// create a hook
$hook = \SlaxWeb\Hooks\Factory::newHook();
$hook->create("hook.name", function (Hooks $container) {
// stuff..
return "I ran!";
});
// add the hook to the container
$hook->addHook($hook);
// some app stuff
// execute the hook
if ($hooks->execute("hook.name") === "I ran!") {
// stuff..
}
You can achieve the same thing using the Pimple Dependency Injection Container,
just make sure that you have registered the Service Providers of all 3
components:
* SlaxWeb/Config
* SlaxWeb/Logger
* SlaxWeb/Hooks, (*8)
When you have all those three providers registered, you can safely use the hooks
container:, (*9)
<?php
use SlaxWeb\Hooks\Container as Hooks;
require_once "vendor/autoload.php":
$container = new Pimple\Container;
// register the providers
$container->register(new \SlaxWeb\Config\Service\Provider);
$container->register(new \SlaxWeb\Logger\Service\Provider);
$container->register(new \SlaxWeb\Hooks\Service\Provider);
// load the config for the logger etc.
$hook = $container["newHook.factory"];
$hook->create("hook.name", function (Hooks $container) {
// stuff ..
return "I ran!";
});
// add the hook to the container
$container["hooks.service"]->addHook($hook);
// some app stuff..
// execute the hook
if ($container["hook.service"]->exec("hook.name") === "I ran!") {
// stuff..
}
Multiple Hook Definitions
As it is already visible from above examples, hook execution method will return
the value of the hook definition. But a single hook point may hold more than one
definition. In this case the exec method will return all return values in an
array, except if the return value of definition was null. If no definition
returned a valid return value, the exec method will return an empty array., (*10)
For a better representation of the above examples, please refer to the code
example bellow:, (*11)
// instantiation of everything required etc.
// create hooks
$hook = $container["newHook.factory"];
$hook->create("hook.name", function (Hooks $container) {
return 1;
});
$container["hooks.service"]->addHook($hook);
$hook = $container["newHook.factory"];
$hook->create("hook.name", function (Hooks $container) {
return null;
});
$container["hooks.service"]->addHook($hook);
$hook = $container["newHook.factory"];
$hook->create("hook.name", function (Hooks $container) {
return 3;
});
$container["hooks.service"]->addHook($hook);
// execute the hook
$container["hooks.service"]->exec("hook.name"); // will return: [1, 2]
// create 'no return' hook
$hook = $container["newHook.factory"];
$hook->create("noreturn.hook", function (Hooks $container) {
// stuff
});
$container["hooks.service"]->addHook($hook);
// execute the hook
$container["hooks.service"]->exec("noreturn.hook"); // will return: []
Definition Execution Interruption
Additionally to multiple definitions per hook, a hook can also prevent other
definitions from executing. For this case an instance of the container is passed
into the hook definition as the first parameter. Each hook may call stopExec
method on that passed in container object, and it will stop execution of other
hook definitions., (*12)
// create hooks
$hook = $container["newHook.factory"];
$hook->create("hook.name", function (Hooks $container) {
$container->stopExec();
return 1;
});
$container["hooks.service"]->addHook($hook);
$hook = $container["newHook.factory"];
$hook->create("hook.name", function (Hooks $container) {
return 2;
});
$container["hooks.service"]->addHook($hook);
$container["hooks.service"]->exec("hook.name"); // will return: 1
Hook definition parameters
When calling the exec method you can pass additional parameters to it, and
all those parameters will be passed on to your hook definition., (*13)
// create hook
$hook = $container["newHook.factory"];
$hook->create("hook.name", function (Hooks $container, string $myParam) {
return $myParam;
});
$container["hooks.service"]->addHook($hook);
$container["hooks.service"]->exec("hook.name", "foo"); // will return: "foo"
Wallogit.com
