Filament StateFusion

https://github.com/a909m/filament-statefusion
Admin
Filament StateFusion is a powerful plugin that seamlessly integrates Spatie Laravel Model States...
Tokens:50,519
Snippets:358
Trust Score:7.8
License:MIT
Update:6 days ago
Show doc for...
Tokens:
Raw
### configurePackage method implementation

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/filament-statefusion-service-provider.md

Configures the package name and install command with a GitHub star prompt.

```php
public function configurePackage(Package $package): void
{
    $package->name(static::$name)
        ->hasInstallCommand(function (InstallCommand $command) {
            $command
                ->askToStarRepoOnGitHub('a909m/filament-statefusion');
        });
}
```

--------------------------------

### Install filament-statefusion via Composer

Source: https://github.com/a909m/filament-statefusion/blob/main/README.md

Install the plugin via Composer. Requires PHP ^8.1, Laravel ^10.0|^11.0|^12.0, Filament ^3.0|^4.0|^5.0, and Spatie Laravel Model States ^2.0.

```bash
composer require a909m/filament-statefusion
```

--------------------------------

### setUp(): void (protected)

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-bulk-action.md

Configures the bulk action's label, color, icon, tooltip, form, modal, and action behavior. This method is called during action initialization and sets up the bulk transition logic.

```APIDOC
## setUp(): void (protected)

### Description
Configures the bulk action's label, color, icon, tooltip, form, modal, and action behavior. This method is called during action initialization and sets up the bulk transition logic.

### Method
PHP Method

### Endpoint
`setUp(): void`

### Behavior
- **No `hidden()` closure** — the bulk action is always visible in the table's bulk action bar (visibility is controlled by Filament's bulk action selection state).
- **`action(Collection $records, $data)`** — iterates the selected records; per record:
  1. `$record->{$attribute}?->equals($fromState)` — nullsafe: records without the state attribute value are skipped without error;
  2. `in_array($toState::getMorphClass(), $record->{$attribute}->transitionableStates())` — the transition must be allowed;
  3. if both conditions hold: `transitionTo($toStateClass)` (empty `$data`) or `transitionTo($toStateClass, $data[array_key_first($data)])` (form payload present); otherwise the record is silently skipped.
- **No `$this->success()`** — unlike the single-record actions, no success notification is fired.
- **Throws:** `Error` — `getToState()::getMorphClass()` and `getToStateClass()` fail when `transition()` (or `transitionTo()`) was never called; `transitionableStates()` fails when the attribute value is not a Spatie `State` instance.
```

--------------------------------

### Usage example of FilamentStateFusion facade

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/filament-statefusion-service-provider.md

Attempting to call a method on the facade throws an Error because no methods exist.

```php
<?php
use FilamentStateFusion; // facade alias

// No methods exist — the following throws an Error at runtime:
FilamentStateFusion::make();
```

--------------------------------

### Example concrete state class implementing HasFilamentState

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/contracts.md

Shows how to implement the required methods from the parent interfaces on a state class.

```php
<?php
// app/States/CancelledState.php

use A909M\FilamentStateFusion\Contracts\HasFilamentState;
use Filament\Support\Colors\Color;

final class CancelledState extends OrderState implements HasFilamentState
{
    public function getLabel(): string
    {
        return __('Order Cancelled');
    }

    public function getColor(): array
    {
        return Color::Red;
    }

    public function getIcon(): string
    {
        return 'heroicon-o-x-circle';
    }

    public function getDescription(): ?string
    {
        return 'Order cancelled, transaction reversed.';
    }
}
```

--------------------------------

### setUp() method (protected)

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-bulk-action.md

Configures the bulk action's label, color, icon, tooltip, form, modal, and action behavior. The action iterates selected records, transitioning those that match the from state and allow the transition; no success notification is fired. Throws Error if transition() was never called or the attribute value is not a Spatie State instance.

```php
protected function setUp(): void
{
    parent::setUp();
    $this->label(fn () => is_a($this->getClassInstance(), HasLabel::class) ? $this->getClassInstance()?->getLabel() : (is_a($this->getToStateClass(), HasLabel::class) ? $this->getToStateClass()?->getLabel() : null));
    $this->color(fn () => is_a($this->getClassInstance(), HasColor::class) ? $this->getClassInstance()?->getColor() : (is_a($this->getToStateClass(), HasColor::class) ? $this->getToStateClass()?->getColor() : null));
    $this->icon(fn () => is_a($this->getClassInstance(), HasIcon::class) ? $this->getClassInstance()?->getIcon() : ((is_a($this->getToStateClass(), HasIcon::class)) ? $this->getToStateClass()?->getIcon() : null));
    $this->tooltip(fn () => is_a($this->getClassInstance(), HasDescription::class) ? $this->getClassInstance()?->getDescription() : (is_a($this->getToState(), HasDescription::class) ? $this->getToState()?->getDescription() : null));
    $this->action(function (Collection $records, $data) {
        if (empty($data)) {
            $records->each(fn ($record) => ($record->{$this->getAttribute()}?->equals($this->getFromState())
                && in_array($this->getToState()::getMorphClass(), $record->{$this->getAttribute()}->transitionableStates())) ? $record->{$this->getAttribute()}->transitionTo($this->getToStateClass()) : null);
        } else {
            $records->each(fn ($record) => ($record->{$this->getAttribute()}?->equals($this->getFromState())
                && in_array($this->getToState()::getMorphClass(), $record->{$this->getAttribute()}->transitionableStates())) ? $record->{$this->getAttribute()}->transitionTo($this->getToStateClass(), $data[array_key_first($data)]) : null);
        }
    });

    $this->form(fn () => ((method_exists($this->getClassInstance(), 'form')) ? $this->getClassInstance()->form() : null));
    $this->modalDescription(fn () => is_a($this->getClassInstance(), HasDescription::class) ? $this->getClassInstance()->getDescription() : (is_a($this->getToState(), HasDescription::class) ? $this->getToState()->getDescription() : null));
    $this->modalIcon(fn () => $this->getIcon());
    $this->modalIconColor(fn () => $this->getColor());
    $this->requiresConfirmation();
}
```

