Introducing a new way to review your PRs.

Read the announcement

appwrite / appwrite

The open-source cloud for agents & devs. Including Auth, Databases, Storage, Functions, Messaging, Hosting, Realtime, WAF and more

View on GitHub

59 documents · Updated Nov 20, 2026

docs / reusable-event-bus

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 concernBus roleConsumer-owned decision
Event meaningCarries a typed eventDefines the event data and when to publish it
Reaction selectionMatches exact event typesRegisters listeners for the events they handle
Runtime accessResolves named dependenciesSupplies services for the active runtime
Work lifetimeRuns listeners synchronouslyChooses 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 tests for unit coverage and tests/E2E for end-to-end coverage.

Important failure modes

TriggerConsequenceGuard
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

FileWhy to read it
packages/…/Bus.phpDefines subscription, dependency resolution, dispatch order, and listener failure behavior.
packages/…/Event.phpDefines the minimal contract for typed events.
packages/…/Listener.phpDefines listener names, event subscriptions, dependencies, and callbacks.
packages/…/BusTest.phpShows the core consumer flow and verifies matching, per-listener dependencies, and resolver setup.
packages/…/phpunit.xmlDefines the package's unit and end-to-end test boundaries.