Skip to content
workflows / 1

Custom actions

Last updated:

On this page

Write an action for anything your workflows do by themselves: create an invoice, book a room, post to another system.

namespace App\Workflows\Actions;

use App\Models\Invoice;
use Javaabu\Workflows\Actions\Action;
use Javaabu\Workflows\Actions\ActionContext;

class CreateInvoiceAction extends Action
{
    public static function key(): string
    {
        return 'create_invoice';
    }

    public function name(): string
    {
        return __('Create an invoice');
    }

    public function description(): ?string
    {
        return __('Bill the applicant for the fee.');
    }

    public function icon(): string
    {
        return 'receipt';
    }

    /** The builder's inputs: text, textarea, select, checkboxes, key_value or assignees */
    public function settingsFields(): array
    {
        return [
            'amount' => ['type' => 'text', 'label' => __('Amount'), 'help' => __('A number, or {{ fee }}'), 'required' => true],
            'currency' => ['type' => 'select', 'label' => __('Currency'), 'options' => ['MVR' => 'MVR', 'USD' => 'USD']],
        ];
    }

    public function settingsRules(): array
    {
        return [
            'amount' => ['required'],
            'currency' => ['nullable', 'in:MVR,USD'],
        ];
    }

    public function handle(ActionContext $context): void
    {
        Invoice::create([
            'billable_type' => $context->instance->subject_type,
            'billable_id' => $context->instance->subject_id,
            'amount' => $context->interpolate($context->setting('amount')),
            'currency' => $context->setting('currency', 'MVR'),
        ]);
    }

    /** What the tester shows instead of running it */
    public function describe(ActionContext $context): string
    {
        return __('Invoice :amount', ['amount' => $context->interpolate($context->setting('amount'))]);
    }
}

Register it:

// config/workflows.php
'actions' => [
    ...
    App\Workflows\Actions\CreateInvoiceAction::class,
],

// or in a service provider's boot()
Workflows::registerAction(CreateInvoiceAction::class);

registerAction() replaces an action with the same key, so you can swap a built-in one for a subclass. forgetAction('webhook') removes one from the builder and the validator.

The context

$context->instance the WorkflowInstance
$context->call the ActionCall: getAction(), getSettings()
$context->step, $context->transition the step key (and the transition key, for a transition's actions)
$context->actor who caused it, or null
$context->simulated true in the tester
setting($key, $default), settings() the settings, with dots
subject(), data($key), value('subject.amount') what conditions read
interpolate($value) fills {{ placeholders }} in a string or an array

Queued actions

Implement Illuminate\Contracts\Queue\ShouldQueue and the action runs as a job after the start or transition is saved.

The tester

simulate(ActionContext $context) runs instead of handle() in the tester. It may only change the (unsaved) instance's data, as set_data does, so later decisions see it. The default does nothing.

Documentation
All packages

javaabu/workflows

Source on GitHub