Skip to main content
skill CX Codex

laravel-queues — Claude Code skill: async jobs and queue patterns

laravel-queues guides job design, driver selection, retry logic, worker scaling, and Horizon configuration in Laravel 13.

MIT 770 installs ★ 104 updated 2026-08-27

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add AsyrafHussin/agent-skills --skill laravel-queues -a claude-code
Open on GitHub

What laravel-queues does

The skill targets failures that escape testing: forgotten ShouldQueue runs jobs synchronously in request, serialised models go stale on workers, payment jobs lack idempotency, workers leak memory over time. It covers driver choice—database for small apps, redis for production, sqs for Vapor—passing IDs instead of models to avoid bloated payloads, implementing failed() callbacks for permanent errors, configuring supervisor with stopwaitsecs larger than job timeout, and backoff strategies via #[Backoff].

Includes patterns for Bus::batch() with progress tracking and allowFailures() for fault-tolerant parallel work, Bus::chain() for strict sequence, chunking large sets (1000+ items) to avoid one job per item, and guidance on Horizon—useful on Redis with multiple supervisors, but overkill on database driver or single-worker setups.

What it helps with

  • Design a background job with proper idempotency and error handling
  • Select a queue driver and configure failed_jobs storage
  • Set up supervisor with correct timeouts and retry behavior
  • Debug a stuck or looping job in production
  • Chain or batch multiple async tasks with dependencies

Example prompts for the agent

  • Review this job against laravel-queues rules: does it implement ShouldQueue, pass IDs not models, guarantee idempotency?
  • Audit queue config and supervisor settings: is stopwaitsecs large enough, should we adopt Horizon for this scale?
  • Design a payment batch with allowFailures() and exponential backoff for API rate limits

How to install laravel-queues

1Skills CLI (Vercel)

npx skills add AsyrafHussin/agent-skills --skill laravel-queues -a claude-code

2Manually: put the files in place

~/.claude/skills/laravel-queues/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/laravel-queues/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about laravel-queues

How do I install laravel-queues in Claude Code?

Run npx skills add AsyrafHussin/agent-skills --skill laravel-queues -a claude-code, then open ~/.claude/skills/laravel-queues/SKILL.md.

What does laravel-queues do?

It provides 20 rules for designing async jobs: driver selection (database, redis, sqs), idempotency, retry strategies, worker scaling, and batching. Triggers on requests about background jobs, Horizon setup, debugging stuck jobs, and queue health audits.

When should I use this skill?

When writing a new job, reviewing queue-related PRs, setting up workers on a new server, configuring queue.php or horizon.php, or debugging stuck and repeating jobs.

Source text

SKILL.md · MIT
---
name: laravel-queues
description: Laravel 13 queue and job patterns — driver choice, job design (idempotency, ShouldQueue, model serialisation), retry and failure handling, worker scaling, Bus batching and chaining, Horizon when warranted, queue testing. Use when designing async jobs, scheduling background work, configuring Horizon, debugging stuck jobs, or auditing queue health. Triggers on "Laravel queue", "Laravel job", "background job", "Horizon setup", "failed jobs", "Bus batch", "queue worker tuning".
license: MIT
metadata:
  author: agent-skills
  version: "1.0.0"
---

# Laravel Queues & Jobs

Production-grade queue patterns for Laravel 13 (MySQL + Redis). Contains 20 rules across 6 categories covering driver choice, job design, retry/failure handling, worker scaling, batching/chaining, and testing. Targets the failure modes that pass code review but break under load — silent re-dispatch on retry, models stale on serialisation, missing idempotency on payment jobs, workers leaking memory, and "we forgot ShouldQueue and the request takes 12 seconds in production."

## Metadata

- **Version:** 1.0.0
- **Scope:** PHP / Laravel 13 + MySQL + Redis (queues), optional Horizon
- **Rule Count:** 20 rules across 6 categories
- **License:** MIT

## How to Use

When the user asks "design this background job", "audit our queue setup", "why is this job not running", or anything queue-related — work through this skill's rules as a checklist against the relevant files (job classes, `config/queue.php`, `config/horizon.php`, supervisor config, the dispatching call sites).

For audit mode, output per-rule verdicts:
- **PASS** — pattern correctly applied
- **FAIL** — anti-pattern present (with file:line + fix recommendation)
- **N/A** — does not apply to this codebase

End with a top-priority fix list (idempotency on payment jobs, missing `ShouldQueue`, supervisor `stopwaitsecs` too low — these are the most common production-bite issues).

