Props

Immutable spawn configuration for an actor.

What it does

Props<T> bundles three things: how to create the actor's behavior, the mailbox capacity policy, and the supervision strategy override. You pass a Props value to ActorSystem::spawn() or ActorContext::spawn() to create a new actor. The four static factory methods (fromBehavior, fromFactory, fromStatefulFactory, fromContainer) cover every actor definition style supported by Nexus: closure-based, class-based, stateful class-based, and PSR-11 container-resolved. Mailbox and supervision defaults are sensible out of the box — only override them when your actor has specific capacity or fault-tolerance requirements.

Example

src/ActorBootstrap.php

use Monadial\Nexus\Core\Actor\Props;
use Monadial\Nexus\Core\Actor\Behavior;
use Monadial\Nexus\Core\Supervision\SupervisionStrategy;
use Monadial\Nexus\Runtime\Mailbox\MailboxConfig;
use Monadial\Nexus\Runtime\Mailbox\OverflowStrategy;

// Closure-based (simplest)
$props = Props::fromBehavior(
    Behavior::receive(fn($ctx, $msg) => Behavior::same()),
);

// Class-based — a fresh instance is created per spawn
$props = Props::fromFactory(fn() => new OrderActor($repository));

// Class-based from a PSR-11 DI container
$props = Props::fromContainer($container, PaymentActor::class);

// Override mailbox and supervision
$props = Props::fromFactory(fn() => new WorkerActor())
    ->withMailbox(MailboxConfig::bounded(256, OverflowStrategy::DropNewest))
    ->withSupervision(SupervisionStrategy::oneForOne(maxRetries: 3));

$ref = $system->spawn($props, 'worker');

Key methods

• Props::fromBehavior(Behavior<T> $behavior): Props<T> — wrap a pre-built Behavior value.
• Props::fromFactory(Closure $factory): Props<T> — factory that returns an ActorHandler<T> (or AbstractActor); called once per spawn.
• Props::fromStatefulFactory(Closure $factory): Props<T> — factory that returns a StatefulActorHandler<T, S>; state is managed by the runtime.
• Props::fromContainer(ContainerInterface $c, string $class): Props<T> — resolves the actor class from a PSR-11 container.

A factory (or container entry) that produces anything other than the required handler interface fails at actor start with ActorInitializationException, whose cause is an InvalidPropsFactoryException naming the factory and the actual type. This check is independent of the zend.assertions setting, so misconfigured production deployments fail at spawn with a clear message rather than on the first message delivery.

• ->withMailbox(MailboxConfig $config): self — override the mailbox (default: unbounded).
• ->withSupervision(SupervisionStrategy $strategy): self — override the supervision strategy (default: inherited from parent).

Full API reference

Full method list and class hierarchy

See also

• Props concept — design rationale and examples
• Behavior — the behavior factory methods used inside Props::fromBehavior()
• ActorSystem — spawn(Props, string) is the top-level spawn entry point
• Actors concept — the actor hierarchy and supervision trees