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
| 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 bootstrap (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 | Stable | Multi-worker pool — WorkerNode, ConsistentHashRing, WorkerActorRef | — |
| nexus-actors/worker-pool-swoole | Stable | 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 | Stable | 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/psalm | Stable | Psalm plugin — ReadonlyMessage, MutableState, BlockingCall, and PropsReturnType rules | — |
| nexus-actors/skeleton | Stable | Project skeleton — composer create-project starter with interactive bootstrap 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. See
ZTS PHP setup guide
for environment configuration.
The semver promise.
Nexus follows Semantic Versioning 2.0 strictly 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 @internal
in 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 a
composer.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 only
nexus-cluster.
Following changes.
The easiest way to track Nexus releases is to watch the GitHub Releases page — 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 via
splitsh-lite. If you only use
nexus-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