README

Automatically records all Enumata transitions.

Description

This package allow you to automatically record logs of all states a model with Enumata may have and query this logs to take specific actions accordingly.

Installation

Install the package via Composer:

composer require norotaro/enumata-recorder

Then run the migrations:

php artisan migrate

Configuration

In a model configured to use Enumata (see documentation) we only need to add the LogTransitions trait:

use Norotaro\Enumata\Traits\HasStateMachines;
use Norotaro\EnumataRecorder\Traits\LogTransitions;

class Order extends Model
{
    use HasStateMachines, LogTransitions;

    protected $casts = [
        'status' => OrderStatus::class,
    ];
}

That's it. Now all transitions will be recorded automatically using the enumata_state_logs table that was created when installing the package.

Querying Logs

Get full history of transitioned states:

$order->stateLogs;

// or

$order->stateLogs()->get();

The stateLogs() method returns an Eloquent relationship that can be chained as any Query Builder to further down the results. You also have some scopes available.

$order->stateLogs()
    ->fromState(OrderStatus::Pending)
    ->toState(OrderStatus::Approved)
    ->where('created_at', '<', Carbon::yesterday())
    ->get();

Scopes

fromState($state)

$order->stateLogs()->fromState(OrderStatus::Pending)->get();

toState($state)

$order->stateLogs()->toState(OrderStatus::Approved)->get();

forField($field)

This is util if you have more that one field that use states.

For example, having this model:

use Norotaro\Enumata\Traits\HasStateMachines;
use Norotaro\EnumataRecorder\Traits\LogTransitions;

class Order extends Model
{
    use HasStateMachines, LogTransitions;

    protected $casts = [
        'status'      => OrderStatus::class,
        'fulfillment' => OrderFulfillment::class,
    ];
}

We can access the logs for each field in this way:

$order->stateLogs()->forField('status')->get();

$order->stateLogs()->forField('fulfillment')->get();

Alternatively we can pass a param to stateLogs() with the name of the field to get the same result:

$order->stateLogs('status')->get();

$order->stateLogs('fulfillment')->get();

Testing

To run the test suite:

composer run test

Inspiration

This package was inspired by asantibanez/laravel-eloquent-state-machines.

LICENSE

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