SIGNALS Docs
Exit Reader View
100%
Theme

Reader View

Event Registry

Contract for the canonical domain-event catalogue, consumer visibility flags, and system-protected exclusions.

Overview

App\Services\Events\EventRegistry is the canonical domain-event catalogue. Core seeds it from config/events.php at construction; plugins and framework code extend it with register() / registerMany().

Consumer accessors (names() / describe()) filter by visibility flag and always exclude system-protected events. get() / has() remain available for recording regardless of exposure flags.

The public surface is a stable contract for workflow triggers and the plugin SDK. Consumers depend on its method names and signatures.

Public surface

Method Purpose
register() Register one EventDefinition by event name
registerMany() Validate and register a batch atomically
names() Return visible event names for an optional consumer
describe() Return visible EventDefinition objects keyed by name
workflowCatalogueDefinitions() Return every non-protected event visible to workflow authoring
workflowTriggerDefinitions() Return definitions supported by the current workflow capability runtime
workflowTriggerDiagnostics() Explain missing metadata or capabilities across every workflow-visible family
get() Return one definition or throw for an unknown name
has() Check whether an event name is registered

Accepted definition shape

Each entry is an immutable App\Services\Events\EventDefinition:

new EventDefinition(
    name: 'account.updated',
    source: EventSource::Core, // or EventSource::Plugin
    payloadSchema: null,       // optional array shape metadata
    api: false,
    webhook: true,
    workflow: true,
    plugin: true,
    systemProtected: false,
)

Visibility flags gate consumer exposure:

Flag Consumer key passed to names() / describe()
api 'api'
webhook 'webhook'
workflow 'workflow'
plugin 'plugin'

systemProtected excludes the event from every discovery accessor. It never gates recording via get() / has().

EventDefinition::visibleTo($consumer) returns the matching flag, always false when system-protected, and throws InvalidArgumentException for an unknown consumer string. The definition also derives entity from the substring before the first . in name.

Identity, collisions, and lookup behavior

Event identity is the definition's name string.

  • register() throws InvalidArgumentException with Event [{name}] is already registered. on collision
  • registerMany() validates the entire batch before storing anything; a collision leaves definitions and memoised discovery unchanged
  • Construction from config skips non-string keys and non-array definition values rather than throwing

Lookup behavior:

  • get($name) throws InvalidArgumentException with Unknown event [{name}]. when missing
  • has($name) is the optional guard
  • names(null) / describe(null) return every non-system-protected event
  • names('plugin') / describe('plugin') further require the matching visibility flag

Runtime consumption

Current framework consumers use the catalogue for discovery and recording:

  1. Consumer pickers and catalogues call names($consumer) / describe($consumer) so system-protected events stay hidden
  2. Recording paths call get() / has() without regard to visibility flags
  3. Plugin / workflow seams treat the registry as the authoritative event name catalogue

Config seeding maps system_protected and the four visibility booleans from each config/events.php entry. payload_schema is kept only when it is an array; other types become null.

The webhook consumer slice is authoritative: WebhookEventRegistry is seeded from names('webhook'), so declaring webhook: true here is what makes an event subscribable.

Workflow and approval-chain consumers use the same canonical catalogue through WorkflowTriggerRegistry::availableCatalogueEvents() and ApprovalChainRegistry::availableCatalogueEvents(). Their executable trigger methods use the stricter workflowTriggerDefinitions() slice, so late plugin registrations are discoverable while events without the required runtime authority or metadata remain unavailable for execution.

Payload shape and schema

Every entry also declares payload_shape (App\Enums\PayloadShape), describing the internal event payload that producers publish:

Shape Payload Schema
full_dto a complete response DTO nested under payload_key resolved from PayloadSchemas for the entry's payload_dto
lean_envelope id + action pointer envelope (the default) the shared lean-envelope schema
ad_hoc a bespoke array assembled at the dispatch site none

Schemas are not inlined in config: entries name a DTO, and the registry resolves the generated schema from App\Services\Events\PayloadSchemas at construction time, so cached config stays small. An entry may still supply an explicit payload_schema array, which always wins (plugins use this path).

HTTP webhook delivery projects this internal payload into data with delivery attributes in root meta. A registered single-resource result is promoted directly to data; compound results retain their resource keys under data, including the parent/child flightcases in flightcase.nested. See webhook payload schemas for the delivery examples.

An architecture ratchet enforces that every entry declares a valid payload_shape, that every full_dto event resolves a schema, and that the frozen set of schema-less events only ever shrinks.

Worked example

This is the current registration and consumer-filter shape:

