Nexus API Reference

Behavior
in package

Read onlyYes
AbstractYes

Immutable behavior definition — the heart of every actor.

A Behavior describes what an actor does when it receives a message. You never instantiate Behavior subclasses directly; instead use the static factory methods (receive, withState, setup, withTimers, withStash) which return the appropriate concrete subtype. Each message handler returns a Behavior to indicate what the actor should do next — keep the same behavior (same()), stop (stopped()), or switch to a new behavior.

Example — stateless closure actor:

$behavior = Behavior::receive(static function (ActorContext $ctx, object $msg): Behavior {
    if ($msg instanceof Greet) {
        $ctx->log()->info('Hello, ' . $msg->name);
    }
    return Behavior::same();
});
$ref = $system->spawn(Props::fromBehavior($behavior), 'greeter');

Example — stateful closure actor:

$behavior = Behavior::withState(0, static function (ActorContext $ctx, object $msg, int $count): BehaviorWithState {
    return match (true) {
        $msg instanceof Increment => BehaviorWithState::next($count + 1),
        $msg instanceof GetCount  => BehaviorWithState::same(),
        default                   => BehaviorWithState::same(),
    };
});
Tags
see
Props

for wiring a Behavior into a spawnable actor

see
BehaviorWithState

for the stateful handler return type

see
ActorContext

for the context available inside handlers

psalm-api
template

T of object

Table of Contents

Methods

empty()  : EmptyBehavior<string|int, T>
onSignal()  : static
Returns a new behavior of the same type with the given signal handler attached.
receive()  : ReceiveBehavior<string|int, U>
Create a stateless behavior from a message-handler closure.
same()  : SameBehavior<string|int, T>
Signal that the actor should keep its current behavior unchanged.
setup()  : SetupBehavior<string|int, U>
Create a lazily-initialized behavior from a setup factory closure.
signalHandler()  : callable(ActorContext<string|int, T>, Signal): Behavior<string|int, T>|null
Returns the signal handler attached via onSignal(), or null if none.
stopped()  : StoppedBehavior<string|int, T>
Signal that the actor should stop after processing the current message.
supervise()  : SupervisedBehavior<string|int, U>
Wrap an existing behavior with a custom supervision strategy.
unhandled()  : UnhandledBehavior<string|int, T>
Signal that the current message was not handled by this behavior.
unstashAllReplay()  : UnstashAllBehavior<string|int, U>
withStash()  : WithStashBehavior<string|int, U>
Create a behavior with a bounded stash buffer for deferring messages.
withState()  : WithStateBehavior<U, S>
Create a stateful behavior that carries typed state alongside the message handler.
withTimers()  : WithTimersBehavior<string|int, U>
Create a behavior with access to a TimerScheduler for delayed and periodic messages.

Methods

onSignal()

Returns a new behavior of the same type with the given signal handler attached.

public abstract onSignal(callable(ActorContext<string|int, T>, Signal): Behavior<string|int, T> $handler) : static
Parameters
$handler : callable(ActorContext<string|int, T>, Signal): Behavior<string|int, T>
Return values
static

receive()

Create a stateless behavior from a message-handler closure.

public static receive(callable(ActorContext<string|int, U>, U): Behavior<string|int, U> $handler) : ReceiveBehavior<string|int, U>

The closure receives the current ActorContext and the message, and must return a Behavior indicating what the actor should do next. Return Behavior::same() to keep the current behavior unchanged.

Parameters
$handler : callable(ActorContext<string|int, U>, U): Behavior<string|int, U>
Tags
template

U of object

Return values
ReceiveBehavior<string|int, U>

same()

Signal that the actor should keep its current behavior unchanged.

public static same() : SameBehavior<string|int, T>

The most common return value from a message handler — return this when you have processed the message but do not need to change the behavior.

Return values
SameBehavior<string|int, T>

setup()

Create a lazily-initialized behavior from a setup factory closure.

