Writing a Hook Listener

Writing the function that binds to a hook: taking the parameters in order, giving the return its contract asks for.

Overview

A listener is three things: the name you bind to, the number that is your place in the queue, the function that runs. The hard part is none of those. The hard part is getting the function's signature and return right.

Every hook carries its own contract. One hands you the value by reference and waits for you to change it. One prints the text you return. One throws that text as an error and stops the action. One never looks at your return.

Reading the contract wrong reports nothing: the listener runs and nothing happens.

Prerequisites

• How Hooks Work read first.
• The name of the hook you bind to, and its entry. The parameters get their meaning there.
• A file for the listener: one under coremio/hooks, or your module's hooks.php.

Step by Step

1. Read the contract

1. A hook's entry holds three lines: Mechanism, Parameters, Return contract. Read all three.
2. Do not decide from the word in front of the name. On measuring, part of the filter family was called with a copy.
3. The Ref column decides. Take a marked parameter with & and you can change it.

2. Write the signature

1. Take the parameters in the order the hook gives them. The names are yours, the order is not.
2. Leave out trailing parameters you do not need. Fewer is safe, more drops the listener.
3. Take the parameter you mean to change with &.

// filter:invoice.late_fee_amount — the entry's order: &$fee, $invoice, $cycle
Hook::add('filter:invoice.late_fee_amount', 10, function (&$fee, $invoice) {
    if ((int) ($invoice['user_id'] ?? 0) === 1) $fee = 0.0;   // third parameter left out
});

3. Give the return

1. Do what the entry's Return contract line says. The spread below helps, but that line decides.
2. Return null where you mean to touch nothing.
3. Where you stop an action, return the sentence the user will read.

4. Prove it ran

1. Put the file in place and do the work that fires the hook. No restart is needed.
2. Where nothing happened, read the error log. A Hook execution error record says the listener ran and threw.
3. A Hook listener unresolved record says the class or method name is wrong.
4. An empty log means the listener was never called: the name is wrong, or the file sits in neither swept place.
5. For a definite answer, run the hook in diagnosis mode.

foreach (Hook::runDetailed('action:service.created', $id, $data) as $row) {
    echo $row['source']['file'] . ':' . $row['source']['line'] . "\n";
    if ($row['error'] !== null) echo '  FAILED: ' . $row['error'] . "\n";
}

Reference

The spread below was counted from the entries of 984 hooks. It shows what to expect in a family. It is not the truth for any single hook: every row holds a minority that behaves otherwise.

The running order

A smaller number runs first. The same number cannot be taken twice: a second listener slides to the next free number.

Pick the number against the other listeners. Take a large one to change a value with the last word. Take a small one to stop an action before anyone else.

Example

One installation's rules for corporate customers: no late fee, a word to an outside system when a service opens, no deleting a service while the account owes money.

<?php

// A VALUE: zero the late fee by reference.
Hook::add('filter:invoice.late_fee_amount', 10, function (&$fee, $invoice) {
    if (Corporate::has((int) ($invoice['user_id'] ?? 0))) $fee = 0.0;
});

// AN EVENT: a service opened. Our return is not read.
Hook::add('action:service.created', 10, function ($id, $data) {
    if (Corporate::has((int) ($data['owner_id'] ?? 0))) Crm::openedService($id, $data);
});

// PERMISSION: a non-empty string stops the delete; the operator reads this sentence.
Hook::add('gate:service.delete', 10, function ($service) {
    $uid = (int) ($service['owner_id'] ?? 0);
    if (Corporate::has($uid) && Corporate::owes($uid))
        return 'A corporate account with an unpaid invoice keeps its services.';
    return null;
});

All three sit in one file under three different contracts. One changes its parameter, one returns nothing, one returns text and cuts the action short.

Pitfalls

Related Articles

• How Hooks Work
• Hook Domains
• Common Hook Scenarios