home / skills / hoangnguyen0403 / agent-skills-standard / background-processing

background-processing skill

This skill helps you implement scalable Laravel background processing using queues, jobs, and events with best-practice guidelines.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill background-processing

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.5 KB

---
name: Laravel Background Processing
description: Scalable asynchronous workflows using Queues, Jobs, and Events.
metadata:
  labels: [laravel, queue, job, events, horizon]
  triggers:
    files:
      ['app/Jobs/**/*.php', 'app/Events/**/*.php', 'app/Listeners/**/*.php']
    keywords: [ShouldQueue, dispatch, batch, chain, listener]
---

# Laravel Background Processing

## **Priority: P1 (HIGH)**

## Structure

```text
app/
├── Jobs/               # Asynchronous tasks
├── Events/             # Communication flags
└── Listeners/          # Task reactions
```

## Implementation Guidelines

- **Offload Heavy Tasks**: Move any logic taking >100ms to a Queued Job.
- **ShouldQueue Interface**: Add to Listeners for transparent async execution.
- **Redis Driver**: Use Redis for reliable and high-throughput queuing.
- **Job Chaining**: Use `Bus::chain()` for dependent sequential jobs.
- **Job Batching**: Use `Bus::batch()` for parallel task monitoring.
- **Failures**: Define `failed()` method in jobs to handle permanent errors.
- **Monitoring**: Use **Laravel Horizon** for real-time queue observability.

## Anti-Patterns

- **Blocking UX**: **No heavy logic in Request path**: Always defer to Queues.
- **Raw Models**: **No large job payloads**: Pass model IDs, not full objects.
- **Implicit Flow**: **No deep event-loop logic**: Keep listener chains shallow.
- **Silent Failures**: **No unmonitored queues**: Ensure retries and alerts.

## References

- [Job Chaining & Event Patterns](references/implementation.md)

Overview

This skill provides a concise, opinionated approach to implementing scalable background processing in Laravel using Queues, Jobs, Events, and Listeners. It focuses on reliable async execution, observability, and patterns that prevent common pitfalls. The guidance emphasizes Redis-backed queues, job chaining and batching, and clear failure handling for production-grade workflows.

How this skill works

The skill organizes async logic into app/Jobs, app/Events, and app/Listeners so responsibilities are explicit and testable. Long-running or CPU-bound logic is moved into queued Jobs, listeners implement ShouldQueue for transparent background execution, and Job chaining/batching coordinates sequential or parallel flows. Monitoring and failure handling rely on Laravel Horizon and job failed() hooks to surface issues and trigger remediation.

When to use it

Any request path that takes longer than ~100ms or risks blocking user interaction.
Processing large data imports, image/video transcoding, report generation, or external API retries.
Workflows that require ordered steps (use chaining) or parallel subtasks with aggregated results (use batching).
Operations needing retry, visibility, or alerts in production environments.
Decoupling side effects like emails, webhooks, or analytics from synchronous requests.

Best practices

Offload heavy logic to Queued Jobs; keep controllers and requests fast and deterministic.
Use Redis as the queue driver for high throughput and low latency with Laravel Horizon for observability.
Pass model IDs or lightweight DTOs into jobs; avoid serializing whole Eloquent models in payloads.
Keep listener chains shallow; prefer explicit job chaining (Bus::chain()) over deep implicit event loops.
Implement failed() handlers on jobs and configure retries, timeouts, and alerts to avoid silent failures.

Example use cases

Upload pipeline: store file, dispatch a job to generate thumbnails, then chain transcoding and CDN invalidation jobs.
Order processing: accept order, dispatch inventory reservation job, then chain billing and shipment jobs.
Bulk import: run parallel parsing jobs with Bus::batch() and notify when the batch completes or fails.
Webhook delivery: enqueue webhook attempts with exponential retry and record permanent failures in failed().
Analytics aggregation: schedule periodic jobs to aggregate metrics and push to dashboards without blocking users.

FAQ

When should I use chaining vs batching?

Use chaining for dependent sequential steps that must run in order. Use batching for running many independent jobs in parallel while tracking overall progress and completion.

How do I avoid large job payloads?

Serialize only IDs or minimal DTOs and rehydrate models inside the job. This keeps the queue payload small and avoids stale data and serialization issues.