dimonka2/flatstate

Model states manager with simplified state declaration for Laravel

dev-master 2024-06-18 13:32 UTC

Requires

• php: ^7 | ^8
• composer/composer: ^2
• laravel/framework: ^7 | ^8 | ^9 | ^10 | ^11.0

MIT

• Dmitry Gultyaev

• php
• state
• helper
• laravel

README

Simple model state management package for Laravel. This package allows you to define and store model states in a state model with caching and updating.

Features

• Define states for your Eloquent models
• Store and manage states in a separate state model
• Cache and update states efficiently
• Integration with Blade for easy state formatting
• Facade for easy state management

Installation

1. Install the package via Composer:

composer require dimonka2/flatstate

1. Publish the configuration and migration files:

php artisan vendor:publish --provider="dimonka2\flatstate\FlatstateServiceProvider"

1. Run the migrations:

php artisan migrate

Usage

Adding States to a Model

To add states to a model, use the Stateable trait. Define the states in the model's $states property:

use dimonka2\flatstate\Traits\Stateable;

class Project extends Model
{
    use Stateable;

    protected $states = [
        'state_id' => [
            'type' => 'projects',
            'default' => 'pr_active',
            ['name' => 'Active', 'key' => 'pr_active', 'descriptions' => '..', 'icon' => 'fa fa-info', 'color' => 'danger'],
        ],
    ];
}

Accessing and Formatting States

You can access and format states using the methods provided by the Stateable trait:

$project = Project::find(1);

// Get the state key
$stateKey = $project->getState('state_id');

// Format the state with an icon
$formattedState = $project->formatStateState(true);

Blade Integration

You can use the state directive in Blade templates to format states:

@state($project->state_id)

State Service Manager

The State Service Manager class provides various methods to interact with the states. It is available via the Flatstate facade.

Retrieving States

use dimonka2\flatstate\Flatstate;

// Get state by key
$state = Flatstate::getState('pr_active');

// Get several states by key as array
$state = Flatstate::getState(['pr_active', 'pr_suspended']);

// Get state key by ID
$stateKey = Flatstate::getStateKey(1);

// Get state icon by ID
$stateIcon = Flatstate::getStateIcon(1);

// Get a list of states by type
$stateList = Flatstate::getStateList('projects');

Managing Cache

You can clear the state cache using the clearCache method:

Flatstate::clearCache();

Formatting States

You can format states using the formatState method:

$formattedState = Flatstate::formatState($state, true);

Commands

The package provides several Artisan commands:

• php artisan flatstate:list - List all defined states
• php artisan flatstate:seed - Seed the states into the database
• php artisan flatstate:generate - Generate TypeScript definitions for the states

List Available States

The flatstate:list command allows you to list available state categories or the states within a specific category.

• To list all state categories and the count of states in each category, run:

php artisan flatstate:list

• To list all states within a specific category, specify the category as an argument:

php artisan flatstate:list {category}

Example usage:

php artisan flatstate:list projects

This will output a table with the state details such as state_type, state_key, name, and other fillable fields.

Seeding States

The flatstate:seed command allows you to seed the states defined in your models into the database.

php artisan flatstate:seed

This command processes the states defined in your models and saves them to the database. It looks for models that use the Stateable trait and reads their $states property to determine which states to seed.

You can also specify a single model class to seed:

php artisan flatstate:seed {class?}

Generate TypeScript Definitions

The flatstate:generate command generates a TypeScript list of all states or states within a specific category. This is useful for maintaining type safety and consistency in your front-end code.

Usage

php artisan flatstate:generate {category?}

Example

To generate TypeScript definitions for all states:

php artisan flatstate:generate

To generate TypeScript definitions for a specific category, pass the category as an argument:

php artisan flatstate:generate projects

This will output a TypeScript file with all the state definitions, which you can then use in your front-end code.

Configuration

The configuration file flatstate.php will be published to your application's config directory. You can customize the settings as needed.

License

This package is open-sourced software licensed under the MIT license.