Use Cases
Where actors change the equation.
The actor model is not a universal solution. These are the workloads where its structural properties — isolated state, supervised failures, message-driven concurrency — deliver concrete advantages over queue-based or thread-based alternatives.
Event-driven microservices
Each service owns an actor tree. Services communicate through typed messages, not raw HTTP JSON. Event-sourced aggregates produce a full audit trail with zero extra code — every state change is already a persisted event. Adding a new subscriber is one actor spawn — no schema migration, no queue topology change, no broker configuration. When a subscriber crashes, its supervisor restarts it and it replays missed events from the store.
Persistence + event sourcing docs →Real-time data pipelines
Ingestion actors receive raw events; transformation actors reshape them; sink actors write to Doctrine or a downstream API. The pipeline is a supervision tree: one stage crashes and restarts without dropping the stages upstream or downstream. Backpressure propagates naturally through bounded mailboxes — a slow sink slows the upstream transformation actors rather than allowing unbounded memory growth. Under Swoole, each stage runs as a coroutine; there is no blocking I/O.
Scaling + worker pool docs →Task orchestration
Long-running workflows — multi-step checkouts, document processing pipelines, asynchronous approvals — are Saga actors. Each step is a typed message. Compensations are explicit Behavior branches that Psalm statically analyses alongside the happy path. The saga persists its own state, so a server restart continues from the last committed step with no loss of progress. There is no external workflow engine to deploy or monitor.
Saga pattern guide →IoT and device management
One actor per device. The actor holds live device state — connection status, last telemetry, pending commands — without a database read on every interaction. Direct message dispatch replaces polling loops; the actor responds to commands in microseconds. Passivation writes state to persistence and stops the actor when the device goes offline; reactivation replays state when it reconnects, typically in under a millisecond for recent snapshots.
Passivation docs →Financial transaction processing
Accounts, wallets, and ledgers are EntityBehavior actors. Each aggregate has exactly one writer by construction — no optimistic lock retries, no phantom reads, no competing UPDATE+version transactions. Commands produce events; events are persisted atomically before the actor state changes. Every transaction is replayable from the event log for audit, reconciliation, or disaster recovery. The DBAL backend keeps insert throughput high under volume.
EntityBehavior reference →Game servers and simulations
Game rooms, match state, and player sessions each live in a dedicated actor. Tick-driven simulations use scheduled messages at a fixed interval — no busy-wait loop needed. The worker pool scales game room actors across CPU cores via the consistent hash ring — each room always routes to the same worker, so state never crosses a thread boundary. Under Swoole, thousands of concurrent WebSocket connections (one per player) run as lightweight coroutines with no thread-per-connection overhead.
Cross-worker ask + scaling →When actors are not the right tool.
Actors add structural overhead. For a simple CRUD application with no concurrency requirements, a traditional PHP-FPM + ORM stack is faster to build and easier to maintain. The actor model earns its keep when you have long-lived state, concurrent workflows, or failure isolation requirements that a stateless request handler cannot provide.
If your use case is primarily background job processing with no shared state between jobs, Symfony Messenger or Laravel Queues are simpler — they solve a narrower problem with less setup. Nexus is the right tool when you need the jobs themselves to be stateful, coordinated, or supervised.
Read the "when to use actors" decision guide →Pick your starting point.
Each use case maps to a specific area of the documentation. Skip the general overview and jump directly to the pattern you need.
Find your use case in the docs.
Each pattern above links to the relevant documentation section with runnable examples.
composer require nexus-actors/nexus