How Hooks Work

The way into the system's flow without touching a core file: a name, a running order and a function to run.

Overview

A hook is the point where the core stops and asks "has anyone here got something to say?" An order is saved and it asks. An invoice total is worked out and it asks. A management screen is about to be drawn and it asks. You leave a function behind, and the core calls it on reaching that point.

What this buys you: behaviour added without editing the core. An edited core file comes back on the first update. A hook listener sits in your own file, and the update leaves it alone. This is also how modules bind themselves to the system.

This installation holds 984 hook points spread over seventeen domains by subject. The word in front of the name says what it was opened for.

Prerequisites

• A file for your listener to live in: a .php file in the installation's own coremio/hooks directory, or a module's hooks.php.
• A finished installation. No listener loads before the setup wizard is done (see the pitfalls below).
• The exact name of the hook you are binding to. A wrong name does nothing at all and reports nothing either.

Structure

Listener files are read on their own and you register them nowhere. Two places are swept and both load together.

coremio/hooks/*.php                     # the installation's own listeners
coremio/modules/{Type}/{Name}/hooks.php # every module's own listeners

Loading happens when the first hook runs, not at page start. The files are read once and stay in memory for that request. So adding a listener restarts nothing: you drop the file in and it runs on the next request.

A hook takes as many listeners as you like. They all run by running order, and the smaller number goes first.

Reference

Registering a listener

// The Hook class — coremio/classes/Hook.php
static function add(string $name, int $priority, callable|array $properties): void;

The four listener forms

// 1 — a closure: the common one
Hook::add('action:order.created', 10, function ($order) {
    Crm::push($order['id']);
});

// 2 — a class method: the class is built ONCE and shared across every hook
Hook::add('filter:invoice.late_fee_amount', 10, ['class' => 'AcmeBilling', 'method' => 'adjust']);

// 3 — a static method: no object is built
Hook::add('gate:order.checkout', 10, ['class' => 'AcmeGuard', 'method::static' => 'allow']);

// 4 — the constructor: with NO method key the class is built and THE OBJECT is the return
Hook::add('register:routes', 10, ['class' => 'AcmeRoutes']);

How the core runs a hook

static function run(string $name, mixed ...$args): array;
static function runRefs(string $name, mixed &...$args): array;
static function runDetailed(string $name, mixed ...$args): array;

What all three share: a listener that throws is caught, recorded, and the next one runs. A single broken listener stops neither the core nor the other listeners.

Example

One file, three listeners, three different jobs: catching an event, changing a value and stopping an action.

<?php

// 1 — AN EVENT: an order was written, tell the outside. Our return is not read.
Hook::add('action:order.created', 10, function ($order) {
    Crm::push((int) $order['id'], $order);
});

// 2 — A VALUE: change the row. With & on the first argument the caller's variable changes.
Hook::add('filter:admin.table.rows', 10, function (&$row, $table) {
    if ($table === 'services') $row['name'] = strtoupper($row['name'] ?? '');
});

// 3 — PERMISSION: returning a non-empty string stops the action and that text reaches the user.
Hook::add('gate:order.checkout', 10, function ($member, $items) {
    if (Blocklist::has((int) ($member['id'] ?? 0)))
        return 'This account cannot order.';
    return null;                    // null or an empty string: the flow carries on
});

It ends the moment you drop the file in. There is no registering, no build and no restart; all three run on the next request.

Pitfalls

Related Articles

• Writing a Hook Listener
• Hook Domains
• Common Hook Scenarios