Skip to content
Tutorials Center
My learning

Topics

Lesson 37 of 67 ยท Queues, Events and Notifications

Queues and Jobs

Move slow work out of the request with Laravel queues. Learn jobs, dispatching, workers, retries, backoff, failed jobs, unique jobs, chains and batches.

Some work does not belong inside a web request. Sending an email, resizing an image, calling a slow payment API or building a report can take seconds, and the visitor is waiting the whole time. If the work fails halfway, the visitor sees an error for something they could not have fixed.

A queue solves this by splitting the work in two. The request writes a small description of the work, a job, to a storage place and answers immediately. A separate long-running process, the worker, picks jobs up one by one and runs them. If a job fails, the worker can try again later without any visitor involved. This lesson shows how Laravel does it, and you will build a small queue and worker yourself to see the moving parts. The general idea is covered in queues and background jobs.

Laravel itself cannot run on this site, so the Laravel code blocks below are read-only. The runnable examples are plain PHP stand-ins that follow the same ideas. Each section says which is which.

The moving parts

flowchart LR
    A["Controller<br/>dispatch(new SendReceipt)"] --> B[("Queue storage<br/>database, Redis, SQS")]
    B --> C["Worker<br/>php artisan queue:work"]
    C -->|success| D[Job deleted]
    C -->|exception| E{"Attempts left?"}
    E -->|yes| B
    E -->|no| F[("failed_jobs table")]

A job travels from the request to storage, to a worker, and ends up deleted or in the failed jobs table.

Laravel calls the storage a queue connection, configured in config/queue.php. The built-in drivers are database (the default in a fresh Laravel 13 app, using the jobs table), redis, sqs (Amazon), beanstalkd, sync and null. The sync driver runs the job immediately inside the request, which is handy in tests and while learning. The database driver needs no extra software, so it suits small and medium apps. Redis is the usual upgrade when you need more throughput. You choose the connection with QUEUE_CONNECTION in .env.

A connection can hold several named queues, such as default, emails and reports. Workers can listen to some of them in priority order, so urgent work is never stuck behind a long report.

Writing a job

Generate a job class with Artisan:

Terminal
php artisan make:job SendReceipt

That creates app/Jobs/SendReceipt.php. A job is a plain class with a handle() method. Laravel resolves the arguments of handle() from the service container, so you can type-hint any service.

PHP
<?php

namespace App\Jobs;

use App\Models\Order;
use App\Services\ReceiptMailer;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;

class SendReceipt implements ShouldQueue
{
    use Queueable;

    public int $tries = 3;

    public function __construct(public Order $order)
    {
    }

    public function handle(ReceiptMailer $mailer): void
    {
        $mailer->send($this->order);
    }
}

Three details matter:

  • ShouldQueue marks the class as queueable. Without it, dispatch() runs the job right away.
  • The Queueable trait adds methods such as onQueue(), delay() and onConnection().
  • The constructor receives an Eloquent model, and Laravel serializes only the model's identifier into the queue. When the worker runs, it loads a fresh copy from the database. Keep job payloads small: pass IDs or small value objects, never big arrays or open resources.

Dispatching

PHP
use App\Jobs\SendReceipt;

SendReceipt::dispatch($order);                        // default queue
SendReceipt::dispatch($order)->onQueue('emails');     // named queue
SendReceipt::dispatch($order)->delay(now()->addMinutes(10));
SendReceipt::dispatchIf($order->wants_receipt, $order);
SendReceipt::dispatchAfterResponse($order);           // after the response is sent

dispatch() serializes the job and stores it. It returns almost immediately, which is the whole point. If you dispatch inside a database transaction, the worker might pick the job up before the transaction commits and look for a row that does not exist yet. Call ->afterCommit() on the job, or set after_commit to true on the connection, to dispatch only once the transaction has committed.

Running the worker

Terminal
php artisan queue:work
php artisan queue:work --queue=emails,default --tries=3

queue:work is a long-running process: it boots the framework once and then loops, which makes it fast. The price is that it keeps your old code in memory. After a deploy you must run php artisan queue:restart, which tells workers to exit after their current job so a process manager starts fresh ones. In production, a manager such as Supervisor (or the Laravel Cloud and Forge equivalents) keeps workers running. See deploying Laravel. While developing, php artisan queue:listen reloads code on every job but is slower.

Building a queue and a worker

Here is a stand-in for the core idea: a jobs table in SQLite, a dispatch that inserts a row and a worker that claims, runs and deletes rows. It is not Laravel's code, but the table has the same essential columns: a queue name, a payload, an attempt counter.

PHP A job queue on SQLite

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Notice serialize(): the job object is turned into a string, stored and rebuilt later by a different process. That is why jobs should hold simple data. Laravel does the same, with extra handling for models.