--------------------------------

### setUp() method implementation

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-select-filter.md

Configures the filter options by resolving the state class from the table's model casts and calling its static getStatesLabel() method. Throws errors if the model, attribute, or cast class is invalid.

```php
protected function setUp(): void
{
    parent::setUp();
    $this->options(fn (Table $table) => (new ($table->getModel()))->getCasts()[$this->getAttribute()]::getStatesLabel($table->getModel()));
}
```

--------------------------------

### setUp() method implementation

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-select-column.md

Configures the column: disables placeholder, sets options from the model's cast class, and disables options not in transitionableStates(). Throws Error if the attribute is not a Spatie State or cast lacks getStatesLabel().

```php
protected function setUp(): void
{
    parent::setUp();
    $this->selectablePlaceholder(false);
    $this->options(fn ($model) => (new $model)->getCasts()[$this->getAttribute()]::getStatesLabel($model));
    $this->disableOptionWhen(
        function (string $value, $record, $state) {
            return ($state == $value) ? false : ! in_array($value, $record->{$this->getAttribute()}->transitionableStates());
        }
    );
}
```

--------------------------------

### Retrieving the registered plugin

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/filament-statefusion-plugin.md

Shows how to get the plugin instance with get() and verify its ID.

```php
<?php
use A909M\FilamentStateFusion\FilamentStateFusionPlugin;

$plugin = FilamentStateFusionPlugin::get();
// $plugin->getId() === 'filament-statefusion'
```

--------------------------------

### Customize state UI with HasLabel, HasDescription, HasColor, HasIcon

Source: https://github.com/a909m/filament-statefusion/blob/main/README.md

Implement HasLabel, HasDescription, HasColor, and HasIcon on a concrete state class to customize its UI appearance. The example shows a CancelledState class that returns a localized label, red color, an icon, and a description.

```php
use Filament\Support\Colors\Color;
use Filament\Support\Contracts\HasColor;
use Filament\Support\Contracts\HasDescription;
use Filament\Support\Contracts\HasIcon;
use Filament\Support\Contracts\HasLabel;

final class CancelledState extends OrderState implements HasDescription, HasColor, HasIcon, HasLabel
{
    public function getLabel(): string
    {
        return __('Order Cancelled');
    }

    public function getColor(): array
    {
        return Color::Red;
    }

    public function getIcon(): string
    {
        return 'heroicon-o-x-circle';
    }

    public function getDescription(): ?string
    {
        return 'Order cancelled, transaction reversed.';
    }
}
```

--------------------------------

### Example test using TestsFilamentStateFusion

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/contracts.md

Shows a Pest test that uses the mixin; currently no additional assertion methods are provided.

```php
<?php
// tests/Feature/OrderResourceTest.php

use App\Filament\Resources\OrderResource;
use App\Models\Order;
use function Pest\Livewire\livewire;

it('renders the order resource', function () {
    livewire(OrderResource::class)
        ->assertSuccessful();
    // TestsFilamentStateFusion currently adds no assertion methods;
    // only the standard Livewire/Filament testables are available.
});
```

--------------------------------

### Usage Example: OrderState with StateFusionInfo

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-info.md

Example of an abstract state class implementing HasFilamentStateFusion and using StateFusionInfo, with a config method defining default state and transitions.

```php
<?php
// app/States/OrderState.php

use A909M\FilamentStateFusion\Concerns\StateFusionInfo;
use A909M\FilamentStateFusion\Contracts\HasFilamentStateFusion;
use Spatie\ModelStates\State;
use Spatie\ModelStates\StateConfig;

abstract class OrderState extends State implements HasFilamentStateFusion
{
    use StateFusionInfo;

    public static function config(): StateConfig
    {
        return parent::config()
            ->default(PendingState::class)
            ->allowTransition(PendingState::class, ProcessingState::class)
            ->allowTransition(ProcessingState::class, ShippedState::class);
    }
}
```

--------------------------------

### StateFusionSelectColumn Usage Examples

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-select-column.md

Examples of using the column in a Filament resource table, including basic and advanced usage with explicit attribute and error handling.

```APIDOC
## [PHP] StateFusionSelectColumn Usage Examples

### Description
Shows how to add the column to a Filament table and configure it with common modifiers.

### Basic Usage
```php
use A909M\FilamentStateFusion\Tables\Columns\StateFusionSelectColumn;
use Filament\Tables\Table;

