Spatie Model States Visualizer

• Requirements
• Installation
• Quick start
  • 1. Prepare your model
  • 2. Add the Kanban to a resource list page
  • 3. Verify detection (optional)
• Kanban board
  • Plug-and-play widget
  • Resource trait (recommended)
  • Generated widget (optional)
  • Custom widget (full control)
• Auto-detection
  • State field detection
• Spatie Model States
  • Transitions
  • Column keys and labels
  • Column ordering
• Enum-based workflows
• Optional model hooks
  • Search
  • Status history on Kanban moves
  • Spatie state class resolution
• Status timeline (Infolist)
  • Basic usage
  • Resource trait
  • Options
• Kanban features
• Artisan command
• Configuration
• How transition validation works
• Where to register the board
• Compatibility
• License

State-aware Kanban board and status timeline components for Filament v5.

Built to sit on top of:

• spatie/laravel-model-status > powers the timeline (status history log)
• spatie/laravel-model-states > powers transition validation and column discovery on the Kanban board (optional but recommended)

Filament Model States provides a plug and play auto-detection for enums, Spatie Model States, or plain database values.

#Requirements

• PHP 8.3+
• Laravel 11–13
• Filament v5
• spatie/laravel-model-status (required for timeline + optional status logging on Kanban moves)
• spatie/laravel-model-states (optional for server-side transition validation and config-driven column order)

#Installation

composer require usamamuneerchaudhary/filament-model-states

php artisan vendor:publish --tag="filament-model-states-config"

php artisan filament:assets

After upgrading the package, re-run php artisan filament:assets and hard-refresh your browser if Kanban styles or drag-and-drop stop working.

#Quick start

#1. Prepare your model

Option A: backed enum (simplest)

use Spatie\ModelStatus\HasStatuses;

class Order extends Model
{
    use HasStatuses;

    protected function casts(): array
    {
        return [
            'workflow_state' => WorkflowState::class,
        ];
    }
}

enum WorkflowState: string
{
    case Draft = 'draft';
    case Pending = 'pending';
    case Completed = 'completed';

    public function label(): string
    {
        return match ($this) {
            self::Draft => 'Draft',
            self::Pending => 'Pending',
            self::Completed => 'Completed',
        };
    }

    /** @return array<string, list<string>> */
    public static function transitions(): array
    {
        return [
            'draft' => ['pending'],
            'pending' => ['completed'],
            'completed' => [],
        ];
    }
}

Option B: Spatie Model States

use Spatie\ModelStates\HasStates;
use Spatie\ModelStatus\HasStatuses;

class Booking extends Model
{
    use HasStates;
    use HasStatuses;

    protected function casts(): array
    {
        return [
            'status' => BookingState::class,
        ];
    }
}

#2. Add the Kanban to a resource list page

use Usamamuneerchaudhary\FilamentModelStates\Concerns\HasStateKanbanBoard;

class BookingResource extends Resource
{
    use HasStateKanbanBoard;

    // ...
}

// Pages/ListBookings.php
protected function getHeaderWidgets(): array
{
    return [
        BookingResource::getStateKanbanBoard(),
    ];
}

That's it. Columns, labels, transitions, and column order are auto-detected.

#3. Verify detection (optional)

php artisan filament-model-states:make-kanban Booking --detect --state-field=status

#Kanban board

#Plug-and-play widget

Point the board at any model, no subclass required:

use Usamamuneerchaudhary\FilamentModelStates\Widgets\ModelStateKanbanBoard;

// List page header widgets
ModelStateKanbanBoard::for(Booking::class)

// Non-default state field
ModelStateKanbanBoard::for(Booking::class, stateField: 'status')

#Resource trait (recommended)

Add HasStateKanbanBoard to your Filament resource, then register on the list page:

use Usamamuneerchaudhary\FilamentModelStates\Concerns\HasStateKanbanBoard;

class OrderResource extends Resource
{
    use HasStateKanbanBoard;
}

protected function getHeaderWidgets(): array
{
    return [
        OrderResource::getStateKanbanBoard(),
    ];
}

#Generated widget (optional)

If you prefer a dedicated widget class:

php artisan filament-model-states:make-kanban Booking --resource=BookingResource

This creates app/Filament/Widgets/BookingKanbanBoard.php and prints wiring instructions. Use --force to overwrite, --detect to inspect without generating.

