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. ExpireOrderJob calls ExpireOrderAction, in app/Jobs/.
  • A job takes the model. Constructor-promoted public Order $order. SerializesModels stores the id and re-fetches the row when the job runs, so the action sees current data. Never an int $orderId with a lookup in handle(), even when the row may be gone by then (see below).
  • Queue options only when the job needs them. No $tries, $timeout, backoff() or failed() by default; the worker's settings hold until a job proves otherwise. Never $tries with retryUntil(): Laravel ignores $tries once retryUntil() 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] from Illuminate\Queue\Attributes; alias the first as OnQueue beside the Queue enum: #[OnQueue(Queue::Processing)].
  • Actions dispatch jobs. After their writes: ExpireOrderJob::dispatch($order), or dispatchIf($condition, …). A controller calls the action; the action decides what to queue.
  • Events are {Subject}{PastTense} in app/Events/. OrderPaid, InvoiceSent; no Event suffix. 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 event as 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: SendOrderReceipt calls SendOrderReceiptAction. Never SendOrderReceiptListener.
  • Listeners are discovered, never registered. Laravel maps each listener in app/Listeners to the event its handle() 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.
Installs
56
GitHub Stars
15
First Seen
Mar 27, 2026