Sharp

# Entity States

Entity states are a little 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", static::GRAY_COLOR)
        ->addState("conception", "Conception phase", static::DARKGRAY_COLOR);
}

$this->addState() take 3 parameters:

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

For the color, you may indicate:

  • an HTML color name (opens new window)
  • a Sharp constant, from its UI: PRIMARY_COLOR, SECONDARY_COLOR, GRAY_COLOR, LIGHTGRAY_COLOR, DARKGRAY_COLOR
  • or an hexadecimal value, starting with #.

# Update a state

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

public function updateState($instanceId, $stateId)
{
    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 omited 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()
{
    $this->setEntityState("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 == sharp_user()->id;
}

← Reordering instances →