Nexus API Reference

NexusApp
in package

FinalYes

Fluent bootstrap entry point for Nexus actor applications.

NexusApp is the top-level application kernel. It collects actor definitions and optional lifecycle callbacks, then spawns them all and starts the runtime event loop with a single run() call. For more control — for example, to wire OS signal handling before the loop starts — use start() instead, which returns the configured ActorSystem without blocking.

All actor registration methods return $this, enabling a fluent builder style:

NexusApp::create('shop')
    ->actor('orders', Props::fromBehavior($orderBehavior))
    ->actor('payments', Props::fromFactory(fn() => new PaymentActor()))
    ->onStart(function (StartedApp $app): void {
        // retrieve a typed handle to a root actor spawned above
        $app->ref('orders')->tell(new WarmUp());
    })
    ->run(new FiberRuntime());
Tags
see
ActorSystem

Underlying system created by start() / run()

Props

Actor spawn configuration passed to actor()

Runtime

Concurrency backend (FiberRuntime, SwooleRuntime, StepRuntime)

psalm-api

Table of Contents

Methods

actor()  : self
Register an actor to be spawned on startup.
actors()  : array<int, ActorDefinition<string|int, object>>
Returns all registered actor definitions.
create()  : self
Create a new NexusApp with the given application name.
name()  : string
Returns the application name supplied to {@see create()}.
onStart()  : self
Register a callback invoked after all actors are spawned.
run()  : void
Run in single-process mode with the given runtime.
start()  : StartedApp
Spawn all registered actors, invoke the start callback, and return the live system without starting the runtime event loop.
withObservability()  : self
Attach an observability provider (traces + metrics). The provider is threaded into the actor system and shut down (flushed) when {@see run()} returns. Build it via ObservabilityFactory::fromConfig(...) or pass a NoopObservability to disable. Optional — defaults to no-op.

Methods

actor()

Register an actor to be spawned on startup.

public actor(string $name, Props<string|int, T> $props) : self

Definitions are accumulated in registration order and spawned during start() before the optional start callback fires. Duplicate names are not detected here — the conflict surfaces when ActorSystem::spawn() throws ActorNameExistsException.

Parameters
$name : string

Unique child name under the user guardian (becomes part of the actor path)

$props : Props<string|int, T>

Spawn configuration describing the behavior, mailbox, and supervision

Tags
template
Return values
self —

This builder, for fluent chaining

actors()

Returns all registered actor definitions.

public actors() : array<int, ActorDefinition<string|int, object>>
Return values
array<int, ActorDefinition<string|int, object>> —

Definitions in registration order

create()

Create a new NexusApp with the given application name.

public static create(string $name) : self

The name is passed through to ActorSystem::create() and appears in log output and actor paths.

Parameters
$name : string

Human-readable application name; becomes the root actor system name

Return values
self —

Fresh builder ready for actor registration

name()

Returns the application name supplied to {@see create()}.

public name() : string
Return values
string —

The application name passed to the constructor

onStart()

Register a callback invoked after all actors are spawned.

public onStart(callable(StartedApp): void $callback) : self

The callback fires synchronously at the end of start(), before the runtime event loop is started, with the StartedApp as its sole argument. Use it to retrieve typed handles to the spawned root actors ($app->ref('orders')), send warm-up messages, or wire external listeners. Replacing a previously registered callback is allowed; only the most recent one is invoked. Reach the underlying system via $app->system().

Parameters
$callback : callable(StartedApp): void

Invoked once with the StartedApp after spawn

Return values
self —

This builder, for fluent chaining

run()

Run in single-process mode with the given runtime.

public run(Runtime $runtime[, LoggerInterface|null $logger = null ]) : void

Convenience wrapper that calls start() and then blocks on StartedApp::run() until the system is shut down. Suitable for Hello World and CLI entry points; long-running services that need to react to OS signals should call start() and drive the loop explicitly via the returned StartedApp.

Parameters
$runtime : Runtime

Concurrency backend (Fiber, Swoole, Step)

$logger : LoggerInterface|null = null

Optional PSR-3 logger; defaults to the ActorSystem default when null

start()

Spawn all registered actors, invoke the start callback, and return the live system without starting the runtime event loop.

public start(Runtime $runtime[, LoggerInterface|null $logger = null ]) : StartedApp

Callers use this when they need to wire infrastructure — OS signal handlers, HTTP servers, metric scrapers — around the actor system before blocking on ActorSystem::run(). For the common case where no extra setup is needed, prefer run().

Parameters
$runtime : Runtime

Concurrency backend (Fiber, Swoole, Step)

$logger : LoggerInterface|null = null

Optional PSR-3 logger; defaults to the ActorSystem default when null

Return values
StartedApp —

The started app: the live system plus the named root actor handles, ready for run()

withObservability()

Attach an observability provider (traces + metrics). The provider is threaded into the actor system and shut down (flushed) when {@see run()} returns. Build it via ObservabilityFactory::fromConfig(...) or pass a NoopObservability to disable. Optional — defaults to no-op.

public withObservability(Observability $observability) : self
Parameters
$observability : Observability
Return values
self
On this page

Search results