{"id":"78f55b50-22ee-4466-96f0-574fed6e477c","shortId":"33BUe9","kind":"skill","title":"laravel-queues","tagline":"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, ","description":"# Laravel Queues & Jobs\n\nProduction-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.\"\n\n## Metadata\n\n- **Version:** 1.0.0\n- **Scope:** PHP / Laravel 13 + MySQL + Redis (queues), optional Horizon\n- **Rule Count:** 20 rules across 6 categories\n- **License:** MIT\n\n## How to Use\n\nWhen 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).\n\nFor audit mode, output per-rule verdicts:\n- **PASS** — pattern correctly applied\n- **FAIL** — anti-pattern present (with file:line + fix recommendation)\n- **N/A** — does not apply to this codebase\n\nEnd with a top-priority fix list (idempotency on payment jobs, missing `ShouldQueue`, supervisor `stopwaitsecs` too low — these are the most common production-bite issues).\n\n## When to Apply\n\nReference this skill when:\n- Writing a new background job (`php artisan make:job`)\n- Reviewing a PR that adds or modifies a job class\n- Setting up queue workers on a new server (Forge / Vapor / bare server)\n- Configuring `config/queue.php` or `config/horizon.php`\n- Debugging a stuck, looping, or repeatedly-failing job\n- Choosing between `dispatch()`, `dispatchSync()`, `dispatchAfterResponse()`, `Bus::batch()`, `Bus::chain()`\n- Adding queue testing (`Queue::fake()`, `Bus::fake()`)\n- Deciding whether to adopt Horizon\n\n## Step 1: Detect Queue Setup\n\nInspect:\n\n| File | What to learn |\n|---|---|\n| `config/queue.php` | Default connection (`QUEUE_CONNECTION` env), failed-jobs storage, `after_commit` setting |\n| `config/horizon.php` (if present) | Horizon environments, balance strategy, worker counts, timeouts |\n| `app/Jobs/*.php` | Job classes, `ShouldQueue` usage, `tries`/`backoff`, `failed()` methods |\n| `app/Console/Kernel.php` or `routes/console.php` | Scheduled jobs (`Schedule::job(...)`, `withoutOverlapping`) |\n| `database/migrations/*_create_failed_jobs_table.php` | Failed-jobs storage migration; or DynamoDB driver in config |\n| `supervisor*.conf` / `/etc/supervisor/conf.d/` | Worker process management, `numprocs`, `--max-time`, `stopwaitsecs` |\n\nTypical setups:\n\n| Stack | Queue driver | Failed driver | Worker manager |\n|---|---|---|---|\n| Small Laravel + MySQL | `database` | `database` | Supervisor (or systemd) |\n| Production Laravel + Redis | `redis` | `database` (or `dynamodb` for serverless) | Supervisor + Horizon |\n| Laravel Vapor | `sqs` | `dynamodb` | Vapor-managed |\n\n## Rule Categories by Priority\n\n| Priority | Category | Impact | Prefix |\n|----------|----------|--------|--------|\n| 1 | Driver & Config | CRITICAL | `config-` |\n| 2 | Job Design | CRITICAL | `design-` |\n| 3 | Retry & Failure | HIGH | `retry-` |\n| 4 | Scaling & Workers | HIGH | `scaling-` |\n| 5 | Batching & Chaining | HIGH | `bus-` |\n| 6 | Testing & Operations | MEDIUM | `ops-` |\n\n## Quick Reference\n\n### 1. Driver & Config (CRITICAL)\n\n- `config-driver-choice` — `database` for small apps; `redis` for production scale; `sqs` for Laravel Vapor\n- `config-after-commit` — set `after_commit: true` to prevent dispatching jobs that reference uncommitted DB rows\n- `config-failed-storage` — `failed_jobs` table is required (or DynamoDB on Vapor); set up retention/cleanup\n\n### 2. Job Design (CRITICAL)\n\n- `design-shouldqueue` — every async job MUST implement `ShouldQueue` (the #1 production bug: forgetting it makes the job run synchronously)\n- `design-pass-ids-not-models` — pass IDs to the constructor; refetch in `handle()` — avoids stale models and bloated serialised payloads\n- `design-idempotency` — payment, external API, and \"create resource\" jobs must be safe to run twice (`ShouldBeUnique`, idempotency keys, unique DB constraints)\n- `design-constructor-vs-handle` — constructor runs at dispatch (sync); `handle()` runs on the worker. No DB writes or HTTP calls in the constructor.\n\n### 3. Retry & Failure (HIGH)\n\n- `retry-tries-and-backoff` — set both: `#[Backoff([1, 5, 30])]` for exponential delays; default 3 tries is usually too few for transient failures\n- `retry-failed-method` — implement `failed(Throwable $e)` for permanent-failure handling (alert, refund, mark-as-failed)\n- `retry-transient-vs-permanent` — `release($delay)` for transient errors (rate-limited, network); throw for permanent\n- `retry-fail-on-timeout` — `#[FailOnTimeout]` to avoid burning all attempts on hung jobs\n\n### 4. Scaling & Workers (HIGH)\n\n- `scaling-supervisor-config` — Supervisor (or systemd) manages workers; `stopwaitsecs > timeout`; `--max-time=3600` to recycle\n- `scaling-multi-queue-priority` — high/default/low queue lanes for SLA-critical jobs; `--queue=high,default,low`\n- `scaling-worker-recycling` — `--max-jobs` and `--max-time` to combat memory leaks in long-running workers\n\n### 5. Batching & Chaining (HIGH)\n\n- `bus-batch-vs-chain` — `Bus::batch` for parallel + progress tracking; `Bus::chain` for strict sequential\n- `bus-batch-failure-handling` — `allowFailures()` for fault-tolerant batches; use `then`/`catch`/`finally` callbacks\n- `bus-chunking-large-sets` — for 1000+ items, chunk via `Bus::batch(...)` rather than one job per item\n\n### 6. Testing & Operations (MEDIUM)\n\n- `ops-queue-fake` — `Queue::fake()` / `Bus::fake()` in tests; `assertDispatched`, `assertPushed`, `assertChained`, `assertBatched`\n- `ops-schedule-queued-jobs` — `Schedule::job(new X)->everyMinute()` queues the job; pair with `withoutOverlapping()` for safety\n- `ops-horizon-when` — adopt Horizon when on Redis with multiple supervisors; not for `database` queue or single-worker setups\n\n## Essential Patterns\n\n### Minimum-viable job class (Laravel 13)\n\n```php\n<?php\n\nnamespace App\\Jobs;\n\nuse App\\Models\\Order;\nuse Illuminate\\Bus\\Queueable;\nuse Illuminate\\Contracts\\Queue\\ShouldQueue;\nuse Illuminate\\Foundation\\Bus\\Dispatchable;\nuse Illuminate\\Queue\\Attributes\\Backoff;\nuse Illuminate\\Queue\\Attributes\\FailOnTimeout;\nuse Illuminate\\Queue\\InteractsWithQueue;\nuse Illuminate\\Queue\\SerializesModels;\nuse Throwable;\n\n#[Backoff([1, 5, 30])]\n#[FailOnTimeout]\nclass ChargeOrder implements ShouldQueue\n{\n    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;\n\n    public int $tries = 5;\n    public int $timeout = 30;\n\n    public function __construct(public readonly int $orderId) {}\n\n    public function handle(StripeGateway $stripe): void\n    {\n        $order = Order::findOrFail($this->orderId);   // refetch — don't trust serialised state\n        if ($order->status === 'paid') return;        // idempotency guard\n\n        $charge = $stripe->charge($order);\n        $order->markPaid($charge->id);\n    }\n\n    public function failed(Throwable $e): void\n    {\n        Order::find($this->orderId)?->markPaymentFailed($e->getMessage());\n    }\n}\n```\n\n### Dispatching\n\n```php\nChargeOrder::dispatch($order->id);                       // default queue\nChargeOrder::dispatch($order->id)->onQueue('high');      // priority lane\nChargeOrder::dispatch($order->id)->delay(now()->addMinutes(5));\nChargeOrder::dispatchAfterResponse($order->id);          // run after HTTP response sent\n```\n\n### Supervisor config (recommended)\n\n```ini\n[program:laravel-worker]\nprocess_name=%(program_name)s_%(process_num)02d\ncommand=php /var/www/app/artisan queue:work redis --queue=high,default,low --sleep=3 --tries=3 --max-time=3600 --backoff=3\nautostart=true\nautorestart=true\nstopasgroup=true\nkillasgroup=true\nuser=forge\nnumprocs=8\nredirect_stderr=true\nstdout_logfile=/var/www/app/storage/logs/worker.log\nstopwaitsecs=3600\n```\n\n**Critical:** `stopwaitsecs` must be greater than your longest job's timeout, or Supervisor will kill mid-job on deploy.\n\n## References\n\n- [Laravel 13 — Queues](https://laravel.com/docs/13.x/queues)\n- [Laravel 13 — Horizon](https://laravel.com/docs/13.x/horizon)\n- [Laravel 13 — Task Scheduling](https://laravel.com/docs/13.x/scheduling)\n- [Supervisor — A Process Control System](http://supervisord.org/)\n\n## Full Compiled Document\n\nFor the complete guide with all rules expanded: `AGENTS.md`","tags":["laravel","queues","agent","skills","asyrafhussin","agent-rules","agent-skills","ai-agents","ai-slop","claude-code","code-quality","code-review"],"capabilities":["skill","source-asyrafhussin","skill-laravel-queues","topic-agent-rules","topic-agent-skills","topic-ai-agents","topic-ai-slop","topic-claude-code","topic-code-quality","topic-code-review","topic-codex","topic-cursor","topic-laravel","topic-nodejs","topic-react"],"categories":["agent-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/AsyrafHussin/agent-skills/laravel-queues","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add AsyrafHussin/agent-skills","source_repo":"https://github.com/AsyrafHussin/agent-skills","install_from":"skills.sh"}},"qualityScore":"0.469","qualityRationale":"deterministic score 0.47 from registry signals: · indexed on github topic:agent-skills · 39 github stars · SKILL.md body (8,490 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T18:58:24.876Z","embedding":null,"createdAt":"2026-05-17T00:57:02.910Z","updatedAt":"2026-05-18T18:58:24.876Z","lastSeenAt":"2026-05-18T18:58:24.876Z","tsv":"'/)':1114 '/docs/13.x/horizon)':1099 '/docs/13.x/queues)':1093 '/docs/13.x/scheduling)':1106 '/etc/supervisor/conf.d':377 '/var/www/app/artisan':1029 '/var/www/app/storage/logs/worker.log':1064 '02d':1026 '1':313,429,461,528,617,905 '1.0.0':116 '1000':783 '12':110 '13':5,51,120,860,1089,1095,1101 '2':434,514 '20':55,128 '3':439,605,624,1038,1040,1046 '30':619,907,925 '3600':701,1044,1066 '4':444,683 '5':449,618,741,906,921,1001 '6':58,131,454,795 '8':1058 'across':57,130 'ad':300 'add':260 'addminut':1000 'adopt':310,835 'agents.md':1126 'alert':646 'allowfailur':766 'anti':198 'anti-pattern':197 'anyth':157 'api':564 'app':472,864,867 'app/console/kernel.php':355 'app/jobs':345 'appli':195,209,242 'artisan':253 'ask':141 'assertbatch':812 'assertchain':811 'assertdispatch':809 'assertpush':810 'async':36,522 'attempt':679 'attribut':887,892 'audit':146,185 'autorestart':1049 'autostart':1047 'avoid':552,676 'background':39,144,250 'backoff':352,613,616,888,904,1045 'balanc':340 'bare':276 'batch':25,297,450,742,747,751,763,771,788 'batching/chaining':69 'bite':238 'bloat':556 'break':81 'bug':530 'burn':677 'bus':24,296,298,305,453,746,750,756,762,778,787,805,872,882 'bus-batch-failure-handl':761 'bus-batch-vs-chain':745 'bus-chunking-large-set':777 'call':182,601 'callback':776 'catch':774 'categori':59,132,422,426 'chain':27,299,451,743,749,757 'charg':957,959,963 'chargeord':910,980,986,994,1002 'checklist':169 'choic':11,62,468 'choos':291 'chunk':779,785 'class':175,265,348,858,909 'code':78 'codebas':212 'combat':733 'command':1027 'commit':333,484,487 'common':235 'compil':1116 'complet':1120 'conf':376 'config':179,374,431,433,463,466,482,499,690,1012 'config-after-commit':481 'config-driver-choic':465 'config-failed-storag':498 'config/horizon.php':177,281,335 'config/queue.php':176,279,322 'configur':278 'connect':324,326 'constraint':580 'construct':928 'constructor':548,583,586,604 'contain':54 'contract':876 'control':1110 'correct':194 'count':127,343 'cover':60 'creat':566 'create_failed_jobs_table.php':364 'critic':432,437,464,517,715,1067 'databas':398,399,407,469,845 'database/migrations':363 'db':496,579,597 'debug':282 'decid':307 'default':323,623,719,984,1035 'delay':622,658,998 'deploy':1086 'design':13,35,64,142,436,438,516,519,539,560,582 'design-constructor-vs-handl':581 'design-idempot':559 'design-pass-ids-not-model':538 'design-shouldqueu':518 'detect':314 'dispatch':87,181,293,491,589,883,914,978,981,987,995 'dispatchafterrespons':295,1003 'dispatchsync':294 'document':1117 'driver':10,61,372,390,392,430,462,467 'dynamodb':371,409,417,508 'e':640,969,976 'end':213 'env':327 'environ':339 'error':661 'essenti':852 'everi':521 'everyminut':822 'expand':1125 'exponenti':621 'extern':563 'fail':196,289,329,353,366,391,500,502,635,638,651,671,967 'failed-job':328,365 'failontimeout':674,893,908 'failur':20,74,441,607,632,644,764 'fake':304,306,802,804,806 'fault':769 'fault-toler':768 'file':173,202,318 'final':775 'find':972 'findorfail':941 'fix':204,219 'forg':274,1056 'forget':531 'forgot':104 'foundat':881 'full':1115 'function':927,934,966 'getmessag':977 'grade':46 'greater':1071 'guard':956 'guid':1121 'handl':21,66,551,585,591,645,765,935 'high':442,447,452,608,686,718,744,991,1034 'high/default/low':709 'horizon':28,125,311,338,413,833,836,1096 'http':600,1008 'hung':681 'id':541,545,964,983,989,997,1005 'idempot':14,95,221,561,576,955 'illumin':871,875,880,885,890,895,899 'impact':427 'implement':525,637,911 'ini':1014 'inspect':317 'int':919,923,931 'interactswithqueu':897,915 'issu':239 'item':784,794 'job':8,12,37,43,63,98,145,153,174,224,251,255,264,290,330,347,359,361,367,435,492,503,515,523,535,568,682,716,727,792,817,819,825,857,865,1075,1084 'key':577 'kill':1081 'killasgroup':1053 'lane':711,993 'laravel':2,4,41,50,119,396,404,414,479,859,1017,1088,1094,1100 'laravel-queu':1 'laravel-work':1016 'laravel.com':1092,1098,1105 'laravel.com/docs/13.x/horizon)':1097 'laravel.com/docs/13.x/queues)':1091 'laravel.com/docs/13.x/scheduling)':1104 'larg':780 'leak':100,735 'learn':321 'licens':133 'limit':664 'line':203 'list':220 'load':83 'logfil':1063 'long':738 'long-run':737 'longest':1074 'loop':285 'low':230,720,1036 'make':254,533 'manag':380,394,420,694 'mark':649 'mark-as-fail':648 'markpaid':962 'markpaymentfail':975 'max':383,699,726,730,1042 'max-job':725 'max-tim':382,698,729,1041 'medium':457,798 'memori':101,734 'metadata':114 'method':354,636 'mid':1083 'mid-job':1082 'migrat':369 'minimum':855 'minimum-vi':854 'miss':94,225 'mit':134 'mode':75,186 'model':16,90,543,554,868 'modifi':262 'multi':706 'multipl':841 'must':524,569,1069 'mysql':52,121,397 'n/a':206 'name':1020,1022 'namespac':863 'network':665 'new':249,272,820 'num':1025 'numproc':381,1057 'one':791 'onqueu':990 'op':458,800,814,832 'oper':456,797 'ops-horizon-when':831 'ops-queue-fak':799 'ops-schedule-queued-job':813 'option':124 'order':869,939,940,951,960,961,971,982,988,996,1004 'orderid':932,943,974 'output':187 'paid':953 'pair':826 'parallel':753 'pass':77,192,540,544 'pattern':9,48,193,199,853 'payload':558 'payment':97,223,562 'per':189,793 'per-rul':188 'perman':643,656,668 'permanent-failur':642 'php':118,252,346,861,862,979,1028 'pr':258 'prefix':428 'present':200,337 'prevent':490 'prioriti':218,424,425,708,992 'process':379,1019,1024,1109 'product':45,113,237,403,475,529 'production-bit':236 'production-grad':44 'program':1015,1021 'progress':754 'public':918,922,926,929,933,965 'queu':816 'queue':3,6,31,42,47,123,148,159,268,301,303,315,325,389,707,710,717,801,803,823,846,877,886,891,896,900,985,1030,1033,1090 'queue-rel':158 'queueabl':873,916 'quick':459 'rate':663 'rate-limit':662 'rather':789 're':86 're-dispatch':85 'readon':930 'recommend':205,1013 'recycl':703,724 'redi':53,122,405,406,473,839,1032 'redirect':1059 'refer':243,460,494,1087 'refetch':549,944 'refund':647 'relat':160 'releas':657 'relev':172 'repeat':288 'repeatedly-fail':287 'request':108 'requir':506 'resourc':567 'respons':1009 'retention/cleanup':513 'retri':18,89,440,443,606,610,634,653,670 'retry-fail-on-timeout':669 'retry-failed-method':633 'retry-transient-vs-perman':652 'retry-tries-and-backoff':609 'retry/failure':65 'return':954 'review':79,256 'routes/console.php':357 'row':497 'rule':56,126,129,166,190,421,1124 'run':155,536,573,587,592,739,1006 'safe':571 'safeti':830 'scale':23,68,445,448,476,684,688,705,722 'scaling-multi-queue-prior':704 'scaling-supervisor-config':687 'scaling-worker-recycl':721 'schedul':38,358,360,815,818,1103 'scope':117 'second':111 'sent':1010 'sequenti':760 'serialis':17,93,557,948 'serializesmodel':901,917 'server':273,277 'serverless':411 'set':266,334,485,511,614,781 'setup':149,316,387,851 'shouldbeuniqu':575 'shouldqueu':15,105,226,349,520,526,878,912 'silent':84 'singl':849 'single-work':848 'site':183 'skill':164,245 'skill-laravel-queues' 'sla':714 'sla-crit':713 'sleep':1037 'small':395,471 'source-asyrafhussin' 'sqs':416,477 'stack':388 'stale':91,553 'state':949 'status':952 'stderr':1060 'stdout':1062 'step':312 'stopasgroup':1051 'stopwaitsec':228,385,696,1065,1068 'storag':331,368,501 'strategi':341 'strict':759 'stripe':937,958 'stripegateway':936 'stuck':284 'supervisor':178,227,375,400,412,689,691,842,1011,1079,1107 'supervisord.org':1113 'supervisord.org/)':1112 'sync':590 'synchron':537 'system':1111 'systemd':402,693 'tabl':504 'take':109 'target':72 'task':1102 'test':32,71,302,455,796,808 'throw':666 'throwabl':639,903,968 'time':384,700,731,1043 'timeout':344,673,697,924,1077 'toler':770 'top':217 'top-prior':216 'topic-agent-rules' 'topic-agent-skills' 'topic-ai-agents' 'topic-ai-slop' 'topic-claude-code' 'topic-code-quality' 'topic-code-review' 'topic-codex' 'topic-cursor' 'topic-laravel' 'topic-nodejs' 'topic-react' 'track':755 'transient':631,654,660 'tri':351,611,625,920,1039 'true':488,1048,1050,1052,1054,1061 'trust':947 'twice':574 'typic':386 'uncommit':495 'uniqu':578 'usag':350 'use':33,137,772,866,870,874,879,884,889,894,898,902,913 'user':140,1055 'usual':627 'vapor':275,415,419,480,510 'vapor-manag':418 'verdict':191 'version':115 'via':786 'viabl':856 'void':938,970 'vs':584,655,748 'warrant':30 'whether':308 'withoutoverlap':362,828 'work':40,161,1031 'worker':22,67,99,269,342,378,393,446,595,685,695,723,740,850,1018 'write':247,598 'x':821","prices":[{"id":"b880812a-a45b-4572-b6f4-8c2ac7c70d23","listingId":"78f55b50-22ee-4466-96f0-574fed6e477c","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"AsyrafHussin","category":"agent-skills","install_from":"skills.sh"},"createdAt":"2026-05-17T00:57:02.910Z"}],"sources":[{"listingId":"78f55b50-22ee-4466-96f0-574fed6e477c","source":"github","sourceId":"AsyrafHussin/agent-skills/laravel-queues","sourceUrl":"https://github.com/AsyrafHussin/agent-skills/tree/main/skills/laravel-queues","isPrimary":false,"firstSeenAt":"2026-05-17T00:57:02.910Z","lastSeenAt":"2026-05-18T18:58:24.876Z"}],"details":{"listingId":"78f55b50-22ee-4466-96f0-574fed6e477c","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"AsyrafHussin","slug":"laravel-queues","github":{"repo":"AsyrafHussin/agent-skills","stars":39,"topics":["agent-rules","agent-skills","ai-agents","ai-slop","claude-code","code-quality","code-review","codex","cursor","laravel","nodejs","react","technical-debt","typescript","windsurf"],"license":"mit","html_url":"https://github.com/AsyrafHussin/agent-skills","pushed_at":"2026-05-16T19:24:02Z","description":"Agent skills for AI coding agents (Claude Code, Cursor, Codex, Windsurf) — Laravel, React, TypeScript, MySQL, code quality, technical debt, documentation, and security.","skill_md_sha":"9b9ddaf73ea992275c13e9847a369e287550c1fa","skill_md_path":"skills/laravel-queues/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/AsyrafHussin/agent-skills/tree/main/skills/laravel-queues"},"layout":"multi","source":"github","category":"agent-skills","frontmatter":{"name":"laravel-queues","license":"MIT","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\"."},"skills_sh_url":"https://skills.sh/AsyrafHussin/agent-skills/laravel-queues"},"updatedAt":"2026-05-18T18:58:24.876Z"}}