Actions

Actions

Use an action when something should happen but the caller does not need a value back. Actions are synchronous and ordered: register callbacks with addAction(), then run them with doAction().

For example, an order-created action can notify an integration and write an audit entry without coupling the order class to either detail.

Register and run an action

The action methods have two jobs:

Method	Use it for	Returns
addAction(string $hookPoint, array|callable $callback, int $priority = 10)	Registering a callback for a named side effect. The callback receives the arguments passed to doAction().	A RegistrationHandle for the exact registration.
doAction(string $hookPoint, mixed ...$arguments)	Running the registered action callbacks in priority order.	void; callback return values are ignored.

The default priority is 10. Use a lower number when a listener must run earlier, or a higher number when it should run later.

Callbacks receive the extra arguments passed to doAction(), in the same order:

PHP

use Magdicom\Hooks;

$hooks = new Hooks();

$hooks->addAction('invoice.paid', static function (int $invoiceId, string $currency): void {
    // Write an audit entry or notify a synchronous integration.
}, priority: 10);

$hooks->doAction('invoice.paid', 42, 'USD');

Laravel

hooks()->addAction('invoice.paid', static function (int $invoiceId, string $currency): void {
    // Write an audit entry or notify a synchronous integration.
}, priority: 10);

hooks()->doAction('invoice.paid', 42, 'USD');

doAction() returns void. Callback return values are ignored, so use an action for side effects rather than for producing a value. You can pass any number of explicit arguments after the hook point.

Priority and ordering

The default priority is 10. Lower numeric priorities run first. When two listeners have the same priority, their registration order is preserved:

<?php

declare(strict_types=1);

use Magdicom\Hooks;

$hooks = new Hooks();

$hooks->addAction('cache.refreshed', static function (): void {
    // Runs first.
}, priority: 5);

$hooks->addAction('cache.refreshed', static function (): void {
    // Runs second.
}, priority: 10);

$hooks->doAction('cache.refreshed');

Hooks takes a sorted snapshot before it starts. Adding or removing a listener inside a callback does not change the callbacks already selected for this run; the change is visible on the next run. Exceptions reach the caller.

Empty actions

Calling doAction() with no listeners is safe: nothing runs and the method returns void.

Remove a registration

addAction() returns a RegistrationHandle. Its remove() method removes that exact registration and returns true; calling it again returns false:

<?php

declare(strict_types=1);

use Magdicom\Hooks;

$hooks = new Hooks();

$handle = $hooks->addAction('cache.refreshed', static function (): void {
    // This exact registration can be removed later.
});

$handle->remove();
$hooks->doAction('cache.refreshed');

The handle belongs to the Hooks instance that created it. If you prefer callback-based removal, removeAction($hookPoint, $callback, $priority) removes the first matching callback at that priority. Use removeAllActions(?string $hookPoint = null) to remove action registrations in bulk.

Actions do not transform values or collect results. Use filters for a sequential value or collectors for one result per listener.