Laravel Async

Laravel Async

Rules for work that happens outside the request: 36 rules across 5 sections.

Two assumptions run through all of them:

• A queued handler runs more than once. Delivery is at-least-once, so every handler must be safe to repeat.
• A cache entry is wrong until something invalidates it. A TTL is a backstop, not the mechanism.

When to Apply

• Writing or reviewing a Job, Event, Listener or scheduled task
• Work is duplicated, lost, or executing inside a request that should return immediately
• A queue is backing up, or failures are going unnoticed
• Adding caching, or debugging stale or cross-tenant cached data
• Configuring queue connections, Horizon supervisors or the scheduler

Pick the Rule

Before You Write Code

• Every API named in these rules is verified against Laravel ^12.0 || ^13.0 and PHP ^8.3. If you need something these rules do not name, check the docs — never infer an API from its name.
• Version-gated APIs are marked inline ("Laravel 13 only"). Read the project's composer.json first; on Laravel 12 use the fallback the rule gives.
• Where the project already differs from a rule, follow the project. Name the rule you set aside and why, rather than half-converting the codebase.
• When two rules collide, the higher-impact section wins — sections are ordered by impact.
• One example is not the whole rule. Open rules/{slug}.md before adapting it to a case the example does not show.

Rule Sections by Priority

Quick Reference

1. Jobs (CRITICAL)

• job-idempotent-handlers — Running twice must equal running once
• job-queue-slow-work — Queue anything slow or externally dependent
• job-retries-and-backoff — Set tries, backoff and timeout on every job
• job-serialize-ids-not-models — Pass identifiers, not object graphs
• job-never-serialize-secrets — A credential never enters a job payload
• job-retry-after-exceeds-timeout — retry_after longer than any job's timeout
• job-rate-limit-external-calls — Throttle jobs that call a third-party API
• job-unique-jobs — Collapse duplicate dispatches with ShouldBeUnique
• job-batches-and-chains — Batches for fan-out, chains for ordered steps
• job-handle-failure-explicitly — Decide what happens after the last attempt
• job-fail-fast-on-permanent-errors — Stop retrying what cannot succeed

2. Domain Events (HIGH)

• event-emit-for-side-effects — Announce state changes, do not perform effects inline
• event-past-tense-immutable — Events are immutable and past tense
• event-carry-identity-not-models — Events carry identities, not Models
• event-listeners-own-domain-only — A listener touches only its own domain
• event-queue-side-effecting-listeners — Side-effecting listeners are queued
• event-dispatch-after-commit — Dispatch after the transaction commits
• event-queue-notifications-and-mailables — Queue them, and send after commit
• event-outbox-for-must-deliver — Commit the intent with the data when loss is unacceptable

3. Queue Operations (HIGH)

• queue-separate-by-priority — Separate queues by latency budget
• queue-route-by-class — Route jobs to queues centrally (Laravel 13)
• queue-never-sync-in-production — sync is for tests only
• queue-restart-workers-on-deploy — Workers keep old code until restarted
• queue-monitor-depth-and-failures — Depth, wait time and failure rate
• queue-sqs-visibility-timeout — On SQS the lease lives in AWS, not in config

4. Caching (HIGH)

• cache-read-heavy-endpoints — Cache in the Repository, cache results not models
• cache-stable-key-convention — Deterministic keys including every input
• cache-invalidate-on-model-events — Invalidate on write, not on a timer
• cache-tags-for-related-data — Tag related entries to flush a group
• cache-lock-against-stampede — One rebuild, not two hundred
• cache-touch-to-extend-ttl — Sliding expiry without a rewrite (Laravel 13)
• cache-memoize-within-the-request — Collapse repeat reads inside one request

5. Scheduling (MEDIUM)

• schedule-queue-work-not-inline — A scheduled task queues work
• schedule-prevent-overlapping — Stop a slow task stacking copies
• schedule-run-on-one-server — Exactly one server per task
• schedule-monitor-and-alert — Make silence itself the alert

Version Notes

Infrastructure Requirements

Reference Material

• references/idempotency-patterns.md — the four ways to make a handler repeat-safe
• references/cache-invalidation-playbook.md — choosing TTL, tags, versions or events
• references/checklist.md — pre-merge self-check for async work

How to Use

Load in this order and stop when the answer is clear:

1. This file — the Quick Reference names every rule, and usually settles the question.
2. One rule file for the reasoning and both examples (~397 tokens each):

rules/job-idempotent-handlers.md
rules/cache-invalidate-on-model-events.md

3. A references/ file only when a rule points at one.

AGENTS.md is every rule compiled into one document (~11k tokens), for agents that read the AGENTS.md convention. Do not load it when the individual rule files are reachable.

Related Skills

• laravel-engineering — trace callers and effects, preserve failures, and verify the changed path
• laravel-patterns — where events, listeners and their contracts live across domains
• laravel-eloquent — transactions, after_commit and bulk writes that skip observers
• laravel-rest-api — returning 202 and a pollable resource instead of blocking
• laravel-testing — Queue::fake(), Bus::fake(), Event::fake() and testing idempotency