Introduction

Hooks 2.x Beta

Hooks lets your application expose named places where other code can participate without changing the original class. These places are called hook points. A hook point can run side effects, transform a value, or gather contributions from several callbacks.

The core package is framework-independent and synchronous. Use a Magdicom\Hooks instance in a plain PHP application; the core package does not add global helper or static state. If you use Laravel, the optional integration adds auto-discovery, container-backed resolution, a facade, and the hooks() helper. The helper and facade resolve the same Laravel singleton, while the underlying model stays the same: callbacks run in a clear order during the current call.

This site covers magdicom/hooks v2.0.0-beta.2 and magdicom/laravel-hooks v2.0.0-beta.3. The source audit links the package metadata, implementation, and tests behind these pages.

Quick start

The hook model stays the same in both environments. The PHP version creates the framework-independent core instance; Laravel provides the application-level hooks() helper:

PHP

use Magdicom\Hooks;

$hooks = new Hooks();
$listener = static function (int $invoiceId): void {
    error_log("Invoice {$invoiceId} was paid.");
};
$invoiceId = 42;

$hooks->addAction('invoice.paid', $listener);
$hooks->doAction('invoice.paid', $invoiceId);

Laravel

$invoiceId = 42;
hooks()->addAction('invoice.paid', static function (int $invoiceId): void {
    logger()->info('Invoice paid.', ['invoice_id' => $invoiceId]);
});

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

When Hooks fit

Hooks is a good fit when you want a named extension point without making the original class know about every integration:

• use an action when callbacks should perform side effects and their return values do not matter;
• use a filter when each callback should turn the current value into the next value;
• use a collector when you want one result from each callback.

Everything happens during the call. Hooks does not queue work or hand it to a worker. Callbacks run by priority and registration order, exceptions reach the caller, and changes made during a callback take effect on a later invocation rather than changing the current listener list.

When another abstraction fits better

Hooks is deliberately smaller in scope than Laravel’s event and pipeline systems.

• Choose Laravel Events for domain events, queued listeners, broadcasting, and other Laravel event workflows.
• Choose Laravel Pipeline for a known middleware-like transformation chain where each pipe passes control to the next pipe.
• Choose Hooks for named synchronous extension points, ordered filters, and independent result collection.

Hooks is not a replacement for Laravel Events or Pipeline. Use the abstraction that matches the job: the core package gives any PHP application named extension points, while the Laravel wrapper adds convenient Laravel access where you need it.

Beta status

The 2.x packages are beta releases. Pin and test the versions your application supports, and read the upgrade guide before moving from version 1. These pages describe the beta API, not a stable release contract.

Continue with installation or compare the three hook types.