NexusApp
in package
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 (ActorSystem $system): void {
// send a warm-up message after all actors are spawned
$system->deadLetters();
})
->run(new FiberRuntime());
Tags
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() : ActorSystem
- 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
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(ActorSystem): void $callback) : self
The callback fires synchronously at the end of start(), before the runtime event loop is started, with the configured ActorSystem as its sole argument. Use it to send warm-up messages, wire external listeners, or capture refs for later use. Replacing a previously registered callback is allowed; only the most recent one is invoked.
Parameters
- $callback : callable(ActorSystem): void
-
Invoked once with the live ActorSystem 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 ActorSystem::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.
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 ]) : ActorSystem
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
ActorSystem —The configured system with all actors spawned, 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