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()throwsInvalidArgumentExceptionwithEvent [{name}] is already registered.on collisionregisterMany()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)throwsInvalidArgumentExceptionwithUnknown event [{name}].when missinghas($name)is the optional guardnames(null)/describe(null)return every non-system-protected eventnames('plugin')/describe('plugin')further require the matching visibility flag
Runtime consumption
Current framework consumers use the catalogue for discovery and recording:
- Consumer pickers and catalogues call
names($consumer)/describe($consumer)so system-protected events stay hidden - Recording paths call
get()/has()without regard to visibility flags - 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 scopedWorkflowEventRuntime. Complete metadata and an available, supported capability provider are both required, including for condition-less publication.WorkflowEventRuntime::canEmit()additionally requiresEventDefinition::isWorkflowEmittable(). Only completeworkflow.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.