public static function table(Table $table): Table
{
    return $table->columns([
        StateFusionSelectColumn::make('status'),
    ]);
}
```

### Advanced Usage
```php
use A909M\FilamentStateFusion\Tables\Columns\StateFusionSelectColumn;

StateFusionSelectColumn::make('approval_status')
    ->attribute('approval_status')
    ->label('Approval')
    ->sortable();
```

### Error Handling
```php
// Attribute not cast to a Spatie state on the model:
StateFusionSelectColumn::make('status')
    ->attribute('not_a_state_field');
// -> Error at render: call to ->transitionableStates() on a non-State value
```
```

--------------------------------

### Usage examples for HasStateAttributes

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/has-state-attributes.md

Shows default attribute usage, explicit attribute for multi-state models, and dynamic attribute selection with a Closure.

```php
<?php
use A909M\FilamentStateFusion\Forms\Components\StateFusionSelect;
use A909M\FilamentStateFusion\Tables\Columns\StateFusionSelectColumn;

// Default attribute: first key of getDefaultStates()
StateFusionSelect::make('status'),

// Explicit attribute for multi-state models
StateFusionSelect::make('approval_status')
    ->attribute('approval_status'),

// Dynamic attribute selection with a Closure
StateFusionSelectColumn::make('status')
    ->attribute(fn ($record) => $record->uses_legacy_field ? 'legacy_state' : 'state'),
```

--------------------------------

### Error handling example

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-select-column.md

Shows a configuration that triggers an Error at render because the attribute is not cast to a Spatie state, causing a call to transitionableStates() on a non-State value.

```php
<?php
// Attribute not cast to a Spatie state on the model:
StateFusionSelectColumn::make('status')
    ->attribute('not_a_state_field');
// -> Error at render: call to ->transitionableStates() on a non-State value
```

--------------------------------

### Usage example for HasStateAttributesContract

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/has-state-attributes.md

Shows type-hinting the interface to bind a state attribute and retrieve it.

```php
<?php
use A909M\FilamentStateFusion\Contracts\HasStateAttributesContract;

function bindToStateField(HasStateAttributesContract $component): void
{
    $component->attribute('status');
    $name = $component->getAttribute(); // 'status'
}
```

--------------------------------

### setUp() method wiring for StateFusion action

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-action.md

Protected hook that configures the action's label, color, icon, tooltip, visibility, transition logic, form, modal, and confirmation. All closures are lazily evaluated at render/run time. The action() closure transitions the record's state attribute to the target state class, passing the first form data key as payload when data exists, then triggers success notification. Throws Error at evaluation time if transitionTo() was never called or the state attribute is not a Spatie State instance.

```php
protected function setUp(): void
{
    parent::setUp();
    $this->label(fn () => is_a($this->getClassInstance(), HasLabel::class) ? $this->getClassInstance()?->getLabel() : (is_a($this->getToStateClass(), HasLabel::class) ? $this->getToStateClass()?->getLabel() : null));
    $this->color(fn () => is_a($this->getClassInstance(), HasColor::class) ? $this->getClassInstance()?->getColor() : (is_a($this->getToStateClass(), HasColor::class) ? $this->getToStateClass()?->getColor() : null));
    $this->icon(fn () => is_a($this->getClassInstance(), HasIcon::class) ? $this->getClassInstance()?->getIcon() : ((is_a($this->getToStateClass(), HasIcon::class)) ? $this->getToStateClass()?->getIcon() : null));
    $this->tooltip(fn () => is_a($this->getClassInstance(), HasDescription::class) ? $this->getClassInstance()?->getDescription() : (is_a($this->getToState(), HasDescription::class) ? $this->getToState()?->getDescription() : null));
    $this->hidden(
        function ($record) {
            return ! in_array($this->getToState()::getMorphClass(), $record->{$this->getAttribute()}->transitionableStates());
        }
    );
    $this->action(function ($record, array $data): void {
        if (empty($data)) {
            $record->{$this->getAttribute()}->transitionTo($this->getToStateClass());
        } else {
            $record->{$this->getAttribute()}->transitionTo($this->getToStateClass(), $data[array_key_first($data)]);
        }
        $this->success();
    });

    $this->form(fn () => ((method_exists($this->getClassInstance(), 'form')) ? $this->getClassInstance()->form() : null));
    $this->modalDescription(fn () => is_a($this->getClassInstance(), HasDescription::class) ? $this->getClassInstance()->getDescription() : (is_a($this->getToState(), HasDescription::class) ? $this->getToState()->getDescription() : null));
    $this->modalIcon(fn () => $this->getIcon());
    $this->modalIconColor(fn () => $this->getColor());
    $this->requiresConfirmation();
}
```

--------------------------------

### Create StateFusionAction with make()

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-action.md

Instantiates the action using the static make factory inherited from Filament\Actions\Action. The example creates an action named 'approve'.

```php
StateFusionAction::make('approve')
```

--------------------------------

### Class signature for FilamentStateFusionPlugin

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/filament-statefusion-plugin.md

Shows the public API of the plugin class, including getId(), register(), boot(), make(), and get().

