Hooks and filters

Hooks let an app react to what core does (actions) and change what core produces (filters). Register them in your app's boot(), or in a theme's boot.php.

Actions and filters

An action tells you something happened. Your callback's return value is ignored:

$this->addAction('post.created', function (array $post) {
    $this->log('New post', ['id' => $post['id'], 'title' => $post['title']]);
});

A filter passes a value through every callback. Each one returns the value, changed or not:

$this->addFilter('post.content', function (string $html, ?array $post = null): string {
    return $html . '<p class="signature">Thanks for reading.</p>';
}, 20, 2);

The full signatures:

$this->addAction(string $tag, callable $callback, int $priority = 10, int $acceptedArgs = 1);
$this->addFilter(string $tag, callable $callback, int $priority = 10, int $acceptedArgs = 1);

• Priority: lower runs first. Core's own post.content renderer runs at 5, so a filter at 10 or 20 sees finished HTML.
• Accepted arguments: how many of the hook's arguments your callback receives. The default is 1. Pass 2 or 3 to get the extra context listed below.

You can fire your own hooks too, so other apps can extend yours:

$this->doAction('event-manager.ticket_sold', $ticket);
$price = $this->applyFilters('event-manager.price', $price, $event);

Prefix your hook names with your app's slug.

Content

All of these fire for every content type, including page and app types. Check $post['type'] when you only care about one.

Filtered HTML

Post HTML from anyone without the unfiltered_html capability is filtered when it's saved. Editors and administrators have that capability. Filtering removes scripts, event handlers, javascript: links, forms and iframes from unknown hosts. It also applies to posts your app writes while nobody is signed in, such as from a scheduled task. If your app writes HTML it generated and trusts:

$this->addFilter('post.unfiltered_html', function (bool $allowed, ?array $user): bool {
    return $allowed || $this->importing;   // a flag your import task sets while it runs
}, 10, 2);

To let filtered posts embed another video host:

$this->addFilter('html.iframe_hosts', fn(array $hosts) => [...$hosts, 'player.example.org/embed/']);

Users

User rows passed to hooks don't include the password hash.

Comments

Taxonomies, media and mail

Front end

Admin

Editor and blocks

SEO

seo.enabled, seo.groups, seo.title, seo.description, seo.canonical, seo.robots, seo.image, seo.jsonld and seo.head. Each receives the value and a context array (pass 10, 2). See SEO, dates and images.

API, MCP and AI discovery

See Give your app an MCP tool for a worked example of the mcp.* hooks.

Good habits

• Keep callbacks fast. Many hooks run on every page view.
• Return the value from every filter, even when you didn't change it.
• A filter's input may come from users: escape what you print, validate what you store.
• Exceptions in hooks are caught in most places, but don't rely on it: one thrown exception can cost the rest of your callback's work.