Filament Workflow Manager Laravel Package

Getting Started

Check compatibility before anything else. The last tagged release is from October 2022, which puts it in the Filament v2 / Laravel 9 era. Confirm the constraints in composer.json against your app before running composer require heloufir/filament-workflow-manager. On a Filament v3/v4 project you will almost certainly need to fork it, bump the filament/filament constraint, and fix the namespaces/APIs that changed (form/table schema builders, Filament\Resources signatures, getPages()). Budget a day for that fork rather than expecting a drop-in install.

Minimal install path:

1. composer require heloufir/filament-workflow-manager
2. Publish and run migrations: php artisan vendor:publish --tag="filament-workflow-manager-migrations" then php artisan migrate
3. Publish the config if you need to change table names or model bindings: php artisan vendor:publish --tag="filament-workflow-manager-config"
4. Register the plugin in your panel provider (->plugin(WorkflowManagerPlugin::make()) in v2 style)
5. php artisan optimize:clear and log into the panel — you should see the workflow resources in the navigation.

Where to look first, in order:

• database/migrations/ — this tells you the real data model (workflows, states, transitions, and any pivot linking a workflow to a model). Everything else follows from these tables.
• config/ — model class bindings and table names you may want to override.
• src/Models/ — the Eloquent models you'll actually query.
• src/Resources/ — the Filament CRUD screens; read these to understand what the UI lets you configure and what it deliberately doesn't.
• The trait (usually something like HasWorkflow) — this is the seam between the package and your models.

First use case to prove out: define a small workflow in the admin UI — say draft → review → approved → published for a Post model. Add the trait to Post, attach the workflow, then write one test that transitions the post from draft to review in code. If that works end-to-end, you understand the package. If the trait doesn't exist in the shape you expect, that's your signal to stop and evaluate alternatives before going further.

Implementation Patterns

UI-defined workflows are data, not code. The core value proposition is that an admin builds states and transitions in the panel. That means your workflow definition lives in the database and is not in version control. The pattern that works: design the workflow in the UI on a local/staging environment, then export it into a seeder or a dedicated WorkflowInstaller service that creates states and transitions idempotently (firstOrCreate keyed on workflow + state name). Run it from your deploy pipeline. Skip this and you'll have a production database whose workflow graph nobody can reproduce.

Attach workflows to your models via the trait, not via raw pivot queries. Add the trait to the model, and expose the current state through an accessor or a small wrapper method on the model ($post->currentState(), $post->canTransitionTo('approved')). Keeping this thin layer in your codebase means that when you eventually fork or replace the package, you only rewrite the wrapper.

Drive transitions from Filament table and form actions, not from bespoke pages. The natural integration is a Tables\Actions\Action on the resource list ("Submit for review", "Approve") that calls the transition service and then ->successNotificationTitle() + $livewire->refreshFormData() / table refresh. Guard the action's visible() with the model's canTransitionTo check so illegal transitions never render. This is where the package earns its keep: admins get buttons that are correct by construction because the graph is the source of truth.

Put side effects behind events, not inside the transition call. Transition logic should stay a single state write. Fire your app's own domain event (or listen to the package's transition event if one exists) and handle notifications, audit rows, and downstream jobs in listeners. This keeps transition actions reusable across HTTP, console, and queue contexts.

Seed a test fixture factory. In tests/, build a helper that creates a known workflow graph once per test class and attaches it to a model instance. Without this, every test ends up hand-rolling states and the suite becomes brittle against workflow changes. Use RefreshDatabase and keep the fixture in one place.

Integration tip — treat it as a state machine, not a BPM engine. There are no timers, no parallel branches, no compensation handlers. If a requirement has "wait 3 days then escalate," model that with a scheduled job that queries models in a given state, not with the package. Pushing orchestration requirements into it will end badly.

Gotchas and Tips

The maintenance risk is the headline gotcha. Seventy stars and a 2022 release means no security patches, no Filament 3/4 support, and no upstream fixes. Before committing, read the issue tracker and check whether anyone has published a maintained fork. If not, plan for a private fork with a pinned major version — and add a note in your README so the next developer knows why composer.json has a vcs repository entry.

Namespaced migrations can collide. Table names like workflows, states, and transitions are generic. If your app already has a states table (addresses, order statuses, whatever), you'll get a confusing migration failure or, worse, silently wrong joins. Rename via the published config before the first migration, and re-check the models if the config only changes the migration side.

State caching. If you cache model state anywhere (model accessors, Cache::remember), remember to bust it in the same transaction as the transition. A stale "current state" in the UI after an approval is the most common bug report on packages like this.

Config and class-map caching will bite you in production. After publishing config or changing model bindings, php artisan config:clear && php artisan optimize:clear. Deployments that only run composer install will keep the old bindings and produce "class not found" errors that don't reproduce locally.

Debugging transitions: when an action does nothing, log the transition attempt with the from-state, to-state, and the result of the guard check. Nine times out of ten the problem is that the workflow attached to the model isn't the one you edited in the UI — a duplicate workflow row created during testing, or a model pointing at an older workflow version. Query the pivot table directly to confirm.

Extension points to prefer: publish and override the views rather than editing vendor files; extend the package's Resource classes and re-register yours in the panel provider if you need extra fields on the state/transition forms; use model observers on your model rather than patching the package's transition handler. Anything you put in vendor/ disappears on the next composer update.

Have an exit ramp. Because the package is effectively unmaintained, isolate it: one trait, one service class, one set of Filament actions. If you do need to migrate to symfony/workflow plus a hand-rolled Filament resource, that isolation turns a rewrite into a swap — the workflow tables map cleanly onto Symfony's places/transitions concept, and the admin UI is a weekend of Filament work.