← Laractions 12 / 12

API reference

Everything the package exposes, in one place.

Action

EduLazaro\Laractions\Action, the abstract base every action extends.

Creating and running

Method	Returns	What it does
`Action::create(mixed ...$params)`	`static`	Resolves the action through the container, injecting constructor dependencies. Arguments are passed as container parameters.
`run(mixed ...$params)`	`mixed`	Resolves the arguments against `handle()`, validates them, calls `handle()` and returns its value.
`dispatch(mixed ...$params)`	`void`	Wraps the action in an `ActionJob` and queues it with the configured queue, delay and tries.
`__invoke(mixed ...$params)`	`mixed`	Forwards to `run()`, so an action can be used as a callable.

Configuring, before run() or dispatch()

All of these return the action, so they chain in any order.

Method	What it does
`with(mixed ...$params)`	Sets declared public or protected properties by name. Keys with no matching property are ignored.
`on(object $actionable)`	Sets the target and assigns it to a property named after its class, walking parent classes.
`actor(object $actor)`	Sets who is performing the action. Readable inside `handle()` as `$this->actor`.
`queue(string $queueName)`	Queue to dispatch on. Defaults to a queue literally named `default`.
`delay(int $seconds)`	Seconds before a dispatched job becomes available.
`retry(int $times)`	Total attempts for a dispatched job, counting the first.
`trace(bool $enabled = true)`	Writes an `action_traces` row after a successful run.
`enableLogging(bool $enabled = true)`	Logs the dispatch. Has no effect on `run()`.

Reading

Method	Returns	What it does
`getActionable()`	`?object`	The object set with `on()`, or null.
`getTries()`	`int`	The configured number of attempts.

What you define in a subclass

Member	Type	Purpose
`handle(...)`	method	The work. Required, may be `protected`, and its return value is what `run()` returns.
`$rules`	`array`	Validation rules keyed by `handle()` parameter name. Empty means no validation.
`$queue`	`?string`	Default queue for this action.
`$delay`	`?int`	Default delay in seconds.
`$tries`	`int`	Default number of attempts. Defaults to 1.
`$actionable`	`?object`	The target, set by `on()`.
`$actor`	`?object`	The actor, set by `actor()` or `act()`.
`log(string $message, array $context = [])`	method	Writes an `info` line prefixed with the action class. Always writes, regardless of `enableLogging()`.
`validate(array $params)`	method	Applies `$rules`. Called by `run()`; override to change how validation works.

Exceptions

Exception	When
`LogicException`	`run()` on an action with no `handle()` method.
`Illuminate\Validation\ValidationException`	`$rules` fail. A 422 in an HTTP context.
`Exception`	`$model->action('key')` with a key that is neither a class nor registered in `$actions`.

Concerns\HasActions

Model trait. Lets a model run actions about itself.

Member	What it does
`action(string $actionClass, array $params = [])`	Resolves the action (by class name, or by a key from `$actions`) with `$params` as constructor parameters, binds the model with `on()` and returns it.
`mockAction(string $actionClass, $mockAction)`	Replaces an action on this instance while running tests. Deprecated: bind the action in the container instead.
`$actions`	Optional map of short keys to action classes.

Concerns\IsActor

Model trait. Lets a model run actions about something else.

Member	What it does
`act(string $actionClass, array $params = [])`	Resolves the action with `$params` as constructor parameters, sets this model as the actor and returns it.

Jobs\ActionJob

The queued wrapper dispatch() builds. You never construct it, but you assert against it in tests.

Property	Type	Contents
`$action`	`?Action`	The action instance, serialized with the job.
`$actionClass`	`string`	Its class name.
`$actionableType`	`?string`	Class of the bound Eloquent model, if any.
`$actionableId`	`int\|string\|null`	Its primary key, integer or string, so UUID and ULID models queue too. The model is re-fetched when the job runs.
`$params`	`array`	The arguments, handed back to `run()`.
`$tries`	`int`	Attempts, taken from the action.

Its handle() rebuilds the actionable, binds it and calls run(). Its failed() writes the exception message and stack trace at error level.

ActionTrace

EduLazaro\Laractions\ActionTrace, an Eloquent model over action_traces.


Columns	`actor_type`, `actor_id`, `target_type`, `target_id`, `action`, `params`, timestamps
Casts	`params` to `array`
Relations	`actor()` and `target()`, both `morphTo`
Migration	Published with `--tag=laractions-migrations`

Commands

Command	What it does
`make:action {name} {--model=}`	Generates an action, standalone or bound to a model.
`list:actions`	Lists the files under `app/Actions` as class names.

Cheat sheet

// standalone
SendWelcomeEmail::create()->run('user@example.com', 'Welcome');
SendWelcomeEmail::create()->queue('emails')->delay(10)->retry(3)->dispatch($payload);

// from a model
$user->action('send_welcome')->run();
$user->action(SendWelcomeEmail::class)->dispatch();

// with an actor and a trace
$admin->act(RefundOrder::class)->on($order)->trace()->run();

// properties instead of arguments
SendWelcomeEmail::create()->with(['email' => $email, 'subject' => 'Welcome'])->run();

PreviousArtisan commands

built and maintained by Edu Lazaro · MIT license

On this page