```php
class FilamentStateFusionPlugin implements Plugin
{
    public function getId(): string;
    public function register(Panel $panel): void;
    public function boot(Panel $panel): void;
    public static function make(): static;
    public static function get(): static;
}
```

--------------------------------

### Class signature for StateFusionTableAction

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-table-action.md

Shows the class declaration, traits, and protected setUp method for the table action.

```php
class StateFusionTableAction extends Action implements HasStateAttributesContract, HasStateFusionAction
{
    use HasStateAttributes;
    use InteractsWithStateAction;

    protected function setUp(): void;
}
```

--------------------------------

### Error handling examples

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-form-components.md

Shows two error scenarios: when the attribute is not present in the model's casts, the options closure fails with an ErrorException or 'Undefined array key'; and when the cast class does not define getStatesLabel(), resolution fails with a 'Call to undefined method' error.

```php
<?php
// If the attribute is not present in the model's casts, the options closure
// fails when the form renders:
StateFusionSelect::make('status')
    ->attribute('nonexistent_field'),
// -> ErrorException / "Undefined array key" when the options closure evaluates.

// If the cast class does not define getStatesLabel(), resolution fails:
// -> Error: Call to undefined method App\States\PlainState::getStatesLabel()
```

--------------------------------

### Class signature of StateFusionAction

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-action.md

Shows the class declaration, traits, and the protected setUp method. Used to understand the structure of the action.

```php
class StateFusionAction extends Action implements HasStateAttributesContract, HasStateFusionAction
{
    use HasStateAttributes;
    use InteractsWithStateAction;

    protected function setUp(): void;
}
```

--------------------------------

### get() static method

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/filament-statefusion-plugin.md

Retrieves the plugin instance already registered on the current Filament panel using the global filament() helper. Throws if the plugin is not registered.

```php
public static function get(): static
{
    /** @var static $plugin */
    $plugin = filament(app(static::class)->getId());

    return $plugin;
}
```

--------------------------------

### Calling the Accessors Directly

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-info.md

Shows how to call getStatesLabel and getStatesColor directly on the state class, with example return values.

```php
<?php
$labels = OrderState::getStatesLabel($order);   // ['pending' => 'Pending', 'processing' => 'Processing', ...]
$colors = OrderState::getStatesColor($order);   // ['pending' => [...Color::Red...], ...] or null
```

--------------------------------

### Custom attribute selection with attribute()

Source: https://github.com/a909m/filament-statefusion/blob/main/README.md

Use the attribute() method to specify which model attribute the state component should use. The first example sets a custom attribute name, while the second dynamically selects the 'state' attribute and transitions to ApprovedState.

```php
// Using a different attribute name
StateFusionSelect::make('approval_status')
    ->attribute('approval_status'),

// Dynamic attribute selection
StateFusionAction::make('transition')
    ->attribute('state')
    ->transitionTo(ApprovedState::class),
```

--------------------------------

### get(): static (static)

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/filament-statefusion-plugin.md

Retrieves the plugin instance already registered on the current Filament panel using the global filament() helper. Throws if the plugin is not registered.

```APIDOC
## get(): static (static)

### Description
Retrieves the plugin instance already registered on the current Filament panel using the global filament() helper. Throws if the plugin is not registered.

### Method
get

### Return Type
static

### Return Value
- **instance** (static) - The plugin instance registered on the current panel.

### Throws
If the plugin has not been registered on the panel, the filament() lookup fails (Filament's panel registry behavior). No custom exception is defined.

### Example
```php
$plugin = FilamentStateFusionPlugin::get();
// $plugin->getId() === 'filament-statefusion'
```
```

--------------------------------

### Class signature for StateFusionSelectColumn

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-select-column.md

Declares the column class extending SelectColumn and implementing HasStateAttributesContract, using the HasStateAttributes trait. The setUp() method is protected and overridden.

```php
class StateFusionSelectColumn extends SelectColumn implements HasStateAttributesContract
{
    use HasStateAttributes;

    protected function setUp(): void;
}
```

--------------------------------

### Common data source pattern for resolving state class from model casts

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-form-components.md

All four setUp() hooks resolve the state class from the model's casts using this expression. It expects a live model bound to the form, the resolved attribute name, the model's getCasts() to contain that attribute mapped to a Spatie state class name, and that state class to implement HasFilamentStateFusion or define the static getStatesLabel()/getStatesDescription()/getStatesIcon()/getStatesColor() methods.

```php
(new $model)->getCasts()[$this->getAttribute()]::getStatesLabel($model)
```

--------------------------------

### Error handling: unconfigured action

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-action.md

Forgetting ->transitionTo() yields a runtime Error when Filament evaluates the action (either at render time in the hidden() closure, or on trigger). The example shows the unconfigured action and an equivalent manual failure with try/catch.

```php
<?php
use A909M\FilamentStateFusion\Actions\StateFusionAction;

// Forgetting ->transitionTo() yields a runtime Error when Filament evaluates
// the action (either at render time in the hidden() closure, or on trigger):
StateFusionAction::make('approve'); // never configured

// Equivalent failure when evaluated manually:
try {
    $record->status->transitionTo($action->getToStateClass());
} catch (\Error $e) {
    // "Class ... not found" / null instantiation error
}
```

--------------------------------

