Entity States

Entity states are a bit of sugar to easily propose a state management on entities. It could be a simple "draft / publish" state for a page, or something more advanced for an order, for instance.

Generator

php artisan sharp:make:entity-state <class_name> [--model=<model_name>]

Write the Entity state class

First, you'll have to write a class that extends the Code16\Sharp\EntityList\Commands\EntityState abstract class.

You'll have to implement two functions: buildStates() and updateState($instanceId, $stateId).

Build the states

The goal is to declare the available states for the entity, using $this->addState():

protected function buildStates()
{
    $this->addState("active", "Active", "green")
        ->addState("inactive", "Retired", "orange")
        ->addState("building", "Building process", "#dddddd")
        ->addState("conception", "Conception phase", "blue");
}

$this->addState() takes 3 parameters:

• first, a key identifying the state,
• then, the state label as shown to the user,
• and finally a color to display.

For the color, you may indicate anything that the browser would understand (an HTML color name or a hexadecimal value).

Update a state

When the user clicks on a state to update it, this is the functional code called.

public function updateState($instanceId, $stateId): array
{
    Spaceship::findOrFail($instanceId)
        ->update([
            "state" => $stateId
        ]);

    return $this->refresh($instanceId);
}

Note the return $this->refresh($instanceId);: Entity states can return either a refresh or a reload (as described in the previous chapter, Commands), but if omitted the refresh of the $instanceId is the default (meaning in the code sample above this line can be deleted).

Configure the state

Once the Entity state class is defined, we have to add it in the Entity List config:

function buildListConfig(): void
{
    $this->configureEntityState("state", SpaceshipEntityState::class)
}

The first parameter is a key which should be the name of the attribute.

Authorizations

Entity states can declare an authorization check very much like Instance Commands:

public function authorizeFor($instanceId): bool 
{
    return Spaceship::findOrFail($instanceId)->owner_id == auth()->id();
}