Spatie Laravel Model States Actions Laravel Package

Product Decisions This Supports

• Admin workflow acceleration: Supports decisions to standardize state-driven actions across Filament back-office resources—orders, payments, contracts, tickets, subscriptions, onboarding/KYC, and content publishing—without building custom action buttons for each model.
• Build vs. adopt: Strong candidate for “adopt open source” when the product already uses spatie/laravel-model-states and Filament. It reduces custom glue code for state display, transition actions, authorization checks, confirmation modals, localization, icons/colors, action ordering, grouping, table filters, and now notification feedback plus live refresh after transitions.
• Roadmap sequencing: Enables a faster path for internal ops features such as approval queues, cancellation/refund flows, fulfillment transitions, and lifecycle filters. The v2.1.1 notification and live-refresh support strengthens the case for responsive admin workflows by making transitions visible immediately, but it remains an admin-panel accelerator, not a full workflow/BPM engine. Roadmap decisions around audit trails, SLA reporting, and complex approvals still require separate investment.
• UX consistency decision: Encourages a single pattern for how state appears and changes across resources: text columns/entries, form selects, action groups, state filters, transition notifications, and refreshed table/entry data after actions. This is useful when multiple teams build admin screens inconsistently.
• Authorization product decision: Lets PMs standardize per-state abilities (cancel, approve, etc.) in Laravel policies and ensure actions only appear when both policy and transition rules allow them. This supports safer back-office permissions without bespoke UI logic.
• Use-case fit: Best for internal/admin lifecycle management with relatively simple state machines. The new notification and live-refresh features improve operator feedback and reduce stale admin views after transitions. Poor fit for customer-facing state UX, complex multi-step orchestration, or regulated workflows requiring audit/compliance features out of the box.
• Risk decision: Low stars (4), zero dependents, and a single-maintainer profile mean adoption should be scoped as a tactical accelerator, not a strategic platform dependency. v2.1.1 appears to be a minor feature release with no breaking changes noted, but notification and live-refresh behavior should still be verified in a pilot. Favor version pinning and a fallback plan.

When to Consider This Package

Consider it when:

• The product uses Laravel and Filament for internal admin/back-office screens.
• The domain already uses, or is ready to adopt, spatie/laravel-model-states.
• State transitions are simple enough to map to Filament actions and Laravel policy abilities.
• The team wants faster delivery of state-aware tables, forms, filters, and action groups.
• The admin UI needs localized state labels, consistent icons/colors, confirmation modals, ordered actions, and built-in transition feedback via notifications and live refresh.
• Operators benefit from immediate UI feedback after state changes without manually reloading tables or entries.
• The team can tolerate MIT open-source maintenance risk, pin versions, review source, and own testing/upgrade work.
• Filament v4 compatibility is relevant; v2.0.0 explicitly added Filament v4 support and v2.1.1 adds notification/live-refresh features, but the exact PHP/Filament/Laravel/Livewire matrix should be verified in a spike.

Look elsewhere when:

• The product is not on Filament or not using Spatie model states.
• Workflows require BPMN-style orchestration, long-running sagas, human task queues, or complex conditional branching.
• The product needs vendor SLAs, enterprise support, security certification, or guaranteed maintenance.
• Audit logging, compliance evidence, or role matrices must be provided out of the box.
• State transition authorization is too complex to express as per-state policy abilities.
• Notification needs extend beyond simple transition feedback into multi-channel delivery, digests, read-state tracking, escalation policies, or websocket-driven operational dashboards.
• The team cannot accept low adoption signals (4 stars, 0 dependents) without a proof of concept and source review.

How to Pitch It (Stakeholders)

Executive summary: This is a small, MIT-licensed accelerator for Laravel/Filament admin panels that turns existing model states into consistent, permission-aware actions. v2.1.1 adds notification support and live refresh for state transitions, improving operator feedback and reducing stale admin views. It can reduce custom back-office code for order, payment, contract, and approval workflows. It is not a strategic workflow platform and has low community adoption, so adopt it only for internal admin use after a scoped pilot.

Engineering summary: The package sits on top of spatie/laravel-model-states and Filament. Teams extend the package’s base State, define policy abilities, and get reusable state columns, entries, form selects, table actions, action groups, filters, and now transition notifications with live refresh. It remains a thin convenience layer—pin it, test authorization, transition behavior, notification delivery, live-refresh behavior, and Filament/Livewire compatibility, and be prepared to fork or replace it if maintenance stalls.

Recommendation: Run a one-resource proof of concept against an existing state machine, including the new notification and live-refresh behavior. If it cleanly replaces custom Filament action code and passes authorization, UX, and upgrade checks, standardize it for internal admin workflows; otherwise, keep custom implementation or defer adoption.