### StateFusionRadio::setUp() - src/Forms/Components/StateFusionRadio.php:13

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-form-components.md

Sets options and per-option descriptions from getStatesDescription(). Description values may be null when the state class lacks getDescription().

```php
protected function setUp(): void
{
    parent::setUp();
    $this->options(fn ($model) => (new $model)->getCasts()[$this->getAttribute()]::getStatesLabel($model));
    $this->descriptions(fn ($model) => (new $model)->getCasts()[$this->getAttribute()]::getStatesDescription($model));
}
```

--------------------------------

### boot() method

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/filament-statefusion-plugin.md

Empty method that performs no boot actions.

```php
public function boot(Panel $panel): void
{
    //
}
```

--------------------------------

### getId() method

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/filament-statefusion-plugin.md

Returns the plugin identifier 'filament-statefusion', used as the registration key and argument to filament() in get().

```php
public function getId(): string
{
    return 'filament-statefusion';
}
```

--------------------------------

### getClassInstance(): string | State | Transition

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/interacts-with-state-action.md

Returns the instance used to resolve label/color/icon/description and the transition form. Uses a custom transition class if available, otherwise the target state instance.

```APIDOC
## getClassInstance(): string | State | Transition

### Description
Returns the instance used to resolve label/color/icon/description and the transition form. Uses a custom transition class if available, otherwise the target state instance.

### Method
PHP Method

### Endpoint
`getClassInstance(): string | State | Transition`

### Return
- **string | State | Transition** - the instance the package uses to resolve label/color/icon/description and the transition `form()`:
  - when a custom transition class exists: `new $transitionClass(new $model())` — note the model is **freshly instantiated** with `new ($this->getModel())()`, not the current record;
  - otherwise: the target state instance from `getToStateClass()`.

### Throws
- `Error` — if `getTransitionClass()` returns null while `hasTransitionClass()` is true (impossible by construction) or if either constructor argument contract is violated.
```

--------------------------------

### boot(Panel $panel): void

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/filament-statefusion-plugin.md

Boots the plugin with a Filament panel. This method is empty and performs no actions.

```APIDOC
## boot(Panel $panel): void

### Description
Boots the plugin with a Filament panel. This method is empty and performs no actions.

### Method
boot

### Parameters
- **$panel** (Panel) - Required - The Filament panel being booted.

### Return Type
void

### Behavior
Empty.
```

--------------------------------

### StateFusionTableAction::setUp()

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-table-action.md

Protected method that configures the action's default behavior: label, color, icon, tooltip, visibility, action logic, form, modal settings, and confirmation requirement. Called automatically during Filament's action initialization.

```APIDOC
## [METHOD] StateFusionTableAction::setUp()

### Description
Protected method that configures the action's default behavior: label, color, icon, tooltip, visibility, action logic, form, modal settings, and confirmation requirement. Called automatically during Filament's action initialization.

### Method
Protected method

### Signature
```php
protected function setUp(): void
```

### Behavior
- **Label** - Resolved from the class instance if it implements `HasLabel`, else from the target state class if it implements `HasLabel`, else `null`.
- **Color** - Resolved from the class instance if it implements `HasColor`, else from the target state class if it implements `HasColor`, else `null`.
- **Icon** - Resolved from the class instance if it implements `HasIcon`, else from the target state class if it implements `HasIcon`, else `null`.
- **Tooltip** - Resolved from the class instance if it implements `HasDescription`, else from the target state if it implements `HasDescription`.
- **Hidden** - The action is hidden for a record whose current state's `transitionableStates()` does not contain the target state's morph class.
- **Action** - Runs `$record->{attribute}->transitionTo($toStateClass)` or, when custom form data is provided, `transitionTo($toStateClass, $data[array_key_first($data)])`, then fires success notification.
- **Form** - Exposes the custom transition's `form()` fields in the confirmation modal.
- **Modal Description** - From the class instance if it implements `HasDescription`, else from the target state if it implements `HasDescription`.
- **Modal Icon** - Set to the action's icon.
- **Modal Icon Color** - Set to the action's color.
- **Confirmation** - Always requires confirmation.

### Return Value
Void
```

--------------------------------

### Customize transition UI with HasLabel, HasColor, HasIcon

Source: https://github.com/a909m/filament-statefusion/blob/main/README.md

Customize a transition class by implementing HasLabel, HasColor, and HasIcon. The ToCancelled transition returns a localized label, red color, and an icon for the UI.

```php
use Filament\Support\Colors\Color;
use Filament\Support\Contracts\HasColor;
use Filament\Support\Contracts\HasIcon;
use Filament\Support\Contracts\HasLabel;
use Spatie\ModelStates\Transition;

final class ToCancelled extends Transition implements HasLabel, HasColor, HasIcon
{
    public function getLabel(): string
    {
        return __('Mark as Cancelled');
    }

    public function getColor(): array
    {
        return Color::Red;
    }

    public function getIcon(): string
    {
        return 'heroicon-o-x-circle';
    }
}
```

--------------------------------

### Prepare State Class with HasFilamentStateFusion

Source: https://github.com/a909m/filament-statefusion/blob/main/README.md

Define the abstract state class for an order, implementing the HasFilamentStateFusion interface and using the StateFusionInfo trait. Configure default state and allowed transitions using Spatie's StateConfig.

