Events are an extension interface

Events represent a stable interface that other components and extensions rely on, so they should be modeled carefully to avoid breaking changes in the future. The stable interface policy applies to domain event classes.

Events must be modeled as immutable value objects and must not expose any stateful objects through getters. The information exposed by events should be modeled based on the needs of consumers, eposing implementation details should be avoided. Events should be designed to allow reliable serialization and broadcasting on an event bus.

Modeling from the perspective of the listener

Modeling should be based on the perspective of listeners, of what they should and shouldn’t know about the system, and what they may be interested in.

Consequences:

• Focus on changes to entities and their properties, rather than user intent.

• Provide sufficient context within the event object model to enable listeners to appropriately differentiate and filter events.

Note that User actions often trigger multiple events, to cover different changes to all affected entities. For example, a single "move page" action may involve renaming sub-pages and talk pages as well, and for each page that is renamed, it may require deleting the target page, and creating a redirect page under the old name. Modeling all these changes as a single event is not very useful to listeners. It is better to emit events that represent specific changes to specific pages (deletion, creation, renaming, content changes, etc).

Events are emitted by entities

Events should represent the effect of a user action on the state of entities (compare Event_(computing)).

Conceptually, an entity is a stateful object, an object that has a continuous identity while its state changes. Typically, the state of entities is persisted in a database, and changes to the entity are performed atomically, to guarantee consistency among all parts of the state. Entities can form complex nested structures (“aggregates”) with rules that govern the integrity and consistency of that structure. An entity’s (or aggregate’s) state is changed by executing well defined “commands” or "actions" on it. It is the command’s responsibility to guarantee atomicity, and to emit any relevant events. Each concrete type of event should be emitted from only one place in the code.

To properly represent this fact, event classes should be named in a way that makes it obvious what kind of change on what entity they represent. Also, objects should provide a way to determine the identity of the entity that was changed (e.g. PageDeletedEvent would have a getPageId() method to determine which page was deleted).

Events emitted by the same entity or otherwise sharing properties may be grouped together using abstract base types. See the section about the type hierarchy below.

Events types form a hierarchy

Events are organized in a type hierarchy. When an event is dispatched, it is dispatched to listeners registered for the event's own type as well as for any of its parent types (the event type chain). In the hierarchy, events emitted by a given kind of entity are typically subtypes of a shared abstract base type. This provides flexibility with respect to the granularity of modeling - we can always introduce a subtype or a parent type to adjust granularity, without breaking compatibility.

Based on their role in the type hierarchy, event types can be classified as follows:

• Concrete event types are emitted explicitly by code that changes the state of an entity (a "command" or "action"). Concrete event types are modeled by PHP objects that are instantiated directly be the code that emits the event. They represent the effect the command has on the state of the entity, and should be named in a way that makes it obvious what change happened on what entity.
• Abstract event types serve as a base type for all events emitted for changes on a given kind of entity. Abstract events types are modeled by abstract base classes. They are emitted implicitly by the EventDispatcher when an event of one of their sub-types is emitted. Abstract event types should be named after the entity they cover.

Note that this classification is useful to guide modeling, but it is generally not relevant to listeners. They should not need to know whether they are subscribed to a concrete or an abstract event type.

The relationship between concrete and abstract event types is implemented in code using subclassing as well as defining a "chain" of event types for each event object, rather than a single type. Each subclass adds to the chain by calling the declareEventType() method in its constructor, so the chain of types corresponds to the list parent classes:

class PageDeletedEvent extends PageStateEvent {

	public const TYPE = 'PageDeleted';

	public function __construct( ... ) {
		parent::__construct( ... );

		$this->declareEventType( self::TYPE );
	}
	
	...
}

class PageDeletedEvent extends PageStateEvent implements LoggedPageEvent {

	public const TYPE = 'PageDeleted';

	public function __construct( ... ) {
		parent::__construct( ... );

        // Declare the event types represented by this class.
        // Declare self::TYPE last, so it will be the type returned by getEventType().
		$this->declareEventType( LoggedPageEvent::LOGGED_EVENT_TYPE );
		$this->declareEventType( self::TYPE );
	}
	
	...
}

Events model changes to properties of entities

Commands (aka actions) modify the properties of entities. Events model the outcome of commands as changes of certain properties.

To properly represent the effect of commands on the properties of entities, event objects should provide the following:

• Documentation of which property changes the event represents, and what guarantees it provides to listeners (see the section on continuity below).
• Documentation on what user actions typically trigger them.
• The identity of the entity that was affected
• The state of the entity after the change, including at least the properties that the event covers.
• The state of the entity before the change, including at least the properties that the event covers.

Events are emitted when the change to the entity is complete. Each concrete type of event should only be emitted from one place in the code. This is especially important to remember when considering events emitted by from nested entity structures: the change to the "outer" entity will finish last, because all the changes to "inner" entities have to be completed first. So the event representing the change that was initiated on the root entity will be delivered to listeners last, after all the events emitted from nested entities.

Events can represent reconcilliation requests

Event listeners are often used to maintain derived data, and keep it up to date with state changes elsewhere in the system. For example, when page content changes, the search index must be updates.

Somtimes such updates fail due to bugs or system outages, causing inconsistencies in the derived data. In that case, it is useful to be able to trigger events as reconcilliation requests. This is similar to replaying events in an event sourcing system, except that reconcilliation events are not required to fully represent the state before the original event - they are based on the current state of the system. For example, a reconcilliation request for a change in page content would have the current revision ID as the before state as well as the after state.

Listeners should default to treating reconcilliation events like regular events - the idea is that they should behave as if the actual change had occurred. This requires listeners to be implemented in an idempotent manner, so processing the same event modultiple times doesn't have any unwanted effects. Listeners that are not idempodent, e.g. a listener incrementing the user edit counter, need to check whether an incoming event is a reconcilliation request, and skip processing as needed.