Reusable event bus
The reusable event bus is a small, synchronous package for sending typed events to local listeners. It lets a producer state that an action occurred without knowing which other actions must follow, so consumers can add local reactions without coupling them to the producer. It is one of the reusable platform packages.
Event model
An event is a typed object that represents one fact or completed action in the current process. The event carries the data needed by its listeners, while the producer stays separate from the code that handles the result.
Typed events
The Event contract marks a class as a bus event. Each event class defines its own data shape, so listeners receive a known type instead of parsing a shared message format.
References: packages/…/Event.php• L5-7
Listener model
A listener is a named unit of local event handling. It declares the event types that it accepts and supplies the action that runs when one of those types is dispatched.
Listener subscriptions
Listeners can subscribe to one or more event classes. The bus matches an event to listeners by its exact type, which lets several listeners react to the same event while unrelated listeners remain untouched.
References: packages/…/Listener.php• L5-17 packages/…/Bus.php• L21-27 packages/…/BusTest.php• L29-41
Listener dependencies
Listeners can request named services at dispatch time. The consumer supplies a resolver for the active runtime, and the bus passes the resolved services to the listener together with the event. This keeps runtime services outside the event object and allows the same package to serve different application contexts.
References: packages/…/Listener.php• L25-49 packages/…/Bus.php• L15-19 packages/…/Bus.php• L35-44 packages/…/BusTest.php• L12-27
Dispatch flow
Dispatch is a local call that runs in the same process as the producer. It is not a queue, network transport, or durable event log. The producer dispatches an event, the bus runs matching listeners, and the call returns after those listeners finish or fail.
This diagram shows how a consumer connects event publication to local handling.
flowchart LR
A[Producer creates typed event] --> B[Bus dispatches event]
B --> C[Find exact type matches]
C --> D[Resolve listener dependencies]
D --> E[Run matching listeners]
E --> F[Local effect or handoff to another system]
Dispatch ordering
The bus runs matching listeners in subscription order. Each listener receives the same event object and its own resolved dependencies, so one event can produce several separate reactions without shared listener state.
References: packages/…/Bus.php• L21-44 packages/…/BusTest.php• L12-27
Dispatch isolation
The bus catches a listener failure and continues with the next matching listener. This prevents one local reaction from stopping the other reactions for the same event. When a span exists, the bus records listener success or failure and the error details for tracing.
References: packages/…/Bus.php• L38-53
Consumer integration
A consumer creates a bus, registers its listeners, and attaches a resolver before it publishes events. The consumer owns the event meanings and listener actions, while the standalone package supplies the shared coordination rules.
Consumer responsibilities
Consumers use the bus for local coordination. A listener can perform a small immediate action or hand work to a queue or another transport when the work must continue beyond the current process.
| Consumer concern | Bus role | Consumer-owned decision |
|---|---|---|
| Event meaning | Carries a typed event | Defines the event data and when to publish it |
| Reaction selection | Matches exact event types | Registers listeners for the events they handle |
| Runtime access | Resolves named dependencies | Supplies services for the active runtime |
| Work lifetime | Runs listeners synchronously | Chooses whether to perform work now or hand it off |
References: packages/…/Bus.php• L15-44 packages/…/Listener.php• L12-49 packages/…/BusTest.php• L12-49
Package boundary
The standalone package provides only the event contract, listener model, and dispatch bus. It does not define product events or choose durable delivery, so each consumer can apply the same primitives to its own local event flow.
The package is loaded as utopia-php/bus. Optional span support records listener activity, while any queue or external transport remains the responsibility of the consumer's listener.
References: packages/…/Event.php• L5-7 packages/…/Listener.php• L5-49 packages/…/Bus.php• L7-55 packages/…/phpunit.xml• L2-17
Change checklist
When these files or sections are changed, remember to consider these:
- Keep each event's data contract aligned with every listener that consumes its type.
- Keep a listener's declared event types aligned with the callback that handles them.
- Keep injection names aligned with the resolver supplied by each runtime that dispatches events.
- Keep listener registration aligned with the events that consumers publish.
- Preserve the synchronous boundary when changing a listener. Move slow or failure-prone work to a suitable queue or transport.
- Keep the unit and end-to-end test suite split aligned with the package's test scope when adding tests. The package configuration includes
testsfor unit coverage andtests/E2Efor end-to-end coverage.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A consumer dispatches before it sets a resolver. | Dispatch stops with a logic error and no listener runs. | Configure the bus for the active runtime before publishing events. |
| A listener does not set a callback. | Dispatch fails when the bus tries to obtain the listener action. | Give every listener one callback before subscription. |
| A listener does not declare an event type that it should handle. | The bus skips it because matching uses the event's exact type. | Update the listener subscription when its event scope changes. |
| A listener requests a service name that the resolver cannot provide. | Dependency resolution fails before that listener handles the event. | Make the named service available in every runtime that publishes the event. |
| A producer treats dispatch as durable or asynchronous delivery. | Work remains tied to the current process and can be lost when it ends. | Use a queue or other transport from the listener when work must cross a process boundary. |
Key files
| File | Why to read it |
|---|---|
| packages/…/Bus.php | Defines subscription, dependency resolution, dispatch order, and listener failure behavior. |
| packages/…/Event.php | Defines the minimal contract for typed events. |
| packages/…/Listener.php | Defines listener names, event subscriptions, dependencies, and callbacks. |
| packages/…/BusTest.php | Shows the core consumer flow and verifies matching, per-listener dependencies, and resolver setup. |
| packages/…/phpunit.xml | Defines the package's unit and end-to-end test boundaries. |