```php
<?php
// app/States/OrderState.php
use A909M\FilamentStateFusion\Concerns\StateFusionInfo;
use A909M\FilamentStateFusion\Contracts\HasFilamentStateFusion;
use Spatie\ModelStates\State;
use Spatie\ModelStates\StateConfig;

abstract class OrderState extends State implements HasFilamentStateFusion
{
    use StateFusionInfo;

    public static function config(): StateConfig
    {
        return parent::config()
            ->default(PendingState::class)
            ->allowTransition(PendingState::class, ProcessingState::class)
            ->allowTransition(ProcessingState::class, ShippedState::class)
            ->allowTransition(ShippedState::class, DeliveredState::class)
            ->allowTransition([PendingState::class, ProcessingState::class], CancelledState::class);
    }
}

```

--------------------------------

### transitionTo(string | State | null $toState): static

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/interacts-with-state-action.md

Sets the target state for the action. Accepts a Spatie state class name or instance, or null to clear the target. Returns the action instance for chaining.

```APIDOC
## transitionTo(string | State | null $toState): static

### Description
Sets the target state for the action. Accepts a Spatie state class name or instance, or null to clear the target. Returns the action instance for chaining.

### Method
PHP Method

### Endpoint
`transitionTo(string | State | null $toState): static`

### Parameters
#### Method Parameters
- **$toState** (string | State | null) - Required - target Spatie state class name or instance; `null` clears the target

### Return
- **static** - the action, for chaining.

### Notes
- `StateFusionBulkAction` overrides the "from" side with its own `transition()` method but reuses this `transitionTo()` implementation for the "to" side.
```

--------------------------------

### Basic usage of StateFusionTableAction::make with transitionTo

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/interacts-with-state-action.md

Creates a table action that transitions to the ApprovedState. Use this as the primary way to define a state-fusion action in a Filament table.

```php
<?php
use A909M\FilamentStateFusion\Tables\Actions\StateFusionTableAction;

StateFusionTableAction::make('approve')
    ->transitionTo(ApprovedState::class);
```

--------------------------------

### transition() method

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-bulk-action.md

Sets the from and to states for the bulk action. This is the only supported configuration method for bulk transitions; transitionTo() from the trait also works for the 'to' side but leaves fromState null.

```php
public function transition(string | State | null $fromState, string | State | null $toState): self
{
    $this->toState = $toState;
    $this->fromState = $fromState;

    return $this;
}
```

--------------------------------

### Class signature for StateFusionSelectFilter

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-select-filter.md

Declares the filter class extending SelectFilter and implementing HasStateAttributesContract, using the HasStateAttributes trait. The protected setUp() method is overridden.

```php
class StateFusionSelectFilter extends SelectFilter implements HasStateAttributesContract
{
    use HasStateAttributes;

    protected function setUp(): void;
}
```

--------------------------------

### StateFusionSelect::setUp() - src/Forms/Components/StateFusionSelect.php:13

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-form-components.md

Sets options keyed by morph class, valued by getStatesLabel() (label or morph class fallback). No icons, colors, or descriptions are configured.

```php
protected function setUp(): void
{
    parent::setUp();
    $this->options(fn ($model) => (new $model)->getCasts()[$this->getAttribute()]::getStatesLabel($model));
}
```

--------------------------------

### transitionTo method

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/interacts-with-state-action.md

Sets the target state for the action. Accepts a Spatie state class name or instance, or null to clear the target. Returns the action for chaining. Note: StateFusionBulkAction overrides the 'from' side but reuses this implementation for the 'to' side.

```php
public function transitionTo(string | State | null $toState): static
{
    $this->toState = $toState;

    return $this;
}
```

--------------------------------

### getClassInstance method

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/interacts-with-state-action.md

Returns the instance used to resolve label/color/icon/description and the transition form(). When a custom transition class exists, it instantiates new $transitionClass(new $model()) with a freshly instantiated model; otherwise returns the target state instance from getToStateClass(). Throws Error if getTransitionClass() returns null while hasTransitionClass() is true or if constructor contracts are violated.

```php
public function getClassInstance(): string | State | Transition
{
    return $this->evaluate($this->hasTransitionClass() ? (new ($this->getTransitionClass())((new ($this->getModel())()))) : $this->getToStateClass());
}
```

--------------------------------

### Use TextEntry with badge for state display in infolists

Source: https://github.com/a909m/filament-statefusion/blob/main/README.md

Display the model state as a badge in infolists using the standard TextEntry. When the state classes implement HasLabel, HasColor, and HasIcon interfaces, the badge automatically shows the appropriate label, color, and icon without additional configuration.

```php
use Filament\Infolists\Components\TextEntry;

TextEntry::make('status')
    ->badge(),
```

--------------------------------

### Run tests with composer test

Source: https://github.com/a909m/filament-statefusion/blob/main/README.md

Runs the project's test suite via Composer. Use this command to execute all tests defined in the composer.json scripts.

```bash
composer test
```

--------------------------------

### StateFusionSelectColumn::setUp()

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-select-column.md

Protected lifecycle hook that configures the column's placeholder, options, and option disabling logic. It is called automatically by Filament and should not be invoked directly.

