Plugin events
EventRegistry for plugins — visibility flags, registrar event()/webhookEvent(), finding hookable names, and core event families.
What it is
App\Services\Events\EventRegistry is the canonical domain-event catalogue. Plugin Event and Filter hooks must use names that exist in this registry (enforced when $registrar->hook() runs for those types).
Contract page: Event Registry.
Seed source: config/events.php (hundreds of named events). Enumerate the supported plugin audience:
php artisan signals:events --plugin
See the event catalogue for generated names and the distinction between listen() and raw hooks.
Visibility flags
Each EventDefinition carries consumer flags:
| Flag | Meaning |
|---|---|
api |
Visible to API / activity consumers that opt into API visibility |
webhook |
Eligible for outbound webhook subscriptions |
workflow |
Eligible for workflow triggers |
plugin |
Eligible for plugin discovery / plugin consumers |
system_protected |
Excluded from names() / describe() listings; still present for has() / get() |
Consumers query via visibleTo('api'|'webhook'|'workflow'|'plugin').
Declaring plugin-owned events (events[])
Plugin-provided catalogue names must appear in signals.yaml events[] (wiring ⊆ declaration). Names are vendor-prefixed like permissions (e.g. package acme/example → acme.sync.completed). Rules: events.malformed, events.namespace.
# signals.yaml
events:
- name: acme.sync.completed
label: Sync Completed
webhook: true # required for webhookEvent() / event(..., webhook: true)
workflow: true # required for event(..., workflow: true)
hooks:
# Other plugins (or this one) that want to *handle* the event declare it here.
- name: acme.sync.completed
type: event
priority: 50
Registering plugin-owned events
From PluginRegistrar (signatures copied from source):
public function webhookEvent(
string $name,
?string $description = null,
?array $subject = null,
?array $redaction = null,
?array $samplePayload = null,
?string $provider = null,
?int $contract_version = null,
bool $workflow = false,
): self
public function event(
string $name,
array $visibility = [],
?string $description = null,
?array $subject = null,
?array $redaction = null,
?array $samplePayload = null,
?string $provider = null,
?int $contract_version = null,
): self
// accepted visibility keys: api?, webhook?, workflow?, plugin?, payload_schema?
webhookEvent($name)registers withEventSource::Plugin,webhook: true, and adds the name toWebhookEventRegistryso it is subscribable in the webhooks UI/API.event($name, $visibility)registers a catalogue entry with the supplied flags;webhook: truealso registers intoWebhookEventRegistry.
Outbound delivery is automatic. A declared event with webhook: true is delivered to subscribers by either dispatch route:
$context->emit($name, $payload)— the SDK path, which also runs plugin Event hooks.Event::dispatch($name, [$payload])— a plain Laravel event, bridged byApp\Listeners\DispatchPluginWebhookEvent, which subscribes to every plugin-source catalogue entry with webhook visibility at boot.
Neither route needs plugin-specific wiring, and neither re-fires while the Verbs event repository is replaying. Pass a single associative array as the payload; other shapes are wrapped under a payload key.
Manifest gate: both methods require name ∈ events[]. When registering webhook or workflow visibility, the manifest entry must also have the matching webhook: true or workflow: true declaration. (hooks[] still gates hook() / container listeners — it is the handler subscription list, not the provided-event list.)
Typical order:
$registrar->event('acme.sync.completed', [
'plugin' => true,
'webhook' => true,
]);
// A different plugin (or the same one) may then:
$registrar->hook('acme.sync.completed', HookType::Event, $handler, 50);
Workflow-visible discovery
Declare a workflow-visible plugin event in events[] and register it with the
matching visibility flag:
events:
- name: acme.sync.completed
label: Sync Completed
workflow: true
$registrar->event('acme.sync.completed', ['workflow' => true]);
WorkflowTriggerRegistry::availableTriggerEvents() and
ApprovalChainRegistry::availableTriggerEvents() delegate to
EventRegistry::names('workflow') on every call. They therefore include a
plugin event registered after either registry was constructed, while excluding
system-protected and non-workflow-visible events. Discovery only supplies names;
it does not dispatch events, execute workflows, or evaluate approval chains.
Namespace and collision rules
Plugin event names must be dotted and prefixed by the Composer vendor segment:
acme/example may declare acme.sync.completed, but not sync.completed.
Every provided event must first be declared in the plugin's events[] manifest
section, and a visibility flag requested at runtime must be enabled on that
declaration.
EventRegistry is authoritative for identity. A plugin cannot shadow a core
event, including a system-protected one, or replace an event already registered
by another plugin; registration fails with a PluginRegistrarException. These
rules apply to workflow visibility as well as webhook and plugin visibility.
Firing plugin events — PluginContext::emit()
In a PluginBase lifecycle method, obtain the context from the plugin instance:
public function boot(): void
{
$this->context()->emit('acme.sync.completed', ['job_id' => 42]);
}
In a hook handler, use the injected first argument:
$registrar->listen('rental.created', function (PluginContext $context, PluginEventPayload $event): void {
$context->emit('acme.sync.completed', ['job_id' => 42]);
});
The context runs plugin Event hooks through the same framework dispatch path as the event bridges, then sends webhooks when the catalogue entry has webhook: true.
Guards: plugin enabled; name declared in that package's events[]; name registered in EventRegistry.
Subscribing to CORE events — listen()
$registrar->listen($eventName, $listener, $priority = 50) subscribes to any
catalogued domain event by its published name — never a class path — so
plugins speak the same stable vocabulary webhook subscribers do:
$registrar->listen('rental.created', function (PluginContext $context, PluginEventPayload $event): void {
$context->log('New rental '.$event->get('id').' by '.$event->actorType());
});
// A container-resolved invokable class is also accepted:
$registrar->listen('invoice.issued', AcmeInvoiceListener::class);
The listener receives the usual PluginContext first, then an immutable
App\Sdk\Hooks\PluginEventPayload carrying the published payload plus the
actor_type / ref stamps ($event->event, ->get($key), ->actorType(),
->ref()).
Rails, all enforced by App\Sdk\Hooks\PluginEventDispatcher rather than by
convention:
| Rail | Behaviour |
|---|---|
| Catalogue gate | Only names with plugin: true and NOT system_protected may be subscribed |
| Fail loud | An unknown or withheld name throws PluginRegistrarException at plugin boot, not silently at runtime |
| Replay guard | Listeners never fire while Verbs::isReplaying() — same contract as outbound webhooks |
| Failure isolation | A throwing listener is logged, counted against its package, and auto-disables the plugin at plugins.hook_failure_threshold; it can never break the business action |
Manifest gate: the event name must appear in hooks[] (it is a handler
subscription, not a provided event). Subscriptions live in the shared
PluginHookRegistry under the namespaced hook name event:<name>, so they can
never be fired by — or collide with — a hand-placed hook() of the same name.
Fan-out happens in WebhookService::dispatch(), the one boundary every
catalogue-named emitter already funnels through: plugin and webhook subscribers
see the same event, exactly once per domain action, with no per-event wiring.
Finding hookable names
- Prefer names already in
config/events.phpthat match the domain moment you care about (e.g.account.updated,invoice.issued). - Confirm with
EventRegistry::has($name). - For integrations, rely on the AuditableEvent bridge (see Plugin hooks) — CRM/invoice actions fire
AuditableEventwith$actionequal to the catalogue name. - Register new names only when you own the domain moment and will dispatch them (or expose them for webhooks).
OpenAPI / REST activity is separate from this catalogue; webhook delivery uses Webhook Event Registry.
Core event catalogue
Use the generated event catalogue for current names, families and audience flags. php artisan signals:events --plugin includes plugin-visible events registered by installed packages at runtime; the generated reference lists core events. The catalogue includes plugin.data_read alongside lifecycle and denial events. Other audit action names are not automatically subscribable catalogue events.
Self-subscription
A plugin may hook its own provided event — declare the name in both events[] (provider side) and hooks[] (consumer side), call event() before the hook() that subscribes to it (Event hook names must already exist in EventRegistry), and never re-emit from the handler (that would loop). The separately installed signals/slots-demo example demonstrates this pattern — see Plugin examples.
Related
- Plugin hooks — handler contracts and bridges
- Registries and resolvers — full registrar surface
- Plugin examples — separately installed provided-event + self-subscription walkthrough
Payload versions
SDK 2.1 adds listen(string $eventName, callable|string $listener, int $priority = 50, int $payloadVersion = 1). Choose version 2 explicitly:
$registrar->listen('payment.recorded', function (PluginContext $context, PluginEventPayload $event): void {
$context->log('Payment event received', ['event_id' => $event->eventId(), 'payment_id' => $event->document()?->id]);
}, payloadVersion: 2);
Version 1 remains the original published payload, including its existing raw fields. Version 2 is a separate envelope with schema_version, event, event_id, occurred_at, actor_type, ref, subject, document, related, and data. Subject and document references identify the entity, id and optional revision. A payment event's subject is its invoice and its document is the payment; a credit event identifies the credit note. Purchase-order events identify the purchase order.
data is the document projection allowed by this plugin's manifest and the current actor's entity permission, field groups, privacy and warehouse scope. Denied or unavailable data is empty with data_omitted_reason; this implicit omission does not record a plugin access denial. Explicit read() refusals still do.
A Verbs source yields event_id = verbs:{source id}. Other dispatches generate one UUID shared by all version 2 listeners. Use it for deduplication. subject.revision carries the available source aggregate revision. Dispatch remains after commit, replay-safe, and failure-isolated. Only versions 1 and 2 are accepted. See the event catalogue for deterministic v2 examples.
V2 data uses the current acting user's permissions and warehouse scope as well as the receiving package's declared fields. When an integration identity triggers another package's listener, that listener runs without an acting principal (system); the originating identity is restored afterwards. The envelope still identifies the triggering actor as integration. Same-package listeners retain their identity scope.
SDK 2.2 payment v2 envelopes include related.original_payment when the audit source carries an original payment ID. Declared payment read fields can include original_payment_id, correction_kind, posting_date, and value_date. Reversals publish the existing payment.refunded event and expose correction_kind: reversal; v1 payloads retain their original shape. Purchase-order billing-marker changes publish purchase_order.updated with the marker available through declared v2 data.