#Custom widget (full control)

Extend StateKanbanBoard when you need complete control over columns, queries, card content, or authorization:

use Usamamuneerchaudhary\FilamentModelStates\Widgets\StateKanbanBoard;

class OrderStatusBoard extends StateKanbanBoard
{
    protected function getModel(): string
    {
        return Order::class;
    }

    protected function getStateField(): string
    {
        return 'workflow_state';
    }

    protected function getColumns(): array
    {
        return ['draft', 'pending', 'processing', 'completed', 'cancelled'];
    }

    protected function getAllowedTransitions(): ?array
    {
        return WorkflowState::transitions();
    }

    protected function getColumnLabel(string $key): string
    {
        return WorkflowState::from($key)->label();
    }

    protected function getCardTitle(Model $record): string
    {
        return "Order #{$record->reference}";
    }

    protected function getCardSubtitle(Model $record): ?string
    {
        return $record->customer_name;
    }

    protected function getQuery(): Builder
    {
        return Order::query()->where('team_id', filament()->getTenant()->id);
    }
}

#Auto-detection

ModelStateKanbanBoard resolves everything through StateConfigurationResolver:

#State field detection

The resolver looks for, in order:

1. workflow_state, state, or status attributes in $casts
2. Any enum cast whose field name contains state or status
3. Any Spatie state cast on a field containing state or status
4. Any enum or Spatie state cast

Pass an explicit field when ambiguous:

ModelStateKanbanBoard::for(Booking::class, stateField: 'status')

#Spatie Model States

#Transitions

When your model uses spatie/laravel-model-states, the Kanban reads allowances directly from your abstract state's config():

abstract class BookingState extends State
{
    public static function config(): StateConfig
    {
        return parent::config()
            ->default(Initiated::class)
            ->allowTransition(Initiated::class, AwaitingPayment::class, ToAwaitingPayment::class)
            ->allowTransition(Initiated::class, Expired::class, ToExpired::class);
    }
}

On drag-and-drop:

1. UI: only allowed target columns are highlighted; invalid targets are blocked client-side.
2. Server: $currentState->canTransitionTo($targetStateClass) is called before saving.
3. Persist: $currentState->transitionTo($targetStateClass) runs your transition classes (ToAwaitingPayment, etc.).
4. History: if the model uses HasStatuses, setStatus() is called automatically.

#Column keys and labels

Without label(), headers are generated from $name (e.g. initiated → "Initiated").

class Initiated extends BookingState
{
    public static string $name = 'initiated';

    public static function label(): string
    {
        return 'Initiated';
    }

    public static function description(): ?string
    {
        return 'Booking has just been created';
    }
}

#Column ordering

Columns are ordered automatically. Priority:

1. columnOrder() on the abstract state class (explicit override)
2. $sortOrder or sortOrder() on each concrete state class
3. Config registration order: default state first, then the order allowTransition() calls appear in config()
4. Filesystem discovery: remaining states in directory order

Explicit order example:

abstract class BookingState extends State
{
    public static function columnOrder(): array
    {
        return [
            'initiated',
            'awaiting_payment',
            'pending',
            'confirmed',
            'completed',
            'cancelled',
        ];
    }
}

Per-state sort order:

class Initiated extends BookingState
{
    public static int $sortOrder = 1;
    public static string $name = 'initiated';
}

#Enum-based workflows

Define transitions on the enum:

public static function transitions(): array
{
    return [
        'draft' => ['pending', 'cancelled'],
        'pending' => ['processing', 'cancelled'],
        'processing' => ['completed', 'failed'],
        'completed' => [],
        'cancelled' => ['draft'],
        'failed' => ['pending'],
    ];
}

Or on the model:

public static function getStateTransitions(): array
{
    return WorkflowState::transitions();
}

Enum case order in the PHP file is used as column order.

#Optional model hooks

#Search

Add a query scope to enable the board's search box:

public function scopeFilamentKanbanSearch(Builder $query, string $search): Builder
{
    return $query->where(function (Builder $query) use ($search): void {
        $query->where('reference', 'like', "%{$search}%")
            ->orWhere('customer_name', 'like', "%{$search}%");
    });
}

#Status history on Kanban moves

Use HasStatuses on the model. Each successful drag calls:

$record->setStatus($targetColumn, 'Moved via Kanban board');

Customize the reason by extending StateKanbanBoard::persistStateChange().