```APIDOC
## [PHP] StateFusionSelectColumn::setUp()

### Description
Protected lifecycle hook that configures the column's placeholder, options, and option disabling logic. It is called automatically by Filament and should not be invoked directly.

### Method
Protected method (lifecycle hook)

### Signature
```php
protected function setUp(): void
```

### Behavior
- Calls `parent::setUp()`.
- Disables the selectable placeholder (`selectablePlaceholder(false)`).
- Sets options from the model's cast class `getStatesLabel()` for the column's attribute.
- Disables options that are not reachable from the current state, except the current state itself.

### Throws
- `Error` when the record's attribute is not a Spatie `State` instance or the cast class lacks `getStatesLabel()`.
```

--------------------------------

### Custom transition with form() for collecting data

Source: https://github.com/a909m/filament-statefusion/blob/main/README.md

Create a custom transition class with a form() method to collect additional data. The CancelOrder transition uses a Textarea for a cancellation reason, passes the form data to the handle() method, and updates the model with the reason and timestamp.

```php
<?php

use Filament\Forms\Components\Textarea;
use Filament\Support\Colors\Color;
use Filament\Support\Contracts\{HasLabel, HasColor, HasIcon};
use Spatie\ModelStates\Transition;

final class CancelOrder extends Transition implements HasLabel, HasColor, HasIcon
{
    public function __construct(
        private Order $order,
        private ?array $data = null
    ) {}

    public function handle(): Order
    {
        $this->order->state = new CancelledState($this->order);
        $this->order->cancellation_reason = $this->data['reason'];
        $this->order->cancelled_at = now();
        $this->order->save();

        return $this->order;
    }

    public function form(): array
    {
        return [
            Textarea::make('reason')
                ->label('Cancellation Reason')
                ->placeholder('Why are you cancelling this order?')
                ->required()
                ->maxLength(500),
        ];
    }

    public function getLabel(): string
    {
        return 'Cancel Order';
    }

    public function getColor(): string | array
    {
        return Color::Red;
    }

    public function getIcon(): string
    {
        return 'heroicon-o-x-circle';
    }
}
```

--------------------------------

### packageBooted method implementation

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/filament-statefusion-service-provider.md

Mixes TestsFilamentStateFusion into Testable for testing support.

```php
public function packageBooted(): void
{
    // Testing
    Testable::mixin(new TestsFilamentStateFusion);
}
```

--------------------------------

### Advanced usage with explicit attribute and Filament options

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-form-components.md

Demonstrates using the ->attribute() method to select a different attribute than the default, and applying standard Filament modifiers like ->inline() and ->disabled() to StateFusionToggleButtons. The first example sets a default value using a state class morph class.

```php
<?php
// Multi-state model — select a different attribute than the default
StateFusionSelect::make('approval_status')
    ->attribute('approval_status')
    ->required()
    ->default(fn () => PendingState::getMorphClass()),

// ToggleButtons accepts all standard Filament modifiers on top of the
// auto-populated options/icons/colors:
StateFusionToggleButtons::make('status')
    ->inline()
    ->disabled(fn (string $operation): bool => $operation === 'view'),
```

--------------------------------

### StateFusionTableAction::make()

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/interacts-with-state-action.md

Creates a new StateFusionTableAction instance. This is the entry point for defining a table action that transitions a record to a specific state.

```APIDOC
## StateFusionTableAction::make()

### Description
Creates a new StateFusionTableAction instance. This is the entry point for defining a table action that transitions a record to a specific state.

### Method
`make` (static)

### Parameters
- **name** (string) - Required - The name of the action.

### Return Value
- **StateFusionTableAction** - A new action instance.

### Example
```php
StateFusionTableAction::make('approve')
```
```

--------------------------------

### transition(string | State | null $fromState, string | State | null $toState): self

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-bulk-action.md

Sets the source and target states for the bulk transition action. This is the only supported configuration method for bulk transitions; it returns the action instance for chaining.

```APIDOC
## transition(string | State | null $fromState, string | State | null $toState): self

### Description
Sets the source and target states for the bulk transition action. This is the only supported configuration method for bulk transitions; it returns the action instance for chaining.

### Method
PHP Method

### Endpoint
`transition(string | State | null $fromState, string | State | null $toState): self`

### Parameters
#### Path Parameters
- `$fromState` (string | State | null) - Required - the state selected records must currently be in
- `$toState` (string | State | null) - Required - the target state to transition into

### Return
- `self` - the action, for chaining.

### Behavior
Sets both `$toState` (trait property) and `$fromState` (class property). This is the only supported configuration method for bulk transitions; `transitionTo()` from the trait also works for the "to" side but leaves `fromState` null.
```

--------------------------------

### getTransitionClass method

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/interacts-with-state-action.md

Returns the class name of the custom Spatie Transition registered for the from→to pair, or null when the state config resolves none. Throws Error if getFromState() or getToState() is null, or if getFromState() is not a State instance.

```php
public function getTransitionClass(): ?string
{
    return $this->evaluate($this->getFromState()::config()->resolveTransitionClass($this->getFromState()::getMorphClass(), $this->getToState()::getMorphClass()));
}
```

--------------------------------

### register() method

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/filament-statefusion-plugin.md