## When to Apply

Reference this skill when:
- Writing a new background job (`php artisan make:job`)
- Reviewing a PR that adds or modifies a job class
- Setting up queue workers on a new server (Forge / Vapor / bare server)
- Configuring `config/queue.php` or `config/horizon.php`
- Debugging a stuck, looping, or repeatedly-failing job
- Choosing between `dispatch()`, `dispatchSync()`, `dispatchAfterResponse()`, `Bus::batch()`, `Bus::chain()`
- Adding queue testing (`Queue::fake()`, `Bus::fake()`)
- Deciding whether to adopt Horizon

## Step 1: Detect Queue Setup

Inspect:

| File | What to learn |
|---|---|
| `config/queue.php` | Default connection (`QUEUE_CONNECTION` env), failed-jobs storage, `after_commit` setting |
| `config/horizon.php` (if present) | Horizon environments, balance strategy, worker counts, timeouts |
| `app/Jobs/*.php` | Job classes, `ShouldQueue` usage, `tries`/`backoff`, `failed()` methods |
| `app/Console/Kernel.php` or `routes/console.php` | Scheduled jobs (`Schedule::job(...)`, `withoutOverlapping`) |
| `database/migrations/*_create_failed_jobs_table.php` | Failed-jobs storage migration; or DynamoDB driver in config |
| `supervisor*.conf` / `/etc/supervisor/conf.d/` | Worker process management, `numprocs`, `--max-time`, `stopwaitsecs` |

Typical setups:

| Stack | Queue driver | Failed driver | Worker manager |
|---|---|---|---|
| Small Laravel + MySQL | `database` | `database` | Supervisor (or systemd) |
| Production Laravel + Redis | `redis` | `database` (or `dynamodb` for serverless) | Supervisor + Horizon |
| Laravel Vapor | `sqs` | `dynamodb` | Vapor-managed |

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Driver & Config | CRITICAL | `config-` |
| 2 | Job Design | CRITICAL | `design-` |
| 3 | Retry & Failure | HIGH | `retry-` |
| 4 | Scaling & Workers | HIGH | `scaling-` |
| 5 | Batching & Chaining | HIGH | `bus-` |
| 6 | Testing & Operations | MEDIUM | `ops-` |

## Quick Reference

### 1. Driver & Config (CRITICAL)

- `config-driver-choice` — `database` for small apps; `redis` for production scale; `sqs` for Laravel Vapor
- `config-after-commit` — set `after_commit: true` to prevent dispatching jobs that reference uncommitted DB rows
- `config-failed-storage` — `failed_jobs` table is required (or DynamoDB on Vapor); set up retention/cleanup

### 2. Job Design (CRITICAL)

