laravel-jobs
Installation
SKILL.md
Laravel Jobs
Jobs, events and listeners move work off the request; none of them does the work. A job is the queue's way to call one action later. An event announces that something happened, and each listener reacts by calling one action. Queue a job when the caller knows the work must happen and only wants it off the request; dispatch an event when other parts of the app react to a change and the code that made it shouldn't know who they are.
Rules
- A job calls one action. The constructor takes what the action needs,
handle()injects the action and calls it. Nothing else: no queries, no branching, no$order->update(...). The operation then runs the same whether it's queued or called directly. laravel-actions owns the logic. - Named after the action it wraps.
ExpireOrderJobcallsExpireOrderAction, inapp/Jobs/. - A job takes the model. Constructor-promoted
public Order $order.SerializesModelsstores the id and re-fetches the row when the job runs, so the action sees current data. Never anint $orderIdwith a lookup inhandle(), even when the row may be gone by then (see below). - Queue options only when the job needs them. No
$tries,$timeout,backoff()orfailed()by default; the worker's settings hold until a job proves otherwise. Never$trieswithretryUntil(): Laravel ignores$triesonceretryUntil()is set. - Queue names are cases of
App\Enums\Queue. A small enum, one case per queue a worker serves (Default,Processing). A job on a named queue sets it in its constructor,$this->onQueue(Queue::Processing); Laravel 12 takes the case directly. Horizon's supervisors list them from the enum too:'queue' => [Queue::Default->value, Queue::Processing->value]. - On Laravel 13, queue options are attributes.
#[Queue],#[UniqueFor],#[Tries],#[Backoff],#[Timeout]fromIlluminate\Queue\Attributes; alias the firstas OnQueuebeside theQueueenum:#[OnQueue(Queue::Processing)]. - Actions dispatch jobs. After their writes:
ExpireOrderJob::dispatch($order), ordispatchIf($condition, …). A controller calls the action; the action decides what to queue. - Events are
{Subject}{PastTense}inapp/Events/.OrderPaid,InvoiceSent; noEventsuffix. An event for a state change is fired by its transition and nowhere else (laravel-state-machines); where a file also imports the state, alias the eventas OrderPaidEvent. Any other event is dispatched by the action that made the change. - An event carries the model, nothing derived.
public function __construct(public Order $order) {}. Listeners read what they need from it, so a new listener never means changing the event. Stored events in an event-sourced app are different: they carry plain values (laravel-event-sourcing). - Listeners are queued and call one action.
implements ShouldQueue, the action constructor-injected,handle()passes it the event's model. A slow or failing listener then can't fail the request that fired the event. - Listeners are named for what they do. After the action they call, without the suffix:
SendOrderReceiptcallsSendOrderReceiptAction. NeverSendOrderReceiptListener. - Listeners are discovered, never registered. Laravel maps each listener in
app/Listenersto the event itshandle()type-hints. A union type (handle(OrderPaid|OrderRefunded $event)) shares one listener across events that carry the same model; discovery registers it for each. - Not
final. Jobs, events and listeners are plain classes.