SIGNALS Docs
Exit Reader View
100%
Theme

Plugin hook payloads

Arguments and return rules for hooks, catalogue listeners and flightcase listeners.

Hook arguments

The dispatcher always prepends PluginContext for hook() handlers. Event returns are ignored; filter returns become the next value in the chain. A throwing filter leaves that step's input unchanged. Validators return a boolean or GuardResult: false or a failed guard denies, and a thrown exception produces a denial with code plugin_validator_exception. Other return values are treated as allowed by HookValidatorVerdict::fromReturn.

Hook Handler arguments after context Return
Event through the audit bridge Model $model, ?array $old, ?array $new Ignored
Filter mixed $value, mixed ...$contextArgs Next value
Validator Call-site arguments Boolean or GuardResult
Decorator object $payload, mixed ...$contextArgs Object replaces payload

The audit bridge in PluginBootstrapper::bridgeAuditableEventsToPluginHooks forwards the action, model, pre-change values and new values only for plugin-visible catalogue names. ImportBatch is passed as publicCopy(). Events with a metadata.plugin key or metadata.audit_only === true are skipped. Other explicit Event call sites can have different shapes.

use App\Sdk\Hooks\HookType;
use App\Sdk\PluginContext;
use Illuminate\Database\Eloquent\Model;

$registrar->hook('account.updated', HookType::Event,
    function (PluginContext $context, Model $model, ?array $old, ?array $new): void {
        $context->log('Account changed', ['id' => $model->getKey()]);
    });

Declare the hook in hooks[] before registering it. Decorator has no core call sites: applyDecorators() exists, but core does not invoke it. Registering a Decorator hook does not make it run today.

Scheduling call sites

SchedulingHookBridge emits these arguments after the context; these are not the audit bridge's $old/$new signature.

Hook Arguments Type
assignment.created ResourceAssignment $assignment Event
assignment.status_changed Assignment, ['old_status' => string, 'new_status' => string] Event
conflict.detected SchedulingConflict $conflict Event
demand.unmet array{rental_line_id: int, shortfall: float} Event
assignment.query Builder<ResourceAssignment> $query Filter; return a builder
assignment.creating Array with rental_id, rental_project_id, rental_line_id, resource_type, resource_id, service_id, starts_at, ends_at, source Validator

The query bridge keeps its input if the filter chain does not return a builder. Scheduling Event hooks are emitted explicitly; their catalogue names differ from the resource_assignment.* and scheduling_conflict.* audit/webhook names.

Catalogue listeners

listen() supplies (PluginContext $context, PluginEventPayload $payload). Its immutable event property is the catalogue name; payload is the published array. get(string $key, mixed $default = null) reads a top-level key, not a dot path. actorType(): ?string and ref(): ?string expose the published actor and subject reference when present.

use App\Sdk\Hooks\PluginEventPayload;
use App\Sdk\PluginContext;

$registrar->listen('rental.created', function (PluginContext $context, PluginEventPayload $payload): void {
    $context->log('Rental received', [
        'event' => $payload->event,
        'actor' => $payload->actorType(),
        'ref' => $payload->ref(),
        'rental' => $payload->get('rental'),
    ]);
});

Use the event catalogue to choose a subscribable name and inspect sample shapes. listen() is not the audit Event hook signature.

Flightcase listeners

The onFlightcase* methods pass a typed event object. Add a first parameter typed PluginContext to opt into context injection; an untyped or event-only callable continues to receive just the event. Event classes live in App\Events\Flightcases.

Registrar methods Before event After event
onFlightcaseBeforePack, onFlightcaseAfterPack BeforeFlightcasePacked FlightcasePacked
onFlightcaseBeforeSeal, onFlightcaseAfterSeal BeforeFlightcaseSealed FlightcaseSealed
onFlightcaseBeforeDissolve, onFlightcaseAfterDissolve BeforeFlightcaseDissolved FlightcaseDissolved
onFlightcaseBeforeDispatch, onFlightcaseAfterDispatch BeforeFlightcaseDispatched FlightcaseDispatchedLifecycle
onFlightcaseBeforeRepack, onFlightcaseAfterRepack BeforeFlightcaseRepack FlightcaseRepackStarted
onFlightcaseBeforeTransfer, onFlightcaseAfterTransfer BeforeFlightcaseItemTransferred FlightcaseItemTransferred

Each event exposes these constructor properties (model types are in App\Models):

Event Public payload properties
BeforeFlightcasePacked Flightcase $flightcase, Asset $asset
FlightcasePacked Flightcase $flightcase, FlightcaseItem $item
BeforeFlightcaseSealed Flightcase $flightcase
FlightcaseSealed Flightcase $flightcase, int $itemCount
BeforeFlightcaseDissolved Flightcase $flightcase
FlightcaseDissolved Flightcase $flightcase, int $itemCount
BeforeFlightcaseDispatched Flightcase $flightcase, Rental $rental
FlightcaseDispatchedLifecycle Flightcase $flightcase, Rental $rental, int $itemCount
BeforeFlightcaseRepack Rental $rental, Asset $housing
FlightcaseRepackStarted Flightcase $flightcase, int $rentalId, ?int $previousFlightcaseId
BeforeFlightcaseItemTransferred Flightcase $sourceFlightcase, Flightcase $targetFlightcase, Asset $asset, FlightcaseItem $flightcaseItem
FlightcaseItemTransferred Flightcase $sourceFlightcase, Flightcase $targetFlightcase, FlightcaseItem $item

Typed version 2 references

For listen(..., payloadVersion: 2), PluginEventPayload also exposes version, subject(), document(), eventId(), revision() and data(). PluginEventRef contains entity, id, nullable revision, and readable (whether the entity exists in the SDK entity map; it is not a permission grant). related is a keyed reference map. data() returns the guarded document array and returns an empty array for v1. The payload version contract explains omission and replay identity.