Effect
in package
Command-handler return type for event-sourced actors.
An Effect encodes what the persistence engine should do in response to a
command: persist one or more events, reply to a caller, stash the message for
later processing, stop the actor, or do nothing. The engine executes the effect
after the command handler returns, guaranteeing that side-effects registered via
thenRun() or thenReply() only execute once the events are durably stored.
Example:
// Persist an event and then reply with the updated state
return Effect::persist(new ItemAdded($item))
->thenReply($ctx->sender(), fn(CartState $state) => new CartUpdated($state->items));
// Do nothing (read-only query)
return Effect::none()->thenReply($replyTo, fn(CartState $s) => new CartSnapshot($s));
// Stop the actor after persisting a terminal event
return Effect::persist(new CartCheckedOut())->thenRun(fn() => Effect::stop());
Tags
Table of Contents
Properties
- $events : array<string|int, mixed>
- $replyMsg : mixed
- $replyTo : ActorRef|null
- $sideEffects : array<string|int, mixed>
- $type : EffectType
Methods
- none() : self
- Acknowledge the command without persisting any events or side-effects.
- persist() : self
- Persist one or more domain events and apply them to the actor state.
- reply() : self
- Send a reply message directly to `$to` as the sole effect of handling a command.
- stash() : self
- Defer the current command by placing it back into the stash buffer.
- stop() : self
- Stop the actor after the current effect (and any side-effects) complete.
- thenReply() : self
- Attach a reply side-effect that runs after the events are persisted.
- thenRun() : self
- Attach an arbitrary side-effect closure that runs after the events are persisted.
- unhandled() : self
- Signal that the command was not handled by the current behavior.
Properties
$events
public
array<string|int, mixed>
$events
= []
$replyMsg
public
mixed
$replyMsg
= null
$replyTo
public
ActorRef|null
$replyTo
= null
$sideEffects
public
array<string|int, mixed>
$sideEffects
= []
$type
public
EffectType
$type
Methods
none()
Acknowledge the command without persisting any events or side-effects.
public
static none() : self
Use this for read-only commands or when a command is intentionally a no-op.
Chain thenReply() to still send a response back to the caller.
Return values
selfpersist()
Persist one or more domain events and apply them to the actor state.
public
static persist(object ...$events) : self
Events are written to the EventStore before any side-effects run.
Chain thenRun() or thenReply() to execute callbacks after they are stored.
Parameters
- $events : object
Return values
selfreply()
Send a reply message directly to `$to` as the sole effect of handling a command.
public
static reply(ActorRef $to, object $message) : self
Use this when no state change is needed; for read commands that need a reply
after persisting events, prefer Effect::persist(...)->thenReply(...) instead.
Parameters
- $to : ActorRef
-
The actor to reply to (typically the command sender).
- $message : object
-
The reply message to send.
Return values
selfstash()
Defer the current command by placing it back into the stash buffer.
public
static stash() : self
The stashed command is replayed automatically once the actor calls
$ctx->unstashAll(). Useful during recovery or state-machine transitions.
Return values
selfstop()
Stop the actor after the current effect (and any side-effects) complete.
public
static stop() : self
Return values
selfthenReply()
Attach a reply side-effect that runs after the events are persisted.
public
thenReply(ActorRef $to, callable(TState): TReply $fn) : self
The closure receives the final projected state and must return the reply object
to send to $to. Multiple thenReply() calls chain additional replies.
Parameters
- $to : ActorRef
- $fn : callable(TState): TReply
-
receives final state, returns reply message
Tags
Return values
selfthenRun()
Attach an arbitrary side-effect closure that runs after the events are persisted.
public
thenRun(callable(TState): void $fn) : self
The closure receives the final projected state for inspection. Multiple thenRun()
calls chain additional side-effects; they execute in registration order.
Parameters
- $fn : callable(TState): void
-
receives final state
Tags
Return values
selfunhandled()
Signal that the command was not handled by the current behavior.
public
static unhandled() : self
The message is routed to dead letters, matching the semantics of
Behavior::unhandled() in the stateless actor model.