- How do I install juststeveking/workflow-engine in a Laravel app?
- Install it with Composer using composer require juststeveking/workflow-engine. The package supports Laravel package auto-discovery, so the service provider is registered without manual edits to config/app.php. After installing, publish any config or migration files the package ships and run your migrations. The whole adoption step is short because the package footprint is small and non-invasive.
- Which Laravel and PHP versions does workflow-engine support?
- The authoritative answer is the require block in the package's composer.json, so check that before you commit to it. The v1.1.2 release notes are a single additive change and do not restate framework or PHP constraints. Confirm there is a CI matrix covering the Laravel and PHP versions you actually run in production. If your app is on a version outside the tested matrix, validate on a sandbox branch first.
- Does the package publish its own migrations, and how is the schema handled?
- The package persists workflows and transitions as Eloquent models, so it needs database tables, but whether it ships publishable migrations is the main integration unknown to verify early. Install in a sandbox branch and publish the package assets to see exactly what schema it creates. Review that schema against your existing database before running it anywhere shared. Decide up front how you will track future schema changes from the package, since upgrades to published migrations are your responsibility once they are in your app.
- How do I define a workflow with states, transitions, and actions?
- Workflows are modelled in PHP with explicit states, transitions between those states, guards that decide whether a transition may run, and actions that execute when it does. You attach the workflow to a record and then move it through each step via the package's expressive API. Because everything is Eloquent-backed, you can add domain fields, relationships, and casts to the underlying models. This fits domains that map cleanly to explicit states and guarded transitions, such as approvals or onboarding flows.
- How do guards work and can I stop a transition from running?
- Guards are conditions evaluated before a transition is allowed, so a record cannot move to a state your business rules do not permit. Keep guard logic small and deterministic, and put side effects in actions rather than in guards. Test each guard against the allowed and denied paths, since a permissive guard is the most common way workflow bugs reach production. Also decide how a rejected transition should surface to the caller, for example as an exception or a validation-style response.
- Can I subclass the package's workflow or transition models?
- Yes, and v1.1.2 makes this cleaner by letting a subclassed model declare its own factory through a newFactory() override. The package is designed around Eloquent models that consumers extend, which is what you want when you need extra columns, relationships, or casting. Existing integrations that rely on the default factories are unaffected, because the change is additive and backwards compatible. Decide your extension convention once and apply it consistently rather than per model.
- Does workflow-engine keep an audit trail of transitions?
- Because transitions are Eloquent entities, they give you a natural place to record who moved a record and when. Whether that is sufficient for audit or compliance work depends on what history the package persists by default, so verify it during your pilot. If you need an immutable trail, log every transition through events or listeners and write to an append-only store. Confirm this before you put a regulated process on the engine.
- Is workflow-engine a replacement for a BPMN or orchestration engine?
- No. It is a lightweight state and transition engine for Laravel, not a general-purpose BPMN or orchestration platform. Choose it when your domain maps to explicit states with guarded transitions; look elsewhere for parallel gateways, long-running sagas, or cross-service orchestration. Keeping that boundary clear avoids fighting the package as requirements grow.
- Is upgrading to v1.1.2 safe?
- v1.1.2 is a patch release with one additive, backwards-compatible change, and it does not alter runtime workflow semantics. Pin to ^1.1 and review the v1.1.1 to v1.1.2 diff, which is small enough to audit in full. If you have not subclassed the package models, the change should not affect you at all. If you have, point your subclass at your own factory to take advantage of it.
- Is juststeveking/workflow-engine actively maintained and production ready?
- It is a young 1.x package with a single maintainer, so bus factor and release cadence are real considerations for critical paths. The code footprint is small and non-invasive, which keeps the ongoing maintenance burden low. Before committing, check the maintainer's issue-response history and release frequency. Then run a pilot with one real, low-risk workflow, confirm audit history and failure behavior, and expand to critical paths only after that.