Actions

An action is an operation beyond create, update and delete: publish, reprice, escalate. It is a class extending VectorAction, listed in its resource’s actions().

use Kinetis\Vector\Actions\{ActionRequest, ActionResponse, VectorAction};

final class AdjustStock extends VectorAction
{
    public function fields(): array
    {
        return [Number::make('delta', 'Change by')->required()];
    }

    public function canRun(CurrentUserInterface $user, ?array $record): bool
    {
        return $record === null || $record['status'] !== 'archived';
    }

    public function handle(ActionRequest $request): ActionResponse
    {
        foreach ($request->entities() as $product) {
            if (!$product->adjustStock($request->field('delta'))) {
                return ActionResponse::danger('Stock cannot go below zero.'); // nothing is saved
            }
        }

        return ActionResponse::message("{$request->count()} adjusted.");
    }
}

fields() become the action’s dialog, validated like a form, with conditions and defaults; an action’s fields are scalar, enum and belongs-to fields. canRun() decides whether the action is offered ($record is null) and whether it may run on a given record. The action’s URL segment is name(): by default the class name without Action, in kebab-case (PublishAction is publish). The constructor may inject what a controller may.

How it runs

For every run, Vector:

  1. checks the resource policy’s viewAny() and runAction(), and canRun() without a record;

  2. validates the dialog’s values;

  3. reads each selected record as the user may view it and refuses the run when canRun() refuses one;

  4. loads the entities and hands them to handle();

  5. saves everything in one flush, unless the response is danger;

  6. logs the run in vector_action_events and adds an entry naming the action to each record’s audit trail.

An action runs on one record, on the selected records, or on every record a filter matches (“all matching”), within the resource’s bulk limit.

Shaping the action

Method

Effect

label(), icon()

How it is named and shown.

confirmation()

A question asked before it runs.

destructive()

Shown and confirmed as dangerous.

standalone()

Runs on no records, from the list’s toolbar.

showOnIndex(), showOnDetail()

Where it is offered.

queued(), chunkSize()

Runs as a background job, in chunks; see Background jobs.

Responses

Response

The user sees

ActionResponse::message()

A confirmation.

ActionResponse::danger()

An error; nothing is saved (422).

ActionResponse::redirect()

The admin navigates to a page.

ActionResponse::openUrl()

A URL opens.

ActionResponse::download()

A file downloads.

queued

A job to follow on Jobs.

A queued action runs in chunks; Background jobs covers how it is delivered and what it must tolerate.

See also