#Spatie state class resolution

If column keys don't map cleanly to state classes, add to your model:

public static function getStateClassForColumn(string $column): string
{
    return match ($column) {
        'awaiting_payment' => AwaitingPayment::class,
        default => throw new InvalidArgumentException("Unknown column [{$column}]"),
    };
}

#Status timeline (Infolist)

Shows a vertical history of status changes from spatie/laravel-model-status.

#Basic usage

use Usamamuneerchaudhary\FilamentModelStates\Infolists\Components\StatusTimelineEntry;

public static function infolist(Schema $schema): Schema
{
    return $schema->components([
        StatusTimelineEntry::make('status_history')
            ->label('Status history')
            ->limit(20),
    ]);
}

#Resource trait

use Usamamuneerchaudhary\FilamentModelStates\Concerns\HasStatusTimelineInfolist;

class OrderInfolist
{
    use HasStatusTimelineInfolist;

    public static function configure(Schema $schema): Schema
    {
        return $schema->components([
            Section::make('Status history')
                ->schema([
                    self::statusTimelineEntry(),
                ]),
        ]);
    }
}

The timeline reads $record->statuses(), shows each state with reason and duration, and highlights the current one. Status labels match the Kanban board (enum label(), Spatie state label(), or a headline fallback).

#Options

StatusTimelineEntry::make('status_history')
    ->limit(20)              // max entries shown (no pagination UI)
    ->hideReason()           // hide the reason text
    ->emptyStateLabel('No changes yet.');

#Kanban features

• Drag-and-drop between columns with SortableJS (bundled, no CDN)
• Server-side validation: invalid moves are rejected with a notification; cards snap back
• Confirmation modal before saving a move (configurable)
• Search: filters cards when scopeFilamentKanbanSearch is defined
• Column filter: dropdown to focus on a single column
• Totals: SQL counts per column; cards are paginated per column
• Transition hints: "Can move to" chips under each column header
• Authorization: Gate::authorize('update', $record) on every move

#Artisan command

# Inspect auto-detected configuration
php artisan filament-model-states:make-kanban Booking --detect

# Specify a non-default state field
php artisan filament-model-states:make-kanban Booking --detect --state-field=status

# Generate a widget class
php artisan filament-model-states:make-kanban Booking --resource=BookingResource

# Overwrite an existing generated widget
php artisan filament-model-states:make-kanban Booking --force

Example --detect output:

 Model              App\Models\Booking
 State field        status
 Detection source   spatie-model-states
 Columns            initiated, awaiting_payment, pending, ...
 Transitions        {"initiated":["awaiting_payment","expired"], ...}

#Configuration

Published to config/filament-model-states.php:

return [
    'timeline' => [
        'per_page' => 25,
        'show_reason' => true,
        'date_format' => 'M j, Y \a\t g:i A',
    ],

    'kanban' => [
        // Filament color tokens per column key
        'column_colors' => [
            'draft' => 'gray',
            'pending' => 'warning',
            'processing' => 'info',
            'completed' => 'success',
            'cancelled' => 'danger',
            'failed' => 'danger',
        ],

        // Show a danger notification when a drag is rejected
        'notify_on_invalid_transition' => true,

        // Max cards rendered per column (totals always use SQL counts)
        'records_per_column' => 25,

        // Confirm in a modal before persisting a move
        'confirm_before_move' => true,
    ],
];

Unlisted column keys fall back to gray. Override per-widget via getColumnColor() on a custom StateKanbanBoard subclass.

#How transition validation works

When a card is dropped on a new column, moveRecord() runs server-side:

1. Loads the record with a row lock.
2. Authorizes update on the record.
3. Checks the transition:
   • Spatie Model States: $state->canTransitionTo($targetStateClass)
   • Enum / manual map: getAllowedTransitions() array
   • No rules: all moves allowed
4. Persists via transitionTo() (Spatie) or direct attribute save (enum/DB).
5. Optionally logs to status history via setStatus().

The browser cannot bypass step 3, enforcement lives in your state machine, not JavaScript.

#Where to register the board

#Compatibility

• Filament v5 (filament/filament ^5.0)
• Laravel 11–13
• PHP 8.3+
• StatusTimelineEntry uses the Filament v5 schemas/infolists API
• Kanban CSS and JS are bundled via FilamentAsset, run php artisan filament:assets after install

#License

MIT