README

with this package you can display or add actions to your views using state, this package depends on spatie/laravel-model-states package.

Installation

You can install the package via composer:

composer require abather/spatie-laravel-model-states-actions

Usage

Follow the Doc in Laravel-model-states , but for each State you have to extends Abather\SpatieLaravelModelStatesActions\State :

use Abather\SpatieLaravelModelStatesActions\State;
use Spatie\ModelStates\StateConfig;

abstract class PaymentState extends State
{   
    public static function config(): StateConfig
    {
        return parent::config()
            ->default(Pending::class)
            ->allowTransition(Pending::class, Paid::class)
            ->allowTransition(Pending::class, Failed::class)
        ;
    }
}

state field

by default the package expects the state to be stored in a field called state, if you use another field you can pass it to the services:

StateActionsService::make(Order::class, 'importance')->actions()
StateFilterService::make(Order::class, 'importance')->tableFilter()

the field will be passed to the actions, so the authorization and the transition will use it.

for the methods that you call on the state itself you can pass the field as well:

OrderState::textColumn('importance')
OrderState::textEntry('importance')
OrderState::formSelect(Order::class, 'importance')

or you can override $state_key in your base state class and skip passing the field every time:

abstract class OrderState extends State
{
    public static string $state_key = 'importance';
}

state name

you can name your states as you do in Spatie package:

class Paid extends PaymentState
{
    public static $name = 'paid';
}

the package will resolve the name back to the state class, and the value that stored in the database will be used for the select options and the filters.

configure authorization

you can define ability name for each state that well be used to determine if the user can change the state or not as:

<?php

namespace App\States\Order;

class Canceled extends OrderState
{
    protected static ?string $ability = 'cancel';
}

that mean it well look to ability name called cancel in OrderPolicy class.

also you can skip authorization by override the attribute $skip_authorization = true

keep in mind that the package also chick if you can transfer to the state using canTransitionTo(Cancel::class) that come with Spatie Package you can view it here

Customize Action Icon & Color

you can custom the state color and icon by overriding the attributes $color & $icon

<?php

namespace App\States\Contract;

class Canceled extends ContractState
{
    protected static ?string $color = 'danger';
    protected static ?string $icon = 'heroicon-o-cursor-arrow-rays';
}

for these attributes you have to follow Filament Doc about each one of them Icon Doc, Color Doc

Localization

you need to create states.php file to translate the state and the structure of each state should be as:

    'ClassName' => [
        'title' => '', //This is the name that well be displayed.
        'label' => '', //This is the action name that used in action button.
    ],

Display Current State

To display the current state in Table you can use StateClass::stateTextColumn() as column in table:

 public static function table(Table $table): Table
{
    return $table
        ->columns([
            //Other Columns
            ContractState::textColumn(),
            //Other Columns
        ]);
}

if you went to display the current state in Edit or Info List you can do so by adding state->display() method to header actions:

class ViewContract extends ViewRecord
{
    protected static string $resource = ContractResource::class;

    protected function getHeaderActions(): array
    {
        return [
            //Other Actions
            $this->record->state->display(),
            //Other Actions
        ];
    }
}

feel free to add it to any place that accept Filament\Actions\Action object.

to display the state as normal TextEntry inside InfoList you can do so by using StateClass::textEntry():

    public static function infolist(Infolist $infolist): Infolist
    {
        return $infolist
            ->schema([
                //...
                ContractState::textEntry(),
                //...
            ]);
    }

to include the select form filed use formSelect(static::getModel()) method:

public static function form(Form $form): Form
    {
        return $form
            ->schema([
                //....
                ContractState::formSelect(static::getModel()),
                //...
             ]);
    }

View actions in Table:

you can view the available actions 'depends on authorizations as states configuration':

    public static function table(Table $table): Table
    {
        return $table
            ->columns([])
            ->actions([
                    ...StateActionsService::make(static::getModel())->tableActions(),
            ]);
    }

tableActions() method well return an array of Filament\Tables\Actions\Action objects.

View actions in any page

you can view the available actions 'depends on authorizations as states configuration' in any resource page:

class ViewContract extends ViewRecord
{
    protected static string $resource = ContractResource::class;

    protected function getHeaderActions(): array
    {
        return [
            ...StateActionsService::make(Contract::class)
                ->actions(),
        ];
    }
}

actions() will return an array of Filament\Actions\Action objects, that mean you can use it any place that accept Action object.

View actions as group

you can view available actions in any resource page as group :

class ViewContract extends ViewRecord
{
    protected static string $resource = ContractResource::class;

    protected function getHeaderActions(): array
    {
        return [
            StateActionsService::make((static::$resource)::getModel(), 'importance')
                    ->excludeStates($this->record->importance)
                    ->actionsAsGroup($this->record)
        ];
    }
}

if you don't pass the record it will not display the current state.

Config ordering actions

if you went to display available actions in specific order you can do so by overriding $order attribute in each State.

class Approved extends PaymentState
{
    public static int $order = 1;    
}

class Rejected extends PaymentState
{
    public static int $order = 2;
}

action without confirmation modal

if you don't went the conformation modal you can set attribute $requires_confirmation to false in the state:

<?php

namespace App\States\Contract;

class Canceled extends ContractState
{
    protected static ?bool $requires_confirmation = false;
}

or change it in the base state class:

<?php

namespace App\States\Order;

use App\States\State;
use Spatie\ModelStates\Attributes;

abstract class OrderState extends State
{
    protected static ?bool $requires_confirmation = false;
}

this will stop confirmation modal to all states under this class.

Add State Filters To Table

you can include state filters to your table by using StateFilterService::make(Contract::class)->tableFilter()as:

public static function table(Table $table): Table
    {
        return $table
            ->columns([
                //
            ])
            ->filters([
                StateFilterService::make(static::getModel())
                    ->tableFilter(),
            ]);
    }

the filter will use the field that passed to the service, so if your state stored in another field you only need to pass it once:

StateFilterService::make(static::getModel(), 'importance')
    ->tableFilter(),

you can hide a state from the filters by overriding $exclude_from_filters in the state:

class Canceled extends OrderState
{
    public static bool $exclude_from_filters = true;
}

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

abather / spatie-laravel-model-states-actions

Package info

Security

Fund package maintenance!

Statistics