Hooks

Events that can be hooked into.

Hooks let add-ons “hook” into core Statamic functionality. Some of these hooks just tell add-ons when a certain event is happening, others will pass in data and let any add-on hooking in to alter the data as it passes by. There are a limited number of hooks available at the moment, but the list will be expanding soon.

Anatomy of a Hook

Hooks can be called anywhere, even within add-ons, by calling Hook::run(). This method takes five parameters.

• namespace is the namespace where this hook lives. For add-ons, this should be the name of your add-on.
• hook is the name of the hook being called. This can be anything, but best practice says this describes the event happening.
• type is either cumulative, replace, or call. More on those in a minute.
• return is a value that should be returned after all hooks have been run. Depending on the type called, this value can sometimes be altered by the hooks called.
• data is data to pass into any hooks found, it can be a string, number, array, boolean or null, whichever makes the most sense for the hook. Documentation will say what data is for each hook.

Add-ons have a shortcut for running hooks in their own namespace:

$this->runHook($hook, $type=null, $return=null, $data=null);

This shortcut will fill in your add-on’s namespace for you.

Types of Hooks

Each hook that gets triggered has the opportunity to pass in a return value. This value is what will be returned after hooks have been found and run. There are three types of hooks in Statamic (the type is determined by the triggering event), some of which let you alter the value of return as it passes by.

The three types:

• cumulative hooks append any value returned by found hooks to the return argument that’s passed in by the triggering event. This hook returns the resulting cumulative value once all hooks have been called.
• replace hooks replace the value of return with whatever gets returned by each hook as it’s called. In this case, the last hook called will control the value being returned.
• call hooks do not let hooks alter the return value in anyway, they simply allow add-ons know when a certain event is happening. These hooks can perform any tasks they need to do, and once done, whatever value was originally passed into return will be returned by the hook. This is the default hook type.

An Example

To call a hook, you’ll add a method in your add-on’s hooks file that is the namespace, followed by two underscores, followed by the hook name. As an example, Statamic has a _render__after hook. _render is the namespace (Statamic’s core front-end hooks are all prepended with an underscore), and after is the name of the hook itself.

This is a replace hook that passed in the rendered HTML page in as both the return value and the data value.

note Why both? Because each parameter does something different, and in this instance, the returned value that can be replaced is also useful to pass into the hook for it to see. It doesn’t always make sense to have the same return and data values, but in this case, it does.

The call within Statamic looks something like this:

$html = Hook::run('_render', 'after', 'replace', $html, $html);

This is going to take the result of running this hook and use that value as the HTML that will be rendered to the screen. To use this within an add-on, you’ll create a method like the following within your add-on’s hooks file.

public function _render__after($data)
{
    // perhaps we want to reverse the order of the HTML that came in
    // pretend that makes sense and is a good idea
    return strrev($data);
}

This function will take the HTML of the rendered page (which is passed in as $data), reverses it, then returns that. This reversed-HTML will then be rendered by Statamic as the final page. Remember that within your hook, you can perform any sort of PHP you can think of, and in this case, you’ll probably want to come up with something more useful than reversing markup.

Available Hooks

Below is a complete list of hooks available, the type of hook each one is, and what data (if any) is being passed in.

Control Panel

Hook	Type	Data	Description
control_panel__add_to_head	culumative	N/A	Add HTML/JavaScript/CSS into the head tag of Control Panel pages.
control_panel__add_to_foot	cumulative	N/A	Add HTML/JavaScript/CSS into the bottom of the body tag of Control Panel pages.
control_panel__add_to_publish_form	cumulative	N/A	add hidden inputs to the default publish form in the Control Panel.
control_panel__publish	replace	form submission	alter the data submitted when content is saved in the Control Panel.
control_panel__delete	call	N/A	run code when content is deleted.

Front-End

Hook	Type	Data	Description
_routes__before	call	N/A	run code before routes are run on the front-end.
_render__before	call	N/A	run code after data has been determined but just before the page is parsed and rendered.
_render__after	replace	N/A	modify the rendered HTML
request__post	call	N/A	run code when Statamic detects a POST has been made. This happens before _routes__before, and will have access to the $_POST global, and allows you to make changes as needed before routing starts.

Triggering Hooks via URL

You can also trigger hooks via URL. The most useful implementation of this is posting to a hook’s triggering URL. That will call the hook you’ve defined, which can then process a form and do what needs doing afterwards. All hooks triggered via URL are call hooks.

A sample URL hook trigger:

http://example.com/TRIGGER/myaddon/myhook

When hit, this URL will call the myaddon__myhook hook. By default, an empty array will be passed into these hooks as data, but you can load up the array by adding additional segments to your triggering URL.

http://example.com/TRIGGER/myaddon/myhook/data-value/another-thing

This above example will pass in an array containing data-value and another-thing.