Nexus API Reference

EventStore
in

Read/write interface for event-sourced event streams.

An EventStore durably records the ordered sequence of EventEnvelope objects that represent every state change a persistent actor has ever made. On actor startup the PersistenceEngine calls load() to replay events from the last snapshot sequence number forward, reconstructing the actor's current state.

Three adapters ship out of the box:

  • InMemoryEventStore — for unit tests; no persistence across process restarts.
  • DbalEventStore (nexus-persistence-dbal) — DBAL-backed, production-ready.
  • DoctrineEventStore (nexus-persistence-doctrine) — Doctrine ORM-backed.

Example (wiring a DBAL store):

$store = new DbalEventStore($connection, 'nexus_events');

EventSourcedBehavior::create($persistenceId, $emptyState, $commandHandler, $eventHandler)
    ->withEventStore($store)
    ->toBehavior();
Tags
see
EventEnvelope

for the envelope wrapping each persisted event

see
PersistenceId

for the unique actor identity used as the stream key

see
EventSourcedBehavior

for the fluent builder that consumes this interface

psalm-api

Table of Contents

Methods

deleteUpTo()  : void
Delete all events up to and including `$toSequenceNr` for the given actor.
highestSequenceNr()  : int
Return the highest sequence number written for `$id`, or 0 if no events exist.
load()  : iterable<string|int, EventEnvelope>
Load events for `$id` within the given sequence number range (inclusive).
persist()  : void
Append one or more events to the stream identified by `$id`.

Methods

deleteUpTo()

Delete all events up to and including `$toSequenceNr` for the given actor.

public deleteUpTo(PersistenceId $id, int $toSequenceNr) : void

Called by the retention policy after a snapshot is confirmed durable. Implementations should be idempotent — deleting already-deleted events is a no-op.

Parameters
$id : PersistenceId
$toSequenceNr : int

highestSequenceNr()

Return the highest sequence number written for `$id`, or 0 if no events exist.

public highestSequenceNr(PersistenceId $id) : int

Used by the engine to detect writer conflicts and to set the starting point for the next persist() call.

Parameters
$id : PersistenceId
Return values
int

load()

Load events for `$id` within the given sequence number range (inclusive).

public load(PersistenceId $id[, int $fromSequenceNr = 0 ][, int $toSequenceNr = PHP_INT_MAX ]) : iterable<string|int, EventEnvelope>

Defaults to the full stream. The PersistenceEngine passes $fromSequenceNr as one past the last snapshot sequence number to avoid replaying already-applied events.

Parameters
$id : PersistenceId
$fromSequenceNr : int = 0
$toSequenceNr : int = PHP_INT_MAX
Return values
iterable<string|int, EventEnvelope>

persist()

Append one or more events to the stream identified by `$id`.

public persist(PersistenceId $id, EventEnvelope ...$events) : void

Implementations must write all events atomically and assign monotonically increasing sequence numbers. Throws on write failure.

Parameters
$id : PersistenceId
$events : EventEnvelope 

        

        
    




    

    

                                

                

                            
    

        On this page

        
    


                

                            

            

    

        

            
Search results