Package stability matrix
All 25 packages follow a two-tier stability model. "Stable" means the public API is frozen for the current major version — breaking changes require a semver major bump and a migration guide. "Experimental" means the API is a preview subject to breaking changes in minor releases; use only if you can absorb churn.
Process criteria for Stable
- ✓Public API documented and reviewed
- ✓90 %+ method coverage in CI
- ✓Psalm Level 1 strict with targeted suppressions documented
- ✓Breaking changes require a semver major + migration guide
API maturity criteria for Stable
- ✓All public interfaces, classes, and methods documented
- ✓Generic type parameters fully annotated (Psalm templates)
- ✓Integration tests covering primary usage paths
- ✓Changelog entry for every shipped change
Nexus is pre-1.0. "Stable" means the package's API is settled within the current development line — it is not a production-hardening claim. All packages may change before 1.0.
| Package | Stability | Description | Notes |
|---|---|---|---|
| nexus-actors/core | Stable | Actor model foundation — Behavior, ActorRef, ActorSystem, mailbox, supervision | — |
| nexus-actors/runtime | Stable | Shared runtime abstractions — Runtime, Duration, Cancellable, mailbox contracts | — |
| nexus-actors/runtime-fiber | Stable | PHP Fiber runtime — cooperative multitasking, no Swoole required | — |
| nexus-actors/runtime-swoole | Stable | Swoole coroutine runtime for production async I/O | — |
| nexus-actors/runtime-step | Stable | Deterministic step runtime for unit testing | — |
| nexus-actors/app | Stable | PSR-11 application startup (NexusApp builder) | — |
| nexus-actors/serialization | Stable | Message and envelope serialization (PHP native, Valinor) | — |
| nexus-actors/persistence | Stable | Event sourcing and durable state core — EventSourcedBehavior, DurableStateBehavior | — |
| nexus-actors/persistence-dbal | Stable | DBAL-backed event store, snapshot store, and durable state store | — |
| nexus-actors/persistence-doctrine | Stable | Doctrine ORM-backed event store, snapshot store, and durable state store | — |
| nexus-actors/worker-pool | Experimental | Multi-worker pool — WorkerNode, ConsistentHashRing, WorkerActorRef | — |
| nexus-actors/worker-pool-swoole | Experimental | Swoole thread-based worker pool transport (WorkerPoolApp, ThreadQueueTransport) | Requires ZTS PHP |
| nexus-actors/http | Stable | HTTP routing core — HttpApp DSL, handler/param resolution, middleware pipeline | — |
| nexus-actors/http-server-swoole | Stable | Swoole worker-mode HTTP server adapter (SwooleHttpServerAdapter) | — |
| nexus-actors/http-server-swoole-threads | Stable | Swoole thread-mode HTTP server with graceful-shutdown hooks (multi-core) | Requires ZTS PHP |
| nexus-actors/http-auth | Stable | HTTP authentication middleware — bearer token, Principal, #[FromPrincipal] | — |
| nexus-actors/http-ws | Experimental | WebSocket DSL — WsApplication, WebSocket handler, actor-backed connections | — |
| nexus-actors/http-toolkit | Stable | Reusable HTTP middlewares — CORS, rate limit, body size limit, helper resolvers | — |
| nexus-actors/doctrine-dbal | Stable | Coroutine-aware DBAL connection pool + HTTP middleware + #[Transactional] | — |
| nexus-actors/doctrine-orm | Stable | Pooled EntityManager injection + EntityBehavior DSL for aggregate actors | — |
| nexus-actors/logger | Stable | Async PSR-3 logger backed by LogActor mailbox with Monolog-compatible handlers | — |
| nexus-actors/cluster | Experimental | Remote actor contracts — NodeAddress, ClusterTransport, NodeDirectory (API preview; not production-ready) | — |
| nexus-actors/cluster-tcp | Experimental | Swoole TCP cluster mesh — gossip membership, phi-accrual failure detection, ClusterRef (not production-ready) | — |
| nexus-actors/psalm | Stable | Psalm plugin — ReadonlyMessage, MutableState, BlockingCall, and PropsReturnType rules | — |
| nexus-actors/skeleton | Stable | Project skeleton — composer create-project starter with interactive setup wizard | — |
| nexus-actors/nexus | Stable | Meta-package — installs nexus-actors/core, runtime, runtime-fiber, and serialization in one step | — |
ZTS-dependent packages require PHP 8.5+ compiled with Zend Thread Safety and Swoole 6.2.1+ built with--enable-swoole-thread. SeeZTS PHP setup guide for environment configuration.
The semver promise.
Nexus follows Semantic Versioning 2.0strictly across all stable packages. A major version bump (e.g. 1.x → 2.x) means at least one public API has changed in a backward-incompatible way. Every major release ships with a migration guide explaining what changed and how to update. A minor version bump adds new public API in a backward-compatible manner — existing code continues to work without changes. A patch version bump fixes bugs without changing the public API.
Internal implementation classes (marked @internalin docblocks and prefixed Internal\ by convention) are not covered by the semver promise. If you depend on@internal APIs, you accept the risk of breakage in minor releases. Public interfaces, abstract classes, and all documented methods are protected.
Experimental packages (currently only nexus-cluster) explicitly do not follow the semver API-stability promise for minor releases. The CHANGELOG entry for each release marks whether the change is semver-breaking or not.
Deprecation policy.
Public API that needs to change is first deprecated in a minor release — it remains fully functional but emits a @deprecated Psalm annotation that tools can surface as a warning. Deprecated API is removed only in the next major version, giving at least one full minor version cycle for migration.
When an API is deprecated, the release notes include:
- ✓The exact method or class being deprecated
- ✓The recommended replacement API
- ✓A code example showing before and after
- ✓The target major version in which the deprecated API will be removed
No API is ever removed without first going through a deprecation cycle, except in the case of a security vulnerability requiring an immediate fix.
What "stable" means in practice.
The stability tier in the matrix above is not a quality judgement — it is a compatibility promise. A package marked Stable has met the criteria listed above: documented API, 90%+ method coverage, Psalm level 1, integration tests across both FiberRuntime and SwooleRuntime. You can add it to acomposer.json with a caret constraint (^1.0) and rely on Composer's range resolver to keep you on compatible releases.
Stable
Public API is frozen for the current major. Breaking changes require a semver major bump and a migration guide. Use with a caret constraint in Composer. Suitable for production use.
Experimental
API is a preview. Breaking changes may ship in minor releases. Use with an exact version constraint in Composer. Suitable for evaluation and early adoption if you can absorb churn. Currently onlynexus-cluster.
Following changes.
The easiest way to track Nexus releases is to watch theGitHub Releasespage — every release has a CHANGELOG excerpt and a link to the full migration notes if the release is a major version. You can also subscribe to release notifications on GitHub by watching the repository with "Releases only" selected.
Individual packages split to their own GitHub repositories viasplitsh-lite. If you only usenexus-actors/nexus-core, you can watch the split repository to get per-package release notifications without noise from unrelated packages.
Questions about package status?
Open an issue or start a discussion on GitHub — the maintainers respond within one business day.
composer require nexus-actors/nexus