Hooks / HookEvent

All addHook*() methods are available on any Wire object. In templates and procedural code use $wire->addHook…; in modules or classes use $this->addHook…. To hook just a single object or API variable instance, replace $wire or $this with the object instance.

addHookAfter() — run after the method (default)

Use when you want to act on or modify the return value after a method runs. This is the most common hook type.

// Hook all Pages::saved events (static hook — fires for all $pages instances)
$wire->addHookAfter('Pages::saved', function(HookEvent $event) {
    $page = $event->arguments(0);
    $event->message("Saved: $page->path");
});

// Modify the return value of Pages::find()
$wire->addHookAfter('Pages::find', function(HookEvent $event) {
    $items = $event->return; // PageArray
    // ... filter or modify $items ...
    $event->return = $items;
});

// Local hook — fires only for this $page instance
$page->addHookAfter('render', function(HookEvent $event) {
    $event->return = str_replace('foo', 'bar', $event->return);
});

addHookBefore() — run before the method

Use when you want to inspect or modify arguments before the method runs, or conditionally skip the original method entirely.

// Modify a Page before save — object modifications take effect without writing back
$wire->addHookBefore('Pages::save', function(HookEvent $event) {
    $page = $event->arguments(0);
    if(!$page->summary) $page->summary = substr(strip_tags($page->body), 0, 200);
});

// Append a condition to every front-end find() — strings must be written back
$wire->addHookBefore('Pages::find', function(HookEvent $event) {
    if(wire()->config->admin) return;
    $selector = $event->arguments(0);
    if(is_string($selector)) {
        $event->arguments(0, "$selector, status!=trash");
    }
});

addHookProperty() — add a new property

Adds a new property to every instance of a class (or a single instance).

// Add a $page->byline property to all Page objects
$wire->addHookProperty('Page::byline', function(HookEvent $event) {
    $page = $event->object;
    $event->return = $page->author . ' — ' . $page->date('F j, Y');
});

echo $page->byline; // "Jane Smith — April 1, 2024"

Use addHookMethod() instead when you want method-call syntax like $page->byline().

addHookMethod() — add a new method

Adds a new callable method to every instance of a class (or a single instance).

// Add a $page->hasAncestor($ancestor) method to all Page objects
$wire->addHookMethod('Page::hasAncestor', function(HookEvent $event) {
    $page = $event->object;
    $ancestor = $event->arguments(0);
    $event->return = $page->parents->has($ancestor);
});

if($page->hasAncestor($pages->get('/products/'))) {
    // ...
}

Hooking multiple methods at once

Any addHook*() method accepts a CSV string or array as its first argument to attach the same handler to multiple methods in one call. The return value is a CSV of hook IDs, accepted as-is by removeHook().

$hookId = $wire->addHookAfter('Pages::saved, Pages::deleted', function(HookEvent $event) {
    // runs after both saved and deleted
});

$wire->removeHook($hookId); // removes all hooks in the CSV

Callback forms

All addHook*() methods accept three callback forms:

// 1. Inline closure (most common)
$wire->addHookAfter('Pages::saved', function(HookEvent $event) {
    // ...
});

// 2. Object + method name (common in classes and modules — $this is usually the object)
$wire->addHookAfter('Pages::saved', $this, 'onPageSaved');
// calls $this->onPageSaved($event) when the hook fires

// 3. Procedural function name (rarely used)
$wire->addHookAfter('Pages::saved', null, 'myHookFunction');
// calls myHookFunction($event) when the hook fires

addHook*() methods return a hook ID string. Pass it to removeHook() to remove the hook.

$hookId = $wire->addHookAfter('Pages::saved', function(HookEvent $event) {
    // ...
});

// Remove it later
$wire->removeHook($hookId);

// Or remove it from inside the hook itself
$wire->addHookAfter('Pages::saved', function(HookEvent $event) {
    // ...
    $event->removeHook(null); // removes this hook; won't fire again
});

Conditions can be embedded in the method argument string so a hook only fires when specified conditions are met. Multiple conditions can be combined in a single hook.

Object match

Append a selector in parentheses after the class name to only fire when the object matches.

// Only fires when the Page being saved uses the 'product' template
$wire->addHookAfter('Page(template=product)::saved', function(HookEvent $event) {
    // ...
});

Argument match

Append a selector in parentheses after the method name to only fire when argument 0 matches.

// Only fires when argument 0 is an array/object that matches "template=product"
$wire->addHookAfter('Pages::find(template=product)', function(HookEvent $event) {
    // ...
});
// Example call that matches: $pages->find(['template' => 'product']);

// Match specific argument positions: 0:selector, 1:selector
$wire->addHookAfter('Pages::find(0:template=product, 1:limit=10)', function(HookEvent $event) {
    // ...
});
// Example call that matches: $pages->find(['template' => 'product'], ['limit' => 10]);

These selector matches apply to array or object argument values. If argument 0 is a raw selector string like "template=product, limit=10", it is not parsed and matched as a selector by this hook syntax.

Argument type match

Use angle brackets <Type> in the argument match to fire only when the argument is an instance of the specified class. Pipe-separate multiple types for an OR match.

// Only fires when the argument to Pages::saveReady() is a User, Role, or Permission
$wire->addHookAfter('Pages::saveReady(<User|Role|Permission>)', function(HookEvent $event) {
    // ...
});

Return value match

A colon before the parentheses or angle brackets matches against the return value of the method rather than an argument. Use a selector for property matching or angle brackets for type matching.

// Only fires when the returned Inputfield's label contains "Currency"
$wire->addHookAfter('Field::getInputfield:(label*=Currency)', function(HookEvent $event) {
    // ...
});

// Only fires when the returned Inputfield is a radios or checkboxes type
$wire->addHookAfter('Field::getInputfield:<InputfieldRadios|InputfieldCheckboxes>', function(HookEvent $event) {
    // ...
});

Combining conditions

Object match, argument match, and return value match can all be applied in a single hook.

// Field(name!=title)          — field is not named "title"
// ::getInputfield(template=product) — called in context of "product" template
// :(label*=description)       — return value's label contains "description"
$wire->addHookAfter(
    'Field(name!=title)::getInputfield(template=product):(label*=description)',
    function(HookEvent $event) {
        // ...
    }
);

Wire::hasHook()

Check whether a specific method or property is hooked on the current object instance. Considers both static and local hooks, including parent class hooks.

if($pages->hasHook('find()')) {
    // Pages::find() is hooked
}

if($page->hasHook('title')) {
    // Page::title property is hooked
}

• Source files: wire/core/WireHooks/WireHooks.php, wire/core/WireHooks/HookEvent.php
• $hooks API variable: $hooks is available as wire()->hooks or $this->wire()->hooks in modules, but direct use is rarely needed — all developer-facing hook methods live on Wire
• Hookable method convention: any method prefixed with ___ (three underscores) is hookable; e.g. ___find() is the hookable implementation of find()
• Default timing is "after": addHook() and addHookAfter() both default to running after the method; addHookBefore() is an explicit opt-in for before timing
• "Replace" hooks are before hooks: setting $event->replace = true inside addHookBefore() prevents the original method from running — there is no separate "replace hook" type
• Static hooks survive instance changes: static hooks registered via Class::method fire for every instance of that class, including new instances created after the hook was added