Hooks

Overview

A Skinny application provides a set of hooks to which you can register your own callbacks.

What is a hook?

A “hook” is a moment in the Skinny application lifecycle at which a priority list of callables assigned to the hook will be invoked. A hook is identified by a string name.

A “callable” is anything that returns true for is_callable(). A callable is assigned to a hook and is invoked when the hook is called. If multiple callables are assigned to a single hook, each callable is invoked in the order assigned.

How to Use

A callable is assigned to a hook using the Skinny application’s hook() method:

<?php
$app = \Skinny\Skinny::newInstance();
$app->hook('the.hook.name', function () {
    //Do something
});

The first argument is the hook name, and the second argument is the callable. Each hook maintains a priority list of registered callables. By default, each callable assigned to a hook is given a priority of 10. You can give your callable a different priority by passing an integer as the third parameter of the hook() method:

<?php
$app = \Skinny\Skinny::newInstance();
$app->hook('the.hook.name', function () {
    //Do something
}, 5);

The example above assigns a priority of 5 to the callable. When the hook is called, it will sort all callables assigned to it by priority (ascending). A callable with priority 1 will be invoked before a callable with priority 10.

Hooks do not pass arguments to their callables. If a callable needs to access the Skinny application, you can inject the application into the callback with the use keyword or with the Skinny application’s static getInstance() method:

<?php
$app = \Skinny\Skinny::newInstance();

// If $app is in scope
$app->hook('the.hook.name', function () use ($app) {
    // Do something
});

// If $app is out of scope
$app->hook('the.hook.name', function () {
    $app = \Skinny\Skinny::getInstance();
    // Do something
});

Defaults

These are the default hooks always invoked in a Skinny application.

skinny.before

This hook is invoked before the Skinny application is run and before output buffering is turned on (if output.buffered is true). This hook is invoked once during the Skinny application lifecycle.

skinny.before.router

This hook is invoked after output buffering is turned on and before the router is dispatched. This hook is invoked once during the Skinny application lifecycle.

skinny.before.dispatch

This hook is invoked before the current matching route is dispatched. Usually this hook is invoked only once during the Skinny application lifecycle; however, this hook may be invoked multiple times if a matching route chooses to pass to a subsequent matching route.

skinny.after.dispatch

This hook is invoked after the current matching route is dispatched. Usually this hook is invoked only once during the Skinny application lifecycle; however, this hook may be invoked multiple times if a matching route chooses to pass to a subsequent matching route.

skinny.after.router

This hook is invoked after the router is dispatched, before the Response is sent to the client, and after output buffering is turned off. This hook is invoked once during the Skinny application lifecycle.

skinny.after

This hook is invoked after output buffering is turned off and after the Response is sent to the client. This hook is invoked once during the Skinny application lifecycle.

Custom

Custom hooks may be created and invoked in a Skinny application. When a custom hook is invoked with applyHook(), it will invoke all callables assigned to that hook. This is exactly how the Skinny application’s default hooks work. In this example, a custom hook called “my.hook.name” is applied. All callables previously registered for this hook will be invoked.

<?php
$app = \Skinny\Skinny::newInstance();
$app->applyHook('my.hook.name');

When you run the above code, any callables previously assigned to the hook “my.hook.name” will be invoked in order of priority (ascending).

Of course, callables must be registered to a hook before the hook is applied. Otherwise, there's nothing to invoke.