- What is teknoo/states and what problem does it solve?
- teknoo/states is a lightweight PHP library implementing the GoF State pattern and finite state machines. It lets you declare an object's allowed states and transitions, guard invalid state changes, and attach callbacks on entry, exit, or transition events, so state-dependent logic lives in one place instead of scattered switch and if ladders. It is framework-agnostic and carries no persistence, orchestration, or eventing concerns.
- How do I install teknoo/states with Composer?
- Run composer require teknoo/states; it pulls in a single runtime dependency, teknoo/immutable, and is BSD-3-Clause licensed. There is no service provider, facade, or config file to publish. The hard requirement is PHP 8.4 or newer, so check your platform baseline before adding it.
- Does teknoo/states work with Laravel?
- Yes. It is plain PHP with no framework coupling, so you can use it inside Laravel domain models, jobs, or services without registering anything. There is no Laravel-specific integration package, config, or facade. The only constraint is that your Laravel app must already run on PHP 8.4 or later.
- Which PHP version does teknoo/states require?
- The package requires PHP ^8.4, which is the single largest adoption filter for most teams. Applications on PHP 8.1 to 8.3 must complete a platform upgrade first, and that is usually a multi-quarter program rather than a library decision. If this package would be the forcing function for that upgrade, it is usually better to wait.
- How do you declare states and transitions in teknoo/states?
- States are declared with #[StateClass] attributes, replacing the deprecated statesListDeclaration() approach. State methods are builders that return Closure instances rebound to the stated class, so inside the closure $this, self, and static refer to the proxy rather than the state object. That gives real PHP method semantics and visibility enforcement, but it is an unusual idiom that defeats IDE navigation unless the shipped PHPStan extension is loaded, so prototype it with your team first.
- How does teknoo/states reject invalid state transitions?
- Transitions are guarded, and state-method visibility is enforced at runtime by walking the call stack with debug_backtrace(). Calls that are not allowed from the current state fail instead of silently executing. Be aware that stack walking can behave differently behind Doctrine lazy proxies, DI decorators, or mocking tools, and it adds per-call overhead.
- Does teknoo/states persist state or integrate with Doctrine?
- The core library has no persistence concerns at all; Doctrine ORM and ODM support ships as an optional infrastructure layer via StandardTrait and AbstractStandardObject. If your candidate domain objects are serialized into sessions, queues, or caches, spike the reserved __serialize() builder and the state serialization semantics before committing. Otherwise state handling stays entirely in memory.
- Does teknoo/states have a PHPStan extension, and will it break CI?
- Yes, a PHPStan extension ships with the package, but it depends on PHPStan internals outside PHPStan's backward-compatibility promise, so PHPStan patch releases can break it. Upstream patch releases of teknoo/states often exist specifically to repair PHPStan-induced breaks, and the project's own phpstan.neon does not load the extension. Adopting the idiom at scale means pinning PHPStan hard or accepting periodic red CI.
- How does teknoo/states compare to symfony/workflow or enums with match?
- For greenfield applications, an enum plus match or symfony/workflow usually delivers most of the value without the idiom tax of builder-returned Closures. teknoo/states fits best where a legacy domain model such as orders, subscriptions, documents, tickets, or approvals is already paying for conditional sprawl and the alternative is a god-class refactor. Measure before and after cyclomatic complexity and defect rate in the affected module before committing.
- Is teknoo/states actively maintained and safe to use in production?
- It is a small project, roughly 10 stars and no dependents, effectively maintained by a single author, so a vendor-and-freeze posture is credible given the permissive BSD-3-Clause license and small surface, but nobody upstream will be paged for you. Its test configuration fails on any deprecation or notice, which is good hygiene but also means a moving target on dependency bumps. Treat team absorption of the idiom as the dominant adoption cost and budget for it explicitly.