Nexus API Reference

UnhandledBehavior extends Behavior
in package

Read onlyYes
FinalYes

Immutable behavior definition — the heart of every actor.

Tags
psalm-api

Sentinel behavior returned from handlers to indicate the message was not handled. The message is routed to dead letters.

template

T of object

extends

Behavior<T>

Table of Contents

Methods

__construct()  : mixed
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 onSignal(Closure $handler) : static
Parameters
$handler : Closure
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