README

#Hook

If you have ever used an event manager, you will find the Hooks component very similar. With the HookManager you can create hooks, on which you can hook callbacks to be executed when the hooks are triggered.

• Installation
• Usage in the Asgard Framework
• Usage outside the Asgard Framework
• Create a hook
• Trigger a hook
• Executing callbacks before and after hooks
• Filters
• The HooksChain Object
• HooksContainer

##Installation If you are working on an Asgard project you don't need to install this library as it is already part of the standard libraries.

composer require asgard/hook 0.*

##Usage in the Asgard Framework

$hm = $container['hooks'];

The container is often accessible as a method parameter or through a ContainerAware object. You can also use the singleton but it is not recommended.

##Usage outside the Asgard Framework

$hm = new \Asgard\Hook\HookManager;

##Create a hook

$hm->hook('name_of_hook', function($chain, $param1) {
	// ...
});

The first parameter is always a \Asgard\Hook\HooksChain object. The next ones are passed when the hook is triggered.

##Trigger a hook

$hm->trigger('name_of_hook', [$param]);

If you want to execute your own function when calling trigger, use the last argument:

$hm->trigger('name_of_hook', [$param], function($chain, $param) {
	// ...
});

##Executing callbacks before and after hooks To execute functions before a hook:

$hm->preHook('name_of_hook', function($chain, $param) {
	// ...
});

And after:

$hm->postHook('name_of_hook', function($chain, $param) {
	// ...
});

##Filters Hooks can be used as filters when parameters are passed by reference

$hm->hook('name_of_hook', function($chain, &$param) {
	$param = 123;
});
$hm->trigger('name_of_hook', [&$param]);

##The HooksChain object The chain contains all the callbacks to be executed in a hook. If a function returns a value, the chain stops and the value is returned by the trigger method.

The chain call also be stopped by calling:

$chain->stop();

The function calling the stop method will be the last one to be executed.

To know how many functions have been executed in a hook:

$hm->trigger('name_of_hook', [$param], null, $chain);
$count = $chain->executed;

Here we provide a reference to retrieve the chain object and its executed property.

##HooksContainer A HooksContainer is a class containing hooks. It extends Asgard\Hook\HooksContainer and contains methods that are matched to hooks with annotations.

Example:

<?php
namespace Bundle\Hooks;

class SomeHooks extends \Asgard\Hook\HooksContainer {
	/**
	 * @Hook("Asgard.Http.Start")
	 */
	public static function start($chain, $request) {
		//do something when HTTP starts processing a request
	}
}

Here the method start is executed when the hook "Asgard.Http.Start" is triggered.

If you are working with a Asgard project, all HooksContainer in the Hooks/ folder of a bundle are automatically loaded.

If not, you can register the hooks with:

$annotationsReader = new \Asgard\Hook\AnnotationReader;
$hooks = $annotationsReader->fetchHooks('Bundle\Hooks\SomeHooks');
$hookManager->hooks($hooks);

###Contributing

Please submit all issues and pull requests to the asgardphp/asgard repository.

License

The Asgard framework is open-sourced software licensed under the MIT license