Filament Workflows Laravel Package

Getting Started

composer require tschucki/filament-workflows
php artisan vendor:publish --tag="filament-workflows-config"
php artisan vendor:publish --tag="filament-workflows-migrations"
php artisan migrate

Register the plugin on the panel you want it on (usually an admin panel, not a customer-facing one):

// app/Providers/Filament/AdminPanelProvider.php
public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(FilamentWorkflowsPlugin::make());
}

Where to look first, in order:

1. config/filament-workflows.php — as of 0.0.5 this is the contract for the package. It now carries class-strings for both the Eloquent models and the Filament resources, so it tells you exactly which classes the package instantiates.
2. The published migrations — these define the workflow/state/transition tables and are the real schema documentation.
3. The package's src/Models and src/Filament/Resources directories — read these before extending anything; there is not much surface area yet.
4. The README, last. On a 0.0.x package the code is more current than the docs.

First use case: attach a workflow to a single obvious model — Order, Ticket, Invoice — and drive its status field through the Filament UI instead of a free-text status column. Define the states and allowed transitions, then let editors move records between them. Do this on one model before wiring up a second; you'll learn the package's assumptions about the model/status relationship cheaply.

Implementation Patterns

Swap models and resources via config (0.0.5+). The whole point of the new release. Instead of editing vendor code, publish the config and point the class-strings at your own subclasses:

// config/filament-workflows.php
return [
    'models' => [
        'workflow' => App\Models\Workflow::class,
        // ...
    ],
    'resources' => [
        'workflow' => App\Filament\Resources\WorkflowResource::class,
        // ...
    ],
];

Extend, don't replace. Subclass the package model and add your concerns — a HasFactory, a global scope for multi-tenancy, an observer, a LogsActivity trait. Replacing the class outright means re-implementing relationships and casting the package already handles. Same for resources: extends the vendor resource, override getNavigationGroup(), table(), form() selectively.

Keep the config as the single switch. Decide once whether a given app uses the default models or custom ones, and commit that config file. Mixing — some panels using custom resources, some using defaults — is a source of "why does this panel look different" bugs that are painful to trace.

Authorize transitions, not just the resource. Filament policies will gate who can open the resource, but "can this user move an order from pending to shipped" is a workflow concern. Put that in a policy on the subject model or a canTransition() method on the record, and call it from the action's visible()/disabled() closures rather than relying on resource-level access.

Seed workflows, don't hand-build them. If states and transitions are data rather than code, they need to exist in every environment. Write a seeder (or an artisan command) that defines the workflow for each model type, and make it idempotent — updateOrCreate on a slug, not blind inserts. Config-driven models make this easier: your seeder references the configured class, not the vendor one.

Testing. Use RefreshDatabase plus your workflow seeder in setUp(). Because the model class is resolved from config, tests can bind a lightweight test double of the workflow model if you want to isolate transition logic from the package's persistence.

Gotchas and Tips

0.0.x means no stability promise. Every minor bump can break you. Pin the version ("tschucki/filament-workflows": "0.0.5") in production and read the changelog before bumping. The jump from 0.0.4 to 0.0.5 changed how models and resources are resolved — that's precisely the kind of change that lands without a major version on a pre-1.0 package.

Config cache is the first thing to clear. After editing class-strings in config/filament-workflows.php, run php artisan config:clear. In a cached production config, a stale or misspelled class-string surfaces as a confusing "class not found" during Filament resource discovery, not at boot.

A typo in a class-string fails late. Config values are strings, not class constants. 'workflow' => App\Models\Workflows::class (plural) resolves fine at config load and explodes when the resource is first rendered. Consider a small test that asserts each configured class exists and extends the expected base — cheap insurance.

Swapped models still use the package's tables. Pointing at a custom model does not rename tables or change columns. If your subclass needs extra columns, add a separate migration and set $table / relationships explicitly; don't assume the package's migration will follow your class.

Migration ordering. Publish the package migrations before writing yours, and make any FK to workflow tables a later migration. Also check whether the package's migrations are published or loaded from the package — if loaded, they run with the vendor timestamp and can collide with an existing table name.

Resource registration doubles up easily. If you register a custom resource in config and Filament auto-discovers the vendor one, you get duplicate navigation entries. Verify what appears in the sidebar after swapping; disable auto-discovery for the vendor namespace or remove the config entry if you intend to keep the defaults.

Filament major-version coupling. This package tracks Filament's API. Confirm your Filament version matches what the release was built against before adopting 0.0.5 — resource class signatures and Action APIs differ across majors, and a mismatch manifests as subtle type errors rather than a clean failure.

Debugging checklist: config:clear → check the resolved class with app(config('filament-workflows.models.workflow')) in tinker → confirm the resource extends the vendor resource and not a stray Filament base → check the record actually has a workflow attached (the UI often renders empty rather than erroring when it doesn't).

Extension points to watch, not to build on yet. Config-driven models and resources is a good sign the author is heading toward a genuinely pluggable package, but at 0.0.5 the config keys themselves may be renamed. Wrap your usage in a small app-level service or trait so a future key rename is a one-file edit rather than a grep across the codebase.