Empty method that registers nothing on the panel.

```php
public function register(Panel $panel): void
{
    //
}
```

--------------------------------

### StateFusionToggleButtons::setUp() - src/Forms/Components/StateFusionToggleButtons.php:13

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-form-components.md

Sets options, per-option icons from getStatesIcon(), and per-option colors from getStatesColor() (Filament color arrays, e.g. Color::Red).

```php
protected function setUp(): void
{
    parent::setUp();
    $this->options(fn ($model) => (new $model)->getCasts()[$this->getAttribute()]::getStatesLabel($model));
    $this->icons(fn ($model) => (new $model)->getCasts()[$this->getAttribute()]::getStatesIcon($model));
    $this->colors(fn ($model) => (new $model)->getCasts()[$this->getAttribute()]::getStatesColor($model));
}
```

--------------------------------

### Use StateFusionAction for page actions

Source: https://github.com/a909m/filament-statefusion/blob/main/README.md

Create an action to transition between states from a page. The action is named 'approve' and transitions to the ApprovedState class.

```php
use A909M\FilamentStateFusion\Actions\StateFusionAction;

StateFusionAction::make('approve')
    ->transitionTo(ApprovedState::class),
```

--------------------------------

### getToStateClass method

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/interacts-with-state-action.md

Returns a state instance (or its class name if evaluated oddly) constructed as new $toState($model). Throws Error when getToState() is null or when the state class constructor rejects the model argument.

```php
public function getToStateClass(): string | State
{
    return $this->evaluate(new ($this->getToState())($this->getModel()));
}
```

--------------------------------

### packageRegistered method implementation

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/filament-statefusion-service-provider.md

Empty hook; nothing is bound into the container here.

```php
public function packageRegistered(): void {}
```

--------------------------------

### Basic usage of StateFusion form components

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-form-components.md

Shows how to use StateFusionSelect, StateFusionRadio, StateFusionToggleButtons, and StateFusionCheckboxList in a Filament form schema. Each component is created with the make() method and the field name 'status'.

```php
<?php
// app/Filament/Resources/OrderResource.php

use A909M\FilamentStateFusion\Forms\Components\StateFusionCheckboxList;
use A909M\FilamentStateFusion\Forms\Components\StateFusionRadio;
use A909M\FilamentStateFusion\Forms\Components\StateFusionSelect;
use A909M\FilamentStateFusion\Forms\Components\StateFusionToggleButtons;
use Filament\Forms\Form;

public static function form(Form $form): Form
{
    return $form
        ->schema([
            // Dropdown select
            StateFusionSelect::make('status'),

            // Radio buttons with descriptions
            StateFusionRadio::make('status'),

            // Toggle buttons with colors and icons
            StateFusionToggleButtons::make('status'),

            // Checkbox list with descriptions
            StateFusionCheckboxList::make('status'),
        ]);
}
```

--------------------------------

### Use StateFusionBulkAction for bulk state transitions

Source: https://github.com/a909m/filament-statefusion/blob/main/README.md

Transition multiple records at once using the StateFusionBulkAction. The action is named 'approve' and transitions from PendingState to ApprovedState.

```php
use A909M\FilamentStateFusion\Tables\Actions\StateFusionBulkAction;

StateFusionBulkAction::make('approve')
    ->transition(PendingState::class,ApprovedState::class),
```

--------------------------------

### Advanced: reading resolved pieces from StateFusionTableAction

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/interacts-with-state-action.md

Shows how to retrieve the resolved state class, instance, and transition details after configuring the action. The getToState() returns the class string, getToStateClass() returns a new state instance, hasTransitionClass() indicates a custom Transition, and getClassInstance() returns the Transition or state instance.

```php
<?php
$action = StateFusionTableAction::make('ship')
    ->transitionTo(ShippedState::class);

$toState   = $action->getToState();          // ShippedState::class (string)
$toClass   = $action->getToStateClass();     // new ShippedState($model) instance
$hasCustom = $action->hasTransitionClass();  // true if a custom Transition is configured
$instance  = $action->getClassInstance();    // Transition instance, or the ShippedState instance
```

--------------------------------

### transition(string | State | null $fromState, string | State | null $toState): self

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/state-fusion-bulk-action.md

Configures the source and target states for the bulk action. This method must be called to set both the fromState and toState before the action can transition selected records.

```APIDOC
## transition(string | State | null $fromState, string | State | null $toState): self

### Description
Configures the source and target states for the bulk action. This method must be called to set both the fromState and toState before the action can transition selected records.

### Method
N/A (PHP method)

### Endpoint
N/A

### Parameters
- **$fromState** (string | State | null) - Required - The source state (class name string or State instance) that records must currently be in.
- **$toState** (string | State | null) - Required - The target state to transition records to.

### Return Value
- **self** - Returns the current action instance for chaining.

### Example
```php
$action->transition('draft', 'published');
```
```

--------------------------------

### Registering TestsFilamentStateFusion mixin

Source: https://github.com/a909m/filament-statefusion/blob/main/_autodocs/api-reference/contracts.md

Applied in FilamentStateFusionServiceProvider::packageBooted() to extend Livewire's Testable class.

```php
Testable::mixin(new TestsFilamentStateFusion);
```
Tokens:
Raw