Weave Code
Stagehand Fsm Laravel Package
piece/stagehand-fsm
Stagehand FSM is a Laravel/PHP finite state machine package for defining states, transitions, guards, and actions. Model workflows and object lifecycles with clean, testable state-driven logic.
A finite state machine
Frequently asked questions about Stagehand Fsm
- What is Stagehand FSM used for in a Laravel application?
- Stagehand FSM is a lightweight finite state machine for modeling bounded workflows on Laravel Eloquent models. It fits order lifecycles, approval states, subscription status, and content moderation where explicit states and guarded transitions reduce scattered status checks. It is not a full BPM or workflow engine for long-running human workflows, sagas, or distributed orchestration.
- How do I install piece/stagehand-fsm with Composer?
- Install it with Composer using the package name piece/stagehand-fsm, then pin the exact version in composer.json. Before installing in a modern Laravel app, audit the package composer.json for PHP and Laravel constraints because the last release was in 2018. Run a time-boxed compatibility spike in a non-critical workflow and check service provider registration, autoloading, and Eloquent integration.
- Does Stagehand FSM support Laravel 9, 10, and 11 or PHP 8.x?
- Support for Laravel 9, 10, and 11 or PHP 8.1 through 8.3 is not confirmed by the provided context. The last release date of 2018 suggests it likely predates modern Laravel and PHP 8.x support, and the unknown repository prevents normal due diligence. Verify composer.json constraints and run a compatibility spike before assuming native fit.
- How do I define states and transitions with Stagehand FSM?
- Stagehand FSM uses attribute-driven state and transition definitions, so you declare states, transitions, and guards declaratively rather than embedding status checks in controllers. Keep transition definitions in application code or config and wrap the package behind an application-owned StateMachine or WorkflowEngine interface. That keeps callers stable if you later replace it with Symfony Workflow, Spatie model states, or a custom enum-based service.
- How do guards and transition validation work in Stagehand FSM?
- Guarded transitions use custom validation callbacks to decide whether a transition is allowed. Test every allowed and disallowed path, including guard failures and edge cases, because undocumented behavior and low maintenance increase risk. Keep guards small and domain-focused so they remain testable outside the package.
- Does Stagehand FSM dispatch Laravel events on state changes?
- Yes, the package dispatches Laravel events on every state change according to its overview. Use listeners for audit logging, notifications, or side effects, but verify event names, payloads, queue behavior, and transaction boundaries during the spike. Avoid relying on events for critical consistency without idempotency and failure handling.
- How does Stagehand FSM persist state on Eloquent models?
- Stagehand FSM models stateful workflows directly on Eloquent models, but the provided context does not document exact persistence, schema changes, concurrency handling, idempotency, or transition history. Confirm whether state is stored in a model column, how casts are handled, and whether transitions run inside database transactions. Add your own audit history if the package does not provide it.
- Can I use Stagehand FSM outside Laravel?
- The core is described as framework-agnostic and usable outside Laravel, while the Laravel integration adds Eloquent scopes, helpers, and events. Audit autoloading, PHP version constraints, and whether Laravel-specific features are optional before using it in a non-Laravel PHP service. Wrap it behind an internal interface so framework coupling remains contained.
- Is Stagehand FSM safe for production in a modern Laravel app?
- Treat it as high risk for production in a modern Laravel app: the last release was 2018-01-17, the repository is unknown, adoption is low, and maintenance cadence is not visible. Use it only after a source and Composer audit, compatibility spike, transition tests, and a decision to fork and own patching if needed. BSD-2-Clause permits a fork, but you must own dependency patching, PHP upgrades, and security review. Isolate it behind an application-owned interface, pin the version, assign a code owner, and avoid critical workflows until proven.
- What are maintained alternatives to Stagehand FSM?
- Maintained alternatives include Symfony Workflow, Spatie model states, or a small internal state machine built with PHP enums, transition guards, and database transactions. Compare them with Stagehand FSM through the same transition tests and a low-risk pilot. If Stagehand FSM fails compatibility or ownership checks, replace the adapter without changing callers.
Weaver
How can I help you explore Laravel packages today?