SIGNALS Docs
Exit Reader View
100%
Theme

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 with EventSource::Plugin, webhook: true, and adds the name to WebhookEventRegistry so it is subscribable in the webhooks UI/API.
  • event($name, $visibility) registers a catalogue entry with the supplied flags; webhook: true also registers into WebhookEventRegistry.

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 by App\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

  1. Prefer names already in config/events.php that match the domain moment you care about (e.g. account.updated, invoice.issued).
  2. Confirm with EventRegistry::has($name).
  3. For integrations, rely on the AuditableEvent bridge (see Plugin hooks) — CRM/invoice actions fire AuditableEvent with $action equal to the catalogue name.
  4. 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.

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.