Retries, backoff and failures

Things fail: the mail server is down, the API returns a 503. A good worker retries, but not instantly, because a service that is down for a minute will not recover in a millisecond. Laravel gives you these knobs on the job class:

PHP
class SendReceipt implements ShouldQueue
{
    use Queueable;

    public int $tries = 5;          // total attempts
    public int $maxExceptions = 3;  // stop after this many thrown exceptions
    public int $timeout = 30;       // seconds before the worker kills the job

    /** @return list<int> seconds to wait after each failed attempt */
    public function backoff(): array
    {
        return [10, 60, 300];
    }

    public function failed(?Throwable $exception): void
    {
        // notify the team, mark the order, clean up
    }
}

With that backoff the worker waits 10 seconds after the first failure, 60 after the second and 300 after the third and every later one. When attempts run out, Laravel calls failed() and writes a row to the failed_jobs table, with the payload and the exception. You can then run:

Terminal
php artisan queue:failed          # list failures
php artisan queue:retry all       # push them back on the queue
php artisan queue:retry 5         # retry one by UUID or ID
php artisan queue:flush           # delete all failed records

Because a job can run more than once, it must be idempotent: running it twice must not charge a card twice or send two receipts. Check whether the work is already done at the start of handle(), or use a unique key on the external side.

This stand-in adds attempts and backoff, measured in worker "ticks" instead of seconds so the output stays the same on every run.

PHP Retries, backoff and failed jobs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Unique jobs, chains and batches

Unique jobs. If a user clicks "rebuild search index" five times, you probably want one job. Implement ShouldBeUnique, and Laravel takes a lock (it needs a cache driver that supports locks) so a second copy is not queued while the first is waiting or running. Define uniqueId() to say what "the same job" means, for example the order ID. ShouldBeUniqueUntilProcessing releases the lock as soon as the job starts instead of when it ends.

Chains. Sometimes steps must run in order, and a later step must not run if an earlier one fails:

PHP
use Illuminate\Support\Facades\Bus;

Bus::chain([
    new OptimizeImage($photo),
    new GenerateThumbnails($photo),
    new NotifyOwner($photo),
])->dispatch();

If OptimizeImage fails permanently, the rest of the chain is skipped.

Batches. A batch runs many independent jobs and tells you when they are all done, which suits imports and bulk exports:

PHP
use Illuminate\Bus\Batch;
use Illuminate\Support\Facades\Bus;

$batch = Bus::batch($jobs)
    ->then(fn (Batch $batch) => /* all succeeded */ null)
    ->catch(fn (Batch $batch, Throwable $e) => /* first failure */ null)
    ->finally(fn (Batch $batch) => /* always */ null)
    ->allowFailures()
    ->dispatch();

Batch jobs use the Batchable trait and you need the job_batches table (php artisan make:queue-batches-table, then migrate). The batch object has progress information, so you can show a progress bar by polling its ID.

Horizon and watching your queues

For Redis queues, Laravel Horizon gives a dashboard and configuration in code: worker counts per queue, auto-scaling, throughput, runtime, failed jobs and alerts when a queue grows too long. With the database driver you can still watch the queues with php artisan queue:monitor and the jobs table. Whatever you use, alert on queue length and on failures: a silent, stuck queue is a bad surprise.

Testing queued code does not need a worker. Faking the queue lets you assert that a job was dispatched, covered in faking and mocking.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main benefit of dispatching a job instead of doing the work inside the request?

    Queuing does not make the work cheaper; it moves it out of the request, so the visitor does not wait and failed work can be retried later.
  2. 2. You deploy new code, but queued jobs keep running the old behavior. What is the likely cause and fix?

    queue:work boots the framework once. After a deploy, queue:restart makes workers exit after the current job so the process manager starts them with the new code.
  3. 3. Why should a queued job be idempotent?

    Retries, timeouts and crashes mean the same job can run again. Running twice must not, for example, send two receipts or charge twice.
  4. 4. What does a job chain guarantee?

    Bus::chain runs steps one after another, and a permanent failure stops the remaining jobs. A batch, by contrast, runs independent jobs and reports when all are done.

Summary

  • A queue moves slow or unreliable work out of the request: the request stores a job, a worker runs it.
  • Jobs implement ShouldQueue, use Queueable, and are dispatched with dispatch(); keep payloads small.
  • php artisan queue:work is long-running, so run queue:restart after deploys and keep workers alive with a process manager.
  • Use tries, backoff() and failed() for retries; failed jobs land in failed_jobs and can be retried.
  • Make jobs idempotent; use ShouldBeUnique to avoid duplicates, chains for ordered steps and batches for bulk work.
  • Horizon adds a dashboard for Redis queues.

Next: Events and Listeners