- `design-shouldqueue` — every async job MUST implement `ShouldQueue` (the #1 production bug: forgetting it makes the job run synchronously)
- `design-pass-ids-not-models` — pass IDs to the constructor; refetch in `handle()` — avoids stale models and bloated serialised payloads
- `design-idempotency` — payment, external API, and "create resource" jobs must be safe to run twice (`ShouldBeUnique`, idempotency keys, unique DB constraints)
- `design-constructor-vs-handle` — constructor runs at dispatch (sync); `handle()` runs on the worker. No DB writes or HTTP calls in the constructor.

### 3. Retry & Failure (HIGH)

- `retry-tries-and-backoff` — set both: `#[Backoff([1, 5, 30])]` for exponential delays; default 3 tries is usually too few for transient failures
- `retry-failed-method` — implement `failed(Throwable $e)` for permanent-failure handling (alert, refund, mark-as-failed)
- `retry-transient-vs-permanent` — `release($delay)` for transient errors (rate-limited, network); throw for permanent
- `retry-fail-on-timeout` — `#[FailOnTimeout]` to avoid burning all attempts on hung jobs

### 4. Scaling & Workers (HIGH)

- `scaling-supervisor-config` — Supervisor (or systemd) manages workers; `stopwaitsecs > timeout`; `--max-time=3600` to recycle
- `scaling-multi-queue-priority` — high/default/low queue lanes for SLA-critical jobs; `--queue=high,default,low`
- `scaling-worker-recycling` — `--max-jobs` and `--max-time` to combat memory leaks in long-running workers

### 5. Batching & Chaining (HIGH)

- `bus-batch-vs-chain` — `Bus::batch` for parallel + progress tracking; `Bus::chain` for strict sequential
- `bus-batch-failure-handling` — `allowFailures()` for fault-tolerant batches; use `then`/`catch`/`finally` callbacks
- `bus-chunking-large-sets` — for 1000+ items, chunk via `Bus::batch(...)` rather than one job per item

### 6. Testing & Operations (MEDIUM)

- `ops-queue-fake` — `Queue::fake()` / `Bus::fake()` in tests; `assertDispatched`, `assertPushed`, `assertChained`, `assertBatched`
- `ops-schedule-queued-jobs` — `Schedule::job(new X)->everyMinute()` queues the job; pair with `withoutOverlapping()` for safety
- `ops-horizon-when` — adopt Horizon when on Redis with multiple supervisors; not for `database` queue or single-worker setups

## Essential Patterns

### Minimum-viable job class (Laravel 13)

```php
<?php

namespace App\Jobs;

use App\Models\Order;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\Attributes\Backoff;
use Illuminate\Queue\Attributes\FailOnTimeout;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Throwable;

#[Backoff([1, 5, 30])]
#[FailOnTimeout]
class ChargeOrder implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public int $tries = 5;
    public int $timeout = 30;

    public function __construct(public readonly int $orderId) {}

    public function handle(StripeGateway $stripe): void
    {
        $order = Order::findOrFail($this->orderId);   // refetch — don't trust serialised state
        if ($order->status === 'paid') return;        // idempotency guard

        $charge = $stripe->charge($order);
        $order->markPaid($charge->id);
    }

    public function failed(Throwable $e): void
    {
        Order::find($this->orderId)?->markPaymentFailed($e->getMessage());
    }
}
```

### Dispatching

```php
ChargeOrder::dispatch($order->id);                       // default queue
ChargeOrder::dispatch($order->id)->onQueue('high');      // priority lane
ChargeOrder::dispatch($order->id)->delay(now()->addMinutes(5));
ChargeOrder::dispatchAfterResponse($order->id);          // run after HTTP response sent
```

### Supervisor config (recommended)

```ini
[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/app/artisan queue:work redis --queue=high,default,low --sleep=3 --tries=3 --max-time=3600 --backoff=3
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=forge
numprocs=8
redirect_stderr=true
stdout_logfile=/var/www/app/storage/logs/worker.log
stopwaitsecs=3600
```

**Critical:** `stopwaitsecs` must be greater than your longest job's timeout, or Supervisor will kill mid-job on deploy.

## References

- [Laravel 13 — Queues](https://laravel.com/docs/13.x/queues)
- [Laravel 13 — Horizon](https://laravel.com/docs/13.x/horizon)
- [Laravel 13 — Task Scheduling](https://laravel.com/docs/13.x/scheduling)
- [Supervisor — A Process Control System](http://supervisord.org/)

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`

© agent-skills · MIT · AsyrafHussin/agent-skills

Similar skills

All skills for Backend and APIs →

From the same set24

The whole set →
code-slop code-slop flags synthetic AI patterns in PHP/Laravel and TypeScript/React codebases. Use it during PR reviews to weed out empty wrappers, mock-everything tests, and narrating comments. CX Codex +1 862installs state-management state-management is a Claude Code skill for handling data fetching, caching, and client-side state with React Query and Zustand. It activates around useQuery, useMutation, Zustand stores, and state-management tasks. CX Codex +1 849installs seo-best-practices The seo-best-practices skill audits web app SEO and guides work on metadata, JSON-LD, sitemaps, Open Graph, and Core Web Vitals. CX Codex +1 797installs technical-debt The technical-debt skill inventories debt in PHP/Laravel and Node/TypeScript/React projects, then ranks findings by impact and effort. Use it to plan refactoring. CX Codex +1 771installs prd-writing prd-writing is a Claude Code skill that guides your agent through six steps of discovery before drafting product requirements, using a 12-section template. CX Codex +1 722installs project-docs project-docs — a skill that runs the whole docs lifecycle: lays out folders, checks what has gone stale, and clears out files left behind by AI. CX Codex +1 721installs laravel-ai-sdk laravel-ai-sdk — a coding assistant skill containing 17 rules for laravel/ai. It guides the agent through building AI workflows, embeddings, and tests in Laravel 13. CX Codex +1 721installs laravel-mcp A skill for building MCP servers on Laravel: tools, prompts, resources, and auth via OAuth or Sanctum. CX Codex +1 712installs

Project sponsors

Companies that keep this analytics open