Hooks

Letting add-ons connect to events within Statamic.

A hook allows you to run arbitrary code when certain events happen in Statamic. Hooks give you a clean way to interact with the system (as well as other add-ons) without needing to hack things in a way that might break later.

Hooking Into Events

The first step to adding hooks to your add-on is to create the file that will contain your hooks. This file will be named after your add-on, for example, if your add-on is in a folder called hiking_boots, your hooks file will be hooks.hiking_boots.php. This file goes into the root-level of your add-on’s folder.

Next, within that file we need to create an object that extends Statamic’s Hooks object. The name of the object must be Hooks_ followed by the name of your add-on, like so:

class Hooks_hiking_boots extends Hooks
{

}

There are no required methods to add within your Hooks object, you’ll simply add a function for each hook you want to listen for, which will contain the code you want to perform when it happens.

As an example, let’s say that you want to add some CSS to the head of the Control Panel for your add-on. You can do this by hooking into the control_panel__add_to_head hook, like so:

class Hooks_hiking_boots extends Hooks
{
    public function control_panel__add_to_head() {
        return $this->css->link('hiking_boots.css');
    }
}

This command will add an HTML link tag for your add-on’s hiking_boots.css file. This hook is going to print out whatever is returned into the head tag of the Control Panel.

Statamic comes with a number of hooks available to you. Each one can do something different, so for example, returning HTML won’t work every time. Consult the hook’s documentation for information on how each will work and what you need to do to use it properly.

Creating Your Own Hookable Events

Creating hookable events isn’t something reserved for Statamic’s core, you can have your add-on trigger hooks as well. To do so, you’ll use $this->runHook() within any aspect of your add-on.

For example, to create a kick hook for your hiking_boots add-on, you would do the following:

$this->runHook('kick');

This is the simplest form of a hook. To hook into this event, another add-on would use the hook method hiking_boots__kick. As you can see, hook names are automatically namespaced with your add-on’s name, letting you not worry about stepping on toes with your hook names.

Hook Types

There are three types of hooks that you can create:

• A call hook (the default type) will simply call each of the hooks that it finds for a given event, not passing any resulting data along if more than one hook is found
• A cumulative hook will merge together the results of each called hook method, giving you one big value at the end; if an array is being returned each time, you’ll have one big array at the end; if a string is being returned, you’ll end up with a long, concatenated string
• A replace hook will overwrite the passed data with each call hook method, which means your final output from running a hook will be the last hook method called in the chain

Which you use is up to you, and will depend on what your hook is attempting to accomplish.