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.