Nexus API Reference

DurableStateBehavior
in package

Read onlyYes
FinalYes

Fluent builder for durable-state actor behaviors.

Durable state is the simpler persistence model: the actor's full current state is stored as a single snapshot on every DurableEffect::persist() call, with no event history retained. This trades auditability for lower storage overhead and faster recovery (no event replay — just load the latest snapshot and you're ready).

On actor startup the DurableStateEngine loads the latest persisted state from the DurableStateStore and delivers it as the initial state before any user command arrives.

Example:

$behavior = DurableStateBehavior::create(
    PersistenceId::of('UserProfile', $userId),
    new UserProfile(),
    static fn (ActorContext $ctx, object $cmd, UserProfile $state): DurableEffect => match (true) {
        $cmd instanceof UpdateEmail  => DurableEffect::persist($state->withEmail($cmd->email)),
        $cmd instanceof GetProfile   => DurableEffect::reply($ctx->sender(), $state),
        default => DurableEffect::none(),
    },
)
    ->withStateStore($stateStore)
    ->toBehavior();
Tags
see
DurableEffect

for the command-handler return type

PersistenceId

for actor identity

EventSourcedBehavior

for the event-sourced alternative with full history

template

The state type

psalm-api

Table of Contents

Methods

create()  : self
Create a new DurableStateBehavior builder.
toBehavior()  : Behavior
Build the final Behavior using DurableStateEngine.
withStateStore()  : self
Set the state store used to load and persist full state snapshots.
withWriterId()  : self
Override the writer ID stamped on persisted state envelopes.

Methods

create()

Create a new DurableStateBehavior builder.

public static create(PersistenceId $persistenceId, object $emptyState, Closure $commandHandler) : self
Parameters
$persistenceId : PersistenceId

Unique identity for this persistent entity

$emptyState : object

Initial empty state before any persisted state

$commandHandler : Closure

Processes commands, returns DurableEffect

Tags
psalm-suppress

UnusedParam Parameters are stored via constructor for later use

Return values
self

toBehavior()

Build the final Behavior using DurableStateEngine.

public toBehavior() : Behavior
Tags
throws
LogicException

if DurableStateStore has not been set

psalm-suppress

MixedArgumentTypeCoercion Stored closures lose generic type info

Return values
Behavior

withWriterId()

Override the writer ID stamped on persisted state envelopes.

public withWriterId(Ulid $writerId) : self

Defaults to a freshly generated ULID. Override for deterministic tests or data-migration scenarios.

Parameters
$writerId : Ulid
Return values
self
On this page

Search results