$registry->register(new EventDefinition(
    name: 'acme.account.updated',
    source: EventSource::Plugin,
    webhook: true,
    workflow: true,
    plugin: true,
));

$registry->names('plugin');   // includes acme.account.updated when plugin=true and not system-protected
$registry->describe(null);    // every non-system-protected definition
$registry->get('acme.account.updated')->visibleTo('webhook'); // true

With a system-protected definition registered under the same catalogue, names() and describe() omit it while has() / get() still succeed.

Workflow capability contract

Three separate questions govern workflow use:

  • workflowCatalogueDefinitions() permits discovery and draft references. Catalogue-only events stay visible but disabled in executable pickers.
  • workflowTriggerDefinitions() delegates execution eligibility to the scoped WorkflowEventRuntime. Complete metadata and an available, supported capability provider are both required, including for condition-less publication.
  • WorkflowEventRuntime::canEmit() additionally requires EventDefinition::isWorkflowEmittable(). Only complete workflow.custom.* signals can be emitted by Fire Event. Domain facts remain non-emittable even when their provider can start workflows.

workflow_capability states which of those three answers an entry is entitled to, as catalogue, trigger, emit, or none. It maps to EventDefinition::$workflowCapability, and effectiveWorkflowCapability() reads it with catalogue as the default. Every workflow-flagged core entry declares one, and a CI contract check holds the declaration and the runtime to each other in both directions.

The declaration is a veto, never a grant. A catalogue or none entry is refused with workflow_capability_not_executable even when a registered provider would accept it, and an emit declaration on anything but a complete workflow.custom.* event still fails isWorkflowEmittable(). An absent key stays null and defers to the provider, so a plugin event registered without it keeps its existing behaviour; a value outside the closed set resolves to none and fails closed. Every system_protected event is none: it is absent from every discovery accessor, so it can never be authored against or triggered.

Core configuration maps workflow_provider to EventDefinition::$workflowProvider and workflow_contract_version to $workflowContractVersion. Providers implement WorkflowEventCapabilityProvider: stable key/version, event support, trigger/emission eligibility, subject resolution, service-principal authorization, sensitive fields, and an AuditableEvent payload adapter. No generic authorization or payload fallback enables an unsupported family.

A definition also needs workflow_description, workflow_subject (type and id_path), workflow_redaction.sensitive_fields (a list of nonempty paths), and a payload schema or workflow_sample_payload. workflow_payload_schema optionally describes the adapted workflow payload independently of the webhook/API schema. workflowSchema() returns that override when present. A malformed override fails closed.

Publication records provider, contract_version, and payload_version in the immutable trigger configuration. Capture records the corresponding runtime_pin on the durable envelope. Admission verifies both pins against the active provider; a missing provider, missing pin, or incompatible version records a reason code with the payload fully redacted. Retained providers are available only to already admitted nonterminal runs through WorkflowExtensionRetention.

Provider mutations do not leave stale trigger discovery: the catalogue is memoised only until event registration changes, and the executable view checks the current scoped runtime on every call. Protected events remain absent from all these discovery views; get() and has() deliberately still resolve them for recording.

Account providers retain the adapted DTO in the captured payload and apply declared sensitive paths to redacted_summary. Anonymisation is identifiers-only. Account name and business reference number remain available through explicitly declared nested condition paths.

Base currency identity recording

The protected audit action base_currency_identity.backfilled records a first identity stamp and its source, evidence, reason and system actor. It is excluded from API, webhook, workflow and plugin discovery. Historical source events are never edited.

Verbs event State Projection target
InvoiceBaseCurrencyIdentityRecorded InvoiceState Invoice or credit note
PurchaseOrderBaseCurrencyIdentityRecorded PurchaseOrderState Purchase order
RentalBaseCurrencyIdentityRecorded RentalState Rental, including state identity
RentalCostBaseCurrencyIdentityRecorded RentalCostState Rental cost, including state identity

Each carries the target table and ID, base currency code, source, evidence, reason and nullable actor ID. Live validation requires NULL identity and matching state ownership; replay performs only a NULL-guarded stamp and preserves the projection timestamp. Stable snake-case aliases are registered in VerbsTypeMap.

Internal account operation facts

AccountOperationOccurred uses the durable account effect repository and is distinct from this external catalogue. Credit decision/reservation and history rebuild facts do not create webhook or plugin names. Relationship and privacy catalogue entries retain their protected flags; account override publication remains webhook-only. Do not infer consumer visibility from an internal operation type. The internal schema version and deterministic operation event ID are separate from a webhook producer's identifier or the account-only UUID delivery fallback.