public static setup(callable(ActorContext<string|int, U>): Behavior<string|int, U> $factory) : SetupBehavior<string|int, U>

The factory runs once when the actor starts (before any user messages), receiving the ActorContext so it can spawn children, subscribe to events, or acquire resources before returning the actual message-handling Behavior.

Parameters
$factory : callable(ActorContext<string|int, U>): Behavior<string|int, U>

Called once at actor startup.

Tags
template

U of object

Return values
SetupBehavior<string|int, U>

stopped()

Signal that the actor should stop after processing the current message.

public static stopped() : StoppedBehavior<string|int, T>

The actor delivers PostStop, stops its children, and closes its mailbox. Any messages still in the mailbox are forwarded to dead letters.

Return values
StoppedBehavior<string|int, T>

supervise()

Wrap an existing behavior with a custom supervision strategy.

public static supervise(Behavior<string|int, U> $inner, SupervisionStrategy $strategy) : SupervisedBehavior<string|int, U>

The supervision strategy overrides the default one-for-one restart policy for this actor's children. Normally you configure supervision via Props; use this factory when you need different strategies per behavior variant.

Parameters
$inner : Behavior<string|int, U>

The behavior to wrap.

$strategy : SupervisionStrategy
Tags
template

U of object

Return values
SupervisedBehavior<string|int, U>

unhandled()

Signal that the current message was not handled by this behavior.

public static unhandled() : UnhandledBehavior<string|int, T>

Unhandled messages are forwarded to the dead-letter channel so they can be monitored without causing the actor to crash.

Return values
UnhandledBehavior<string|int, T>

unstashAllReplay()

public static unstashAllReplay(array<int, Envelope> $envelopes, Behavior<string|int, U> $target) : UnstashAllBehavior<string|int, U>
Parameters
$envelopes : array<int, Envelope>
$target : Behavior<string|int, U>
Tags
template

U of object

Return values
UnstashAllBehavior<string|int, U>

withStash()

Create a behavior with a bounded stash buffer for deferring messages.

public static withStash(int $capacity, callable(StashBuffer): Behavior<string|int, U> $factory) : WithStashBehavior<string|int, U>

The factory receives a StashBuffer that allows the actor to stash incoming messages and unstash them later (e.g. after completing initialization or a persistence recovery phase). Messages beyond capacity are dropped.

Parameters
$capacity : int

Maximum number of messages that can be stashed.

$factory : callable(StashBuffer): Behavior<string|int, U>
Tags
template

U of object

psalm-suppress

UndefinedDocblockClass StashBuffer will be created in a future task

psalm-suppress

UnusedParam $capacity and $factory are stored for resolution by ActorCell

Return values
WithStashBehavior<string|int, U>

withState()

Create a stateful behavior that carries typed state alongside the message handler.

public static withState(S $initialState, callable(ActorContext<string|int, U>, U, S): BehaviorWithState<U, S> $handler) : WithStateBehavior<U, S>

The handler receives the context, the message, and the current state, and must return a BehaviorWithState indicating the next state. The state is private to the actor and never shared outside it.

Parameters
$initialState : S

The initial value of the actor's state.

$handler : callable(ActorContext<string|int, U>, U, S): BehaviorWithState<U, S>
Tags
template

U of object

template

S

Return values
WithStateBehavior<U, S>

withTimers()

Create a behavior with access to a TimerScheduler for delayed and periodic messages.

public static withTimers(callable(TimerScheduler): Behavior<string|int, U> $factory) : WithTimersBehavior<string|int, U>

The factory receives a TimerScheduler that allows the actor to schedule messages to itself without needing access to the ActorContext directly. Timers are automatically cancelled when the actor stops.

Parameters
$factory : callable(TimerScheduler): Behavior<string|int, U>
Tags
template

U of object

psalm-suppress

UndefinedDocblockClass TimerScheduler will be created in a future task

psalm-suppress

UnusedParam $factory is stored for resolution by ActorCell

Return values
WithTimersBehavior<string|int, U> 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results