Queues

• Introduction
  • Connections vs. Queues
  • Driver Notes and Prerequisites
• Creating Jobs
  • Generating Job Classes
  • Class Structure
  • Unique Jobs
  • Encrypted Jobs
• Job Middleware
  • Rate Limiting
  • Preventing Job Overlaps
  • Throttling Exceptions
• Dispatching Jobs
  • Delayed Dispatching
  • Synchronous Dispatching
  • Jobs & Database Transactions
  • Job Chaining
  • Customizing The Queue and Connection
  • Specifying Max Job Attempts / Timeout Values
  • Error Handling
• Job Batching
  • Defining Batchable Jobs
  • Dispatching Batches
  • Chains and Batches
  • Adding Jobs to Batches
  • Inspecting Batches
  • Cancelling Batches
  • Batch Failures
  • Pruning Batches
  • Storing Batches in DynamoDB
• Queueing Closures
• Running the Queue Worker
  • The queue:work Command
  • Queue Priorities
  • Queue Workers and Deployment
  • Job Expirations and Timeouts
• Supervisor Configuration
• Dealing With Failed Jobs
  • Cleaning Up After Failed Jobs
  • Retrying Failed Jobs
  • Ignoring Missing Models
  • Pruning Failed Jobs
  • Storing Failed Jobs in DynamoDB
  • Disabling Failed Job Storage
  • Failed Job Events
• Clearing Jobs From Queues
• Monitoring Your Queues
• Testing
  • Faking a Subset of Jobs
  • Testing Job Chains
  • Testing Job Batches
  • Testing Job / Queue Interactions
• Job Events

Introduction

While building your web application, you may have some tasks, such as parsing and storing an uploaded CSV file, that take too long to perform during a typical web request. Thankfully, Laravel allows you to easily create queued jobs that may be processed in the background. By moving time intensive tasks to a queue, your application can respond to web requests with blazing speed and provide a better user experience to your customers.

Laravel queues provide a unified queueing API across a variety of different queue backends, such as Amazon SQS, Redis, or even a relational database.

Laravel's queue configuration options are stored in your application's config/queue.php configuration file. In this file, you will find connection configurations for each of the queue drivers that are included with the framework, including the database, Amazon SQS, Redis, and Beanstalkd drivers, as well as a synchronous driver that will execute jobs immediately (for use during local development). A null queue driver is also included which discards queued jobs.

Connections vs. Queues

Before getting started with Laravel queues, it is important to understand the distinction between "connections" and "queues". In your config/queue.php configuration file, there is a connections configuration array. This option defines the connections to backend queue services such as Amazon SQS, Beanstalk, or Redis. However, any given queue connection may have multiple "queues" which may be thought of as different stacks or piles of queued jobs.

Note that each connection configuration example in the queue configuration file contains a queue attribute. This is the default queue that jobs will be dispatched to when they are sent to a given connection. In other words, if you dispatch a job without explicitly defining which queue it should be dispatched to, the job will be placed on the queue that is defined in the queue attribute of the connection configuration:

1use App\Jobs\ProcessPodcast;
2 
3// This job is sent to the default connection's default queue...
4ProcessPodcast::dispatch();
5 
6// This job is sent to the default connection's "emails" queue...
7ProcessPodcast::dispatch()->onQueue('emails');
1use App\Jobs\ProcessPodcast;
2 
3// This job is sent to the default connection's default queue...
4ProcessPodcast::dispatch();
5 
6// This job is sent to the default connection's "emails" queue...
7ProcessPodcast::dispatch()->onQueue('emails');

Some applications may not need to ever push jobs onto multiple queues, instead preferring to have one simple queue. However, pushing jobs to multiple queues can be especially useful for applications that wish to prioritize or segment how jobs are processed, since the Laravel queue worker allows you to specify which queues it should process by priority. For example, if you push jobs to a high queue, you may run a worker that gives them higher processing priority:

1php artisan queue:work --queue=high,default
1php artisan queue:work --queue=high,default

Driver Notes and Prerequisites

Database

In order to use the database queue driver, you will need a database table to hold the jobs. Typically, this is included in Laravel's default 0001_01_01_000002_create_jobs_table.php database migration; however, if your application does not contain this migration, you may use the make:queue-table Artisan command to create it:

1php artisan make:queue-table
2 
3php artisan migrate
1php artisan make:queue-table
2 
3php artisan migrate

Redis

In order to use the redis queue driver, you should configure a Redis database connection in your config/database.php configuration file.

Redis Cluster

If your Redis queue connection uses a Redis Cluster, your queue names must contain a key hash tag. This is required in order to ensure all of the Redis keys for a given queue are placed into the same hash slot:

1'redis' => [
2    'driver' => 'redis',
3    'connection' => env('REDIS_QUEUE_CONNECTION', 'default'),
4    'queue' => env('REDIS_QUEUE', '{default}'),
5    'retry_after' => env('REDIS_QUEUE_RETRY_AFTER', 90),
6    'block_for' => null,
7    'after_commit' => false,
8],
1'redis' => [
2    'driver' => 'redis',
3    'connection' => env('REDIS_QUEUE_CONNECTION', 'default'),
4    'queue' => env('REDIS_QUEUE', '{default}'),
5    'retry_after' => env('REDIS_QUEUE_RETRY_AFTER', 90),
6    'block_for' => null,
7    'after_commit' => false,
8],

Blocking

When using the Redis queue, you may use the block_for configuration option to specify how long the driver should wait for a job to become available before iterating through the worker loop and re-polling the Redis database.

Adjusting this value based on your queue load can be more efficient than continually polling the Redis database for new jobs. For instance, you may set the value to 5 to indicate that the driver should block for five seconds while waiting for a job to become available:

1'redis' => [
2    'driver' => 'redis',
3    'connection' => env('REDIS_QUEUE_CONNECTION', 'default'),
4    'queue' => env('REDIS_QUEUE', 'default'),
5    'retry_after' => env('REDIS_QUEUE_RETRY_AFTER', 90),
6    'block_for' => 5,
7    'after_commit' => false,
8],
1'redis' => [
2    'driver' => 'redis',
3    'connection' => env('REDIS_QUEUE_CONNECTION', 'default'),
4    'queue' => env('REDIS_QUEUE', 'default'),
5    'retry_after' => env('REDIS_QUEUE_RETRY_AFTER', 90),
6    'block_for' => 5,
7    'after_commit' => false,
8],

Other Driver Prerequisites

The following dependencies are needed for the listed queue drivers. These dependencies may be installed via the Composer package manager:

Creating Jobs

Generating Job Classes

By default, all of the queueable jobs for your application are stored in the app/Jobs directory. If the app/Jobs directory doesn't exist, it will be created when you run the make:job Artisan command:

1php artisan make:job ProcessPodcast
1php artisan make:job ProcessPodcast

The generated class will implement the Illuminate\Contracts\Queue\ShouldQueue interface, indicating to Laravel that the job should be pushed onto the queue to run asynchronously.

Class Structure

Job classes are very simple, normally containing only a handle method that is invoked when the job is processed by the queue. To get started, let's take a look at an example job class. In this example, we'll pretend we manage a podcast publishing service and need to process the uploaded podcast files before they are published:

 1<?php
 2 
 3namespace App\Jobs;
 4 
 5use App\Models\Podcast;
 6use App\Services\AudioProcessor;
 7use Illuminate\Bus\Queueable;
 8use Illuminate\Contracts\Queue\ShouldQueue;
 9use Illuminate\Foundation\Bus\Dispatchable;
10use Illuminate\Queue\InteractsWithQueue;
11use Illuminate\Queue\SerializesModels;
12 
13class ProcessPodcast implements ShouldQueue
14{
15    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
16 
17    /**
18     * Create a new job instance.
19     */
20    public function __construct(
21        public Podcast $podcast,
22    ) {}
23 
24    /**
25     * Execute the job.
26     */
27    public function handle(AudioProcessor $processor): void
28    {
29        // Process uploaded podcast...
30    }
31}
 1<?php
 2 
 3namespace App\Jobs;
 4 
 5use App\Models\Podcast;
 6use App\Services\AudioProcessor;
 7use Illuminate\Bus\Queueable;
 8use Illuminate\Contracts\Queue\ShouldQueue;
 9use Illuminate\Foundation\Bus\Dispatchable;
10use Illuminate\Queue\InteractsWithQueue;
11use Illuminate\Queue\SerializesModels;
12 
13class ProcessPodcast implements ShouldQueue
14{
15    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
16 
17    /**
18     * Create a new job instance.
19     */
20    public function __construct(
21        public Podcast $podcast,
22    ) {}
23 
24    /**
25     * Execute the job.
26     */
27    public function handle(AudioProcessor $processor): void
28    {
29        // Process uploaded podcast...
30    }
31}

In this example, note that we were able to pass an Eloquent model directly into the queued job's constructor. Because of the SerializesModels trait that the job is using, Eloquent models and their loaded relationships will be gracefully serialized and unserialized when the job is processing.

If your queued job accepts an Eloquent model in its constructor, only the identifier for the model will be serialized onto the queue. When the job is actually handled, the queue system will automatically re-retrieve the full model instance and its loaded relationships from the database. This approach to model serialization allows for much smaller job payloads to be sent to your queue driver.

handle Method Dependency Injection

The handle method is invoked when the job is processed by the queue. Note that we are able to type-hint dependencies on the handle method of the job. The Laravel service container automatically injects these dependencies.

If you would like to take total control over how the container injects dependencies into the handle method, you may use the container's bindMethod method. The bindMethod method accepts a callback which receives the job and the container. Within the callback, you are free to invoke the handle method however you wish. Typically, you should call this method from the boot method of your App\Providers\AppServiceProvider service provider:

1use App\Jobs\ProcessPodcast;
2use App\Services\AudioProcessor;
3use Illuminate\Contracts\Foundation\Application;
4 
5$this->app->bindMethod([ProcessPodcast::class, 'handle'], function (ProcessPodcast $job, Application $app) {
6    return $job->handle($app->make(AudioProcessor::class));
7});
1use App\Jobs\ProcessPodcast;
2use App\Services\AudioProcessor;
3use Illuminate\Contracts\Foundation\Application;
4 
5$this->app->bindMethod([ProcessPodcast::class, 'handle'], function (ProcessPodcast $job, Application $app) {
6    return $job->handle($app->make(AudioProcessor::class));
7});

Queued Relationships

Because all loaded Eloquent model relationships also get serialized when a job is queued, the serialized job string can sometimes become quite large. Furthermore, when a job is deserialized and model relationships are re-retrieved from the database, they will be retrieved in their entirety. Any previous relationship constraints that were applied before the model was serialized during the job queueing process will not be applied when the job is deserialized. Therefore, if you wish to work with a subset of a given relationship, you should re-constrain that relationship within your queued job.

Or, to prevent relations from being serialized, you can call the withoutRelations method on the model when setting a property value. This method will return an instance of the model without its loaded relationships:

1/**
2 * Create a new job instance.
3 */
4public function __construct(Podcast $podcast)
5{
6    $this->podcast = $podcast->withoutRelations();
7}
1/**
2 * Create a new job instance.
3 */
4public function __construct(Podcast $podcast)
5{
6    $this->podcast = $podcast->withoutRelations();
7}

If you are using PHP constructor property promotion and would like to indicate that an Eloquent model should not have its relations serialized, you may use the WithoutRelations attribute:

 1use Illuminate\Queue\Attributes\WithoutRelations;
 2 
 3/**
 4 * Create a new job instance.
 5 */
 6public function __construct(
 7    #[WithoutRelations]
 8    public Podcast $podcast
 9) {
10}
 1use Illuminate\Queue\Attributes\WithoutRelations;
 2 
 3/**
 4 * Create a new job instance.
 5 */
 6public function __construct(
 7    #[WithoutRelations]
 8    public Podcast $podcast
 9) {
10}

If a job receives a collection or array of Eloquent models instead of a single model, the models within that collection will not have their relationships restored when the job is deserialized and executed. This is to prevent excessive resource usage on jobs that deal with large numbers of models.

Unique Jobs

Sometimes, you may want to ensure that only one instance of a specific job is on the queue at any point in time. You may do so by implementing the ShouldBeUnique interface on your job class. This interface does not require you to define any additional methods on your class:

1<?php
2 
3use Illuminate\Contracts\Queue\ShouldQueue;
4use Illuminate\Contracts\Queue\ShouldBeUnique;
5 
6class UpdateSearchIndex implements ShouldQueue, ShouldBeUnique
7{
8    ...
9}
1<?php
2 
3use Illuminate\Contracts\Queue\ShouldQueue;
4use Illuminate\Contracts\Queue\ShouldBeUnique;
5 
6class UpdateSearchIndex implements ShouldQueue, ShouldBeUnique
7{
8    ...
9}

In the example above, the UpdateSearchIndex job is unique. So, the job will not be dispatched if another instance of the job is already on the queue and has not finished processing.

In certain cases, you may want to define a specific "key" that makes the job unique or you may want to specify a timeout beyond which the job no longer stays unique. To accomplish this, you may define uniqueId and uniqueFor properties or methods on your job class:

 1<?php
 2 
 3use App\Models\Product;
 4use Illuminate\Contracts\Queue\ShouldQueue;
 5use Illuminate\Contracts\Queue\ShouldBeUnique;
 6 
 7class UpdateSearchIndex implements ShouldQueue, ShouldBeUnique
 8{
 9    /**
10     * The product instance.
11     *
12     * @var \App\Product
13     */
14    public $product;
15 
16    /**
17     * The number of seconds after which the job's unique lock will be released.
18     *
19     * @var int
20     */
21    public $uniqueFor = 3600;
22 
23    /**
24     * Get the unique ID for the job.
25     */
26    public function uniqueId(): string
27    {
28        return $this->product->id;
29    }
30}
 1<?php
 2 
 3use App\Models\Product;
 4use Illuminate\Contracts\Queue\ShouldQueue;
 5use Illuminate\Contracts\Queue\ShouldBeUnique;
 6 
 7class UpdateSearchIndex implements ShouldQueue, ShouldBeUnique
 8{
 9    /**
10     * The product instance.
11     *
12     * @var \App\Product
13     */
14    public $product;
15 
16    /**
17     * The number of seconds after which the job's unique lock will be released.
18     *
19     * @var int
20     */
21    public $uniqueFor = 3600;
22 
23    /**
24     * Get the unique ID for the job.
25     */
26    public function uniqueId(): string
27    {
28        return $this->product->id;
29    }
30}

In the example above, the UpdateSearchIndex job is unique by a product ID. So, any new dispatches of the job with the same product ID will be ignored until the existing job has completed processing. In addition, if the existing job is not processed within one hour, the unique lock will be released and another job with the same unique key can be dispatched to the queue.

Keeping Jobs Unique Until Processing Begins

By default, unique jobs are "unlocked" after a job completes processing or fails all of its retry attempts. However, there may be situations where you would like your job to unlock immediately before it is processed. To accomplish this, your job should implement the ShouldBeUniqueUntilProcessing contract instead of the ShouldBeUnique contract:

 1<?php
 2 
 3use App\Models\Product;
 4use Illuminate\Contracts\Queue\ShouldQueue;
 5use Illuminate\Contracts\Queue\ShouldBeUniqueUntilProcessing;
 6 
 7class UpdateSearchIndex implements ShouldQueue, ShouldBeUniqueUntilProcessing
 8{
 9    // ...
10}
 1<?php
 2 
 3use App\Models\Product;
 4use Illuminate\Contracts\Queue\ShouldQueue;
 5use Illuminate\Contracts\Queue\ShouldBeUniqueUntilProcessing;
 6 
 7class UpdateSearchIndex implements ShouldQueue, ShouldBeUniqueUntilProcessing
 8{
 9    // ...
10}

Unique Job Locks

Behind the scenes, when a ShouldBeUnique job is dispatched, Laravel attempts to acquire a lock with the uniqueId key. If the lock is not acquired, the job is not dispatched. This lock is released when the job completes processing or fails all of its retry attempts. By default, Laravel will use the default cache driver to obtain this lock. However, if you wish to use another driver for acquiring the lock, you may define a uniqueVia method that returns the cache driver that should be used:

 1use Illuminate\Contracts\Cache\Repository;
 2use Illuminate\Support\Facades\Cache;
 3 
 4class UpdateSearchIndex implements ShouldQueue, ShouldBeUnique
 5{
 6    ...
 7 
 8    /**
 9     * Get the cache driver for the unique job lock.
10     */
11    public function uniqueVia(): Repository
12    {
13        return Cache::driver('redis');
14    }
15}
 1use Illuminate\Contracts\Cache\Repository;
 2use Illuminate\Support\Facades\Cache;
 3 
 4class UpdateSearchIndex implements ShouldQueue, ShouldBeUnique
 5{
 6    ...
 7 
 8    /**
 9     * Get the cache driver for the unique job lock.
10     */
11    public function uniqueVia(): Repository
12    {
13        return Cache::driver('redis');
14    }
15}

Encrypted Jobs

Laravel allows you to ensure the privacy and integrity of a job's data via encryption. To get started, simply add the ShouldBeEncrypted interface to the job class. Once this interface has been added to the class, Laravel will automatically encrypt your job before pushing it onto a queue:

1<?php
2 
3use Illuminate\Contracts\Queue\ShouldBeEncrypted;
4use Illuminate\Contracts\Queue\ShouldQueue;
5 
6class UpdateSearchIndex implements ShouldQueue, ShouldBeEncrypted
7{
8    // ...
9}
1<?php
2 
3use Illuminate\Contracts\Queue\ShouldBeEncrypted;
4use Illuminate\Contracts\Queue\ShouldQueue;
5 
6class UpdateSearchIndex implements ShouldQueue, ShouldBeEncrypted
7{
8    // ...
9}

Job Middleware

Job middleware allow you to wrap custom logic around the execution of queued jobs, reducing boilerplate in the jobs themselves. For example, consider the following handle method which leverages Laravel's Redis rate limiting features to allow only one job to process every five seconds:

 1use Illuminate\Support\Facades\Redis;
 2 
 3/**
 4 * Execute the job.
 5 */
 6public function handle(): void
 7{
 8    Redis::throttle('key')->block(0)->allow(1)->every(5)->then(function () {
 9        info('Lock obtained...');
10 
11        // Handle job...
12    }, function () {
13        // Could not obtain lock...
14 
15        return $this->release(5);
16    });
17}
 1use Illuminate\Support\Facades\Redis;
 2 
 3/**
 4 * Execute the job.
 5 */
 6public function handle(): void
 7{
 8    Redis::throttle('key')->block(0)->allow(1)->every(5)->then(function () {
 9        info('Lock obtained...');
10 
11        // Handle job...
12    }, function () {
13        // Could not obtain lock...
14 
15        return $this->release(5);
16    });
17}

While this code is valid, the implementation of the handle method becomes noisy since it is cluttered with Redis rate limiting logic. In addition, this rate limiting logic must be duplicated for any other jobs that we want to rate limit.

Instead of rate limiting in the handle method, we could define a job middleware that handles rate limiting. Laravel does not have a default location for job middleware, so you are welcome to place job middleware anywhere in your application. In this example, we will place the middleware in an app/Jobs/Middleware directory:

 1<?php
 2 
 3namespace App\Jobs\Middleware;
 4 
 5use Closure;
 6use Illuminate\Support\Facades\Redis;
 7 
 8class RateLimited
 9{
10    /**
11     * Process the queued job.
12     *
13     * @param  \Closure(object): void  $next
14     */
15    public function handle(object $job, Closure $next): void
16    {
17        Redis::throttle('key')
18                ->block(0)->allow(1)->every(5)
19                ->then(function () use ($job, $next) {
20                    // Lock obtained...
21 
22                    $next($job);
23                }, function () use ($job) {
24                    // Could not obtain lock...
25 
26                    $job->release(5);
27                });
28    }
29}
 1<?php
 2 
 3namespace App\Jobs\Middleware;
 4 
 5use Closure;
 6use Illuminate\Support\Facades\Redis;
 7 
 8class RateLimited
 9{
10    /**
11     * Process the queued job.
12     *
13     * @param  \Closure(object): void  $next
14     */
15    public function handle(object $job, Closure $next): void
16    {
17        Redis::throttle('key')
18                ->block(0)->allow(1)->every(5)
19                ->then(function () use ($job, $next) {
20                    // Lock obtained...
21 
22                    $next($job);
23                }, function () use ($job) {
24                    // Could not obtain lock...
25 
26                    $job->release(5);
27                });
28    }
29}

As you can see, like route middleware, job middleware receive the job being processed and a callback that should be invoked to continue processing the job.

After creating job middleware, they may be attached to a job by returning them from the job's middleware method. This method does not exist on jobs scaffolded by the make:job Artisan command, so you will need to manually add it to your job class:

 1use App\Jobs\Middleware\RateLimited;
 2 
 3/**
 4 * Get the middleware the job should pass through.
 5 *
 6 * @return array<int, object>
 7 */
 8public function middleware(): array
 9{
10    return [new RateLimited];
11}
 1use App\Jobs\Middleware\RateLimited;
 2 
 3/**
 4 * Get the middleware the job should pass through.
 5 *
 6 * @return array<int, object>
 7 */
 8public function middleware(): array
 9{
10    return [new RateLimited];
11}

Rate Limiting

Although we just demonstrated how to write your own rate limiting job middleware, Laravel actually includes a rate limiting middleware that you may utilize to rate limit jobs. Like route rate limiters, job rate limiters are defined using the RateLimiter facade's for method.

For example, you may wish to allow users to backup their data once per hour while imposing no such limit on premium customers. To accomplish this, you may define a RateLimiter in the boot method of your AppServiceProvider:

 1use Illuminate\Cache\RateLimiting\Limit;
 2use Illuminate\Support\Facades\RateLimiter;
 3 
 4/**
 5 * Bootstrap any application services.
 6 */
 7public function boot(): void
 8{
 9    RateLimiter::for('backups', function (object $job) {
10        return $job->user->vipCustomer()
11                    ? Limit::none()
12                    : Limit::perHour(1)->by($job->user->id);
13    });
14}
 1use Illuminate\Cache\RateLimiting\Limit;
 2use Illuminate\Support\Facades\RateLimiter;
 3 
 4/**
 5 * Bootstrap any application services.
 6 */
 7public function boot(): void
 8{
 9    RateLimiter::for('backups', function (object $job) {
10        return $job->user->vipCustomer()
11                    ? Limit::none()
12                    : Limit::perHour(1)->by($job->user->id);
13    });
14}

In the example above, we defined an hourly rate limit; however, you may easily define a rate limit based on minutes using the perMinute method. In addition, you may pass any value you wish to the by method of the rate limit; however, this value is most often used to segment rate limits by customer:

1return Limit::perMinute(50)->by($job->user->id);
1return Limit::perMinute(50)->by($job->user->id);

Once you have defined your rate limit, you may attach the rate limiter to your job using the Illuminate\Queue\Middleware\RateLimited middleware. Each time the job exceeds the rate limit, this middleware will release the job back to the queue with an appropriate delay based on the rate limit duration.

 1use Illuminate\Queue\Middleware\RateLimited;
 2 
 3/**
 4 * Get the middleware the job should pass through.
 5 *
 6 * @return array<int, object>
 7 */
 8public function middleware(): array
 9{
10    return [new RateLimited('backups')];
11}
 1use Illuminate\Queue\Middleware\RateLimited;
 2 
 3/**
 4 * Get the middleware the job should pass through.
 5 *
 6 * @return array<int, object>
 7 */
 8public function middleware(): array
 9{
10    return [new RateLimited('backups')];
11}

Releasing a rate limited job back onto the queue will still increment the job's total number of attempts. You may wish to tune your tries and maxExceptions properties on your job class accordingly. Or, you may wish to use the retryUntil method to define the amount of time until the job should no longer be attempted.

If you do not want a job to be retried when it is rate limited, you may use the dontRelease method:

1/**
2 * Get the middleware the job should pass through.
3 *
4 * @return array<int, object>
5 */
6public function middleware(): array
7{
8    return [(new RateLimited('backups'))->dontRelease()];
9}
1/**
2 * Get the middleware the job should pass through.
3 *
4 * @return array<int, object>
5 */
6public function middleware(): array
7{
8    return [(new RateLimited('backups'))->dontRelease()];
9}

Preventing Job Overlaps

Laravel includes an Illuminate\Queue\Middleware\WithoutOverlapping middleware that allows you to prevent job overlaps based on an arbitrary key. This can be helpful when a queued job is modifying a resource that should only be modified by one job at a time.

For example, let's imagine you have a queued job that updates a user's credit score and you want to prevent credit score update job overlaps for the same user ID. To accomplish this, you can return the WithoutOverlapping middleware from your job's middleware method:

 1use Illuminate\Queue\Middleware\WithoutOverlapping;
 2 
 3/**
 4 * Get the middleware the job should pass through.
 5 *
 6 * @return array<int, object>
 7 */
 8public function middleware(): array
 9{
10    return [new WithoutOverlapping($this->user->id)];
11}
 1use Illuminate\Queue\Middleware\WithoutOverlapping;
 2 
 3/**
 4 * Get the middleware the job should pass through.
 5 *
 6 * @return array<int, object>
 7 */
 8public function middleware(): array
 9{
10    return [new WithoutOverlapping($this->user->id)];
11}

Any overlapping jobs of the same type will be released back to the queue. You may also specify the number of seconds that must elapse before the released job will be attempted again:

1/**
2 * Get the middleware the job should pass through.
3 *
4 * @return array<int, object>
5 */
6public function middleware(): array
7{
8    return [(new WithoutOverlapping($this->order->id))->releaseAfter(60)];
9}
1/**
2 * Get the middleware the job should pass through.
3 *
4 * @return array<int, object>
5 */
6public function middleware(): array
7{
8    return [(new WithoutOverlapping($this->order->id))->releaseAfter(60)];
9}

If you wish to immediately delete any overlapping jobs so that they will not be retried, you may use the dontRelease method:

1/**
2 * Get the middleware the job should pass through.
3 *
4 * @return array<int, object>
5 */
6public function middleware(): array
7{
8    return [(new WithoutOverlapping($this->order->id))->dontRelease()];
9}
1/**
2 * Get the middleware the job should pass through.
3 *
4 * @return array<int, object>
5 */
6public function middleware(): array
7{
8    return [(new WithoutOverlapping($this->order->id))->dontRelease()];
9}

The WithoutOverlapping middleware is powered by Laravel's atomic lock feature. Sometimes, your job may unexpectedly fail or timeout in such a way that the lock is not released. Therefore, you may explicitly define a lock expiration time using the expireAfter method. For example, the example below will instruct Laravel to release the WithoutOverlapping lock three minutes after the job has started processing:

1/**
2 * Get the middleware the job should pass through.
3 *
4 * @return array<int, object>
5 */
6public function middleware(): array
7{
8    return [(new WithoutOverlapping($this->order->id))->expireAfter(180)];
9}
1/**
2 * Get the middleware the job should pass through.
3 *
4 * @return array<int, object>
5 */
6public function middleware(): array
7{
8    return [(new WithoutOverlapping($this->order->id))->expireAfter(180)];
9}

Sharing Lock Keys Across Job Classes

By default, the WithoutOverlapping middleware will only prevent overlapping jobs of the same class. So, although two different job classes may use the same lock key, they will not be prevented from overlapping. However, you can instruct Laravel to apply the key across job classes using the shared method:

 1use Illuminate\Queue\Middleware\WithoutOverlapping;
 2 
 3class ProviderIsDown
 4{
 5    // ...
 6 
 7 
 8    public function middleware(): array
 9    {
10        return [
11            (new WithoutOverlapping("status:{$this->provider}"))->shared(),
12        ];
13    }
14}
15 
16class ProviderIsUp
17{
18    // ...
19 
20 
21    public function middleware(): array
22    {
23        return [
24            (new WithoutOverlapping("status:{$this->provider}"))->shared(),
25        ];
26    }
27}
 1use Illuminate\Queue\Middleware\WithoutOverlapping;
 2 
 3class ProviderIsDown
 4{
 5    // ...
 6 
 7 
 8    public function middleware(): array
 9    {
10        return [
11            (new WithoutOverlapping("status:{$this->provider}"))->shared(),
12        ];
13    }
14}
15 
16class ProviderIsUp
17{
18    // ...
19 
20 
21    public function middleware(): array
22    {
23        return [
24            (new WithoutOverlapping("status:{$this->provider}"))->shared(),
25        ];
26    }
27}

Throttling Exceptions

Laravel includes a Illuminate\Queue\Middleware\ThrottlesExceptions middleware that allows you to throttle exceptions. Once the job throws a given number of exceptions, all further attempts to execute the job are delayed until a specified time interval lapses. This middleware is particularly useful for jobs that interact with third-party services that are unstable.

For example, let's imagine a queued job that interacts with a third-party API that begins throwing exceptions. To throttle exceptions, you can return the ThrottlesExceptions middleware from your job's middleware method. Typically, this middleware should be paired with a job that implements time based attempts:

 1use DateTime;
 2use Illuminate\Queue\Middleware\ThrottlesExceptions;
 3 
 4/**
 5 * Get the middleware the job should pass through.
 6 *
 7 * @return array<int, object>
 8 */
 9public function middleware(): array
10{
11    return [new ThrottlesExceptions(10, 5)];
12}
13 
14/**
15 * Determine the time at which the job should timeout.
16 */
17public function retryUntil(): DateTime
18{
19    return now()->addMinutes(5);
20}
 1use DateTime;
 2use Illuminate\Queue\Middleware\ThrottlesExceptions;
 3 
 4/**
 5 * Get the middleware the job should pass through.
 6 *
 7 * @return array<int, object>
 8 */
 9public function middleware(): array
10{
11    return [new ThrottlesExceptions(10, 5)];
12}
13 
14/**
15 * Determine the time at which the job should timeout.
16 */
17public function retryUntil(): DateTime
18{
19    return now()->addMinutes(5);
20}

The first constructor argument accepted by the middleware is the number of exceptions the job can throw before being throttled, while the second constructor argument is the number of minutes that should elapse before the job is attempted again once it has been throttled. In the code example above, if the job throws 10 exceptions within 5 minutes, we will wait 5 minutes before attempting the job again.

When a job throws an exception but the exception threshold has not yet been reached, the job will typically be retried immediately. However, you may specify the number of minutes such a job should be delayed by calling the backoff method when attaching the middleware to the job:

 1use Illuminate\Queue\Middleware\ThrottlesExceptions;
 2 
 3/**
 4 * Get the middleware the job should pass through.
 5 *
 6 * @return array<int, object>
 7 */
 8public function middleware(): array
 9{
10    return [(new ThrottlesExceptions(10, 5))->backoff(5)];
11}
 1use Illuminate\Queue\Middleware\ThrottlesExceptions;
 2 
 3/**
 4 * Get the middleware the job should pass through.
 5 *
 6 * @return array<int, object>
 7 */
 8public function middleware(): array
 9{
10    return [(new ThrottlesExceptions(10, 5))->backoff(5)];
11}

Internally, this middleware uses Laravel's cache system to implement rate limiting, and the job's class name is utilized as the cache "key". You may override this key by calling the by method when attaching the middleware to your job. This may be useful if you have multiple jobs interacting with the same third-party service and you would like them to share a common throttling "bucket":

 1use Illuminate\Queue\Middleware\ThrottlesExceptions;
 2 
 3/**
 4 * Get the middleware the job should pass through.
 5 *
 6 * @return array<int, object>
 7 */
 8public function middleware(): array
 9{
10    return [(new ThrottlesExceptions(10, 10))->by('key')];
11}
 1use Illuminate\Queue\Middleware\ThrottlesExceptions;
 2 
 3/**
 4 * Get the middleware the job should pass through.
 5 *
 6 * @return array<int, object>
 7 */
 8public function middleware(): array
 9{
10    return [(new ThrottlesExceptions(10, 10))->by('key')];
11}

Dispatching Jobs

Once you have written your job class, you may dispatch it using the dispatch method on the job itself. The arguments passed to the dispatch method will be given to the job's constructor:

 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use App\Http\Controllers\Controller;
 6use App\Jobs\ProcessPodcast;
 7use App\Models\Podcast;
 8use Illuminate\Http\RedirectResponse;
 9use Illuminate\Http\Request;
10 
11class PodcastController extends Controller
12{
13    /**
14     * Store a new podcast.
15     */
16    public function store(Request $request): RedirectResponse
17    {
18        $podcast = Podcast::create(/* ... */);
19 
20        // ...
21 
22        ProcessPodcast::dispatch($podcast);
23 
24        return redirect('/podcasts');
25    }
26}
 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use App\Http\Controllers\Controller;
 6use App\Jobs\ProcessPodcast;
 7use App\Models\Podcast;
 8use Illuminate\Http\RedirectResponse;
 9use Illuminate\Http\Request;
10 
11class PodcastController extends Controller
12{
13    /**
14     * Store a new podcast.
15     */
16    public function store(Request $request): RedirectResponse
17    {
18        $podcast = Podcast::create(/* ... */);
19 
20        // ...
21 
22        ProcessPodcast::dispatch($podcast);
23 
24        return redirect('/podcasts');
25    }
26}

If you would like to conditionally dispatch a job, you may use the dispatchIf and dispatchUnless methods:

1ProcessPodcast::dispatchIf($accountActive, $podcast);
2 
3ProcessPodcast::dispatchUnless($accountSuspended, $podcast);
1ProcessPodcast::dispatchIf($accountActive, $podcast);
2 
3ProcessPodcast::dispatchUnless($accountSuspended, $podcast);

In new Laravel applications, the sync driver is the default queue driver. This driver executes jobs synchronously in the foreground of the current request, which is often convenient during local development. If you would like to actually begin queueing jobs for background processing, you may specify a different queue driver within your application's config/queue.php configuration file.

Delayed Dispatching

If you would like to specify that a job should not be immediately available for processing by a queue worker, you may use the delay method when dispatching the job. For example, let's specify that a job should not be available for processing until 10 minutes after it has been dispatched:

 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use App\Http\Controllers\Controller;
 6use App\Jobs\ProcessPodcast;
 7use App\Models\Podcast;
 8use Illuminate\Http\RedirectResponse;
 9use Illuminate\Http\Request;
10 
11class PodcastController extends Controller
12{
13    /**
14     * Store a new podcast.
15     */
16    public function store(Request $request): RedirectResponse
17    {
18        $podcast = Podcast::create(/* ... */);
19 
20        // ...
21 
22        ProcessPodcast::dispatch($podcast)
23                    ->delay(now()->addMinutes(10));
24 
25        return redirect('/podcasts');
26    }
27}
 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use App\Http\Controllers\Controller;
 6use App\Jobs\ProcessPodcast;
 7use App\Models\Podcast;
 8use Illuminate\Http\RedirectResponse;
 9use Illuminate\Http\Request;
10 
11class PodcastController extends Controller
12{
13    /**
14     * Store a new podcast.
15     */
16    public function store(Request $request): RedirectResponse
17    {
18        $podcast = Podcast::create(/* ... */);
19 
20        // ...
21 
22        ProcessPodcast::dispatch($podcast)
23                    ->delay(now()->addMinutes(10));
24 
25        return redirect('/podcasts');
26    }
27}

Dispatching After the Response is Sent to the Browser

Alternatively, the dispatchAfterResponse method delays dispatching a job until after the HTTP response is sent to the user's browser if your web server is using FastCGI. This will still allow the user to begin using the application even though a queued job is still executing. This should typically only be used for jobs that take about a second, such as sending an email. Since they are processed within the current HTTP request, jobs dispatched in this fashion do not require a queue worker to be running in order for them to be processed:

1use App\Jobs\SendNotification;
2 
3SendNotification::dispatchAfterResponse();
1use App\Jobs\SendNotification;
2 
3SendNotification::dispatchAfterResponse();

You may also dispatch a closure and chain the afterResponse method onto the dispatch helper to execute a closure after the HTTP response has been sent to the browser:

1use App\Mail\WelcomeMessage;
2use Illuminate\Support\Facades\Mail;
3 
4dispatch(function () {
5    Mail::to('[email protected]')->send(new WelcomeMessage);
6})->afterResponse();
1use App\Mail\WelcomeMessage;
2use Illuminate\Support\Facades\Mail;
3 
4dispatch(function () {
5    Mail::to('[email protected]')->send(new WelcomeMessage);
6})->afterResponse();

Synchronous Dispatching

If you would like to dispatch a job immediately (synchronously), you may use the dispatchSync method. When using this method, the job will not be queued and will be executed immediately within the current process:

 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use App\Http\Controllers\Controller;
 6use App\Jobs\ProcessPodcast;
 7use App\Models\Podcast;
 8use Illuminate\Http\RedirectResponse;
 9use Illuminate\Http\Request;
10 
11class PodcastController extends Controller
12{
13    /**
14     * Store a new podcast.
15     */
16    public function store(Request $request): RedirectResponse
17    {
18        $podcast = Podcast::create(/* ... */);
19 
20        // Create podcast...
21 
22        ProcessPodcast::dispatchSync($podcast);
23 
24        return redirect('/podcasts');
25    }
26}
 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use App\Http\Controllers\Controller;
 6use App\Jobs\ProcessPodcast;
 7use App\Models\Podcast;
 8use Illuminate\Http\RedirectResponse;
 9use Illuminate\Http\Request;
10 
11class PodcastController extends Controller
12{
13    /**
14     * Store a new podcast.
15     */
16    public function store(Request $request): RedirectResponse
17    {
18        $podcast = Podcast::create(/* ... */);
19 
20        // Create podcast...
21 
22        ProcessPodcast::dispatchSync($podcast);
23 
24        return redirect('/podcasts');
25    }
26}

Jobs & Database Transactions

While it is perfectly fine to dispatch jobs within database transactions, you should take special care to ensure that your job will actually be able to execute successfully. When dispatching a job within a transaction, it is possible that the job will be processed by a worker before the parent transaction has committed. When this happens, any updates you have made to models or database records during the database transaction(s) may not yet be reflected in the database. In addition, any models or database records created within the transaction(s) may not exist in the database.

Thankfully, Laravel provides several methods of working around this problem. First, you may set the after_commit connection option in your queue connection's configuration array:

1'redis' => [
2    'driver' => 'redis',
3    // ...
4    'after_commit' => true,
5],
1'redis' => [
2    'driver' => 'redis',
3    // ...
4    'after_commit' => true,
5],

When the after_commit option is true, you may dispatch jobs within database transactions; however, Laravel will wait until the open parent database transactions have been committed before actually dispatching the job. Of course, if no database transactions are currently open, the job will be dispatched immediately.

If a transaction is rolled back due to an exception that occurs during the transaction, the jobs that were dispatched during that transaction will be discarded.

Specifying Commit Dispatch Behavior Inline

If you do not set the after_commit queue connection configuration option to true, you may still indicate that a specific job should be dispatched after all open database transactions have been committed. To accomplish this, you may chain the afterCommit method onto your dispatch operation:

1use App\Jobs\ProcessPodcast;
2 
3ProcessPodcast::dispatch($podcast)->afterCommit();
1use App\Jobs\ProcessPodcast;
2 
3ProcessPodcast::dispatch($podcast)->afterCommit();

Likewise, if the after_commit configuration option is set to true, you may indicate that a specific job should be dispatched immediately without waiting for any open database transactions to commit:

1ProcessPodcast::dispatch($podcast)->beforeCommit();
1ProcessPodcast::dispatch($podcast)->beforeCommit();

Job Chaining

Job chaining allows you to specify a list of queued jobs that should be run in sequence after the primary job has executed successfully. If one job in the sequence fails, the rest of the jobs will not be run. To execute a queued job chain, you may use the chain method provided by the Bus facade. Laravel's command bus is a lower level component that queued job dispatching is built on top of:

 1use App\Jobs\OptimizePodcast;
 2use App\Jobs\ProcessPodcast;
 3use App\Jobs\ReleasePodcast;
 4use Illuminate\Support\Facades\Bus;
 5 
 6Bus::chain([
 7    new ProcessPodcast,
 8    new OptimizePodcast,
 9    new ReleasePodcast,
10])->dispatch();
 1use App\Jobs\OptimizePodcast;
 2use App\Jobs\ProcessPodcast;
 3use App\Jobs\ReleasePodcast;
 4use Illuminate\Support\Facades\Bus;
 5 
 6Bus::chain([
 7    new ProcessPodcast,
 8    new OptimizePodcast,
 9    new ReleasePodcast,
10])->dispatch();

In addition to chaining job class instances, you may also chain closures:

1Bus::chain([
2    new ProcessPodcast,
3    new OptimizePodcast,
4    function () {
5        Podcast::update(/* ... */);
6    },
7])->dispatch();
1Bus::chain([
2    new ProcessPodcast,
3    new OptimizePodcast,
4    function () {
5        Podcast::update(/* ... */);
6    },
7])->dispatch();

Chain Connection and Queue

If you would like to specify the connection and queue that should be used for the chained jobs, you may use the onConnection and onQueue methods. These methods specify the queue connection and queue name that should be used unless the queued job is explicitly assigned a different connection / queue:

1Bus::chain([
2    new ProcessPodcast,
3    new OptimizePodcast,
4    new ReleasePodcast,
5])->onConnection('redis')->onQueue('podcasts')->dispatch();
1Bus::chain([
2    new ProcessPodcast,
3    new OptimizePodcast,
4    new ReleasePodcast,
5])->onConnection('redis')->onQueue('podcasts')->dispatch();

Chain Failures

When chaining jobs, you may use the catch method to specify a closure that should be invoked if a job within the chain fails. The given callback will receive the Throwable instance that caused the job failure:

 1use Illuminate\Support\Facades\Bus;
 2use Throwable;
 3 
 4Bus::chain([
 5    new ProcessPodcast,
 6    new OptimizePodcast,
 7    new ReleasePodcast,
 8])->catch(function (Throwable $e) {
 9    // A job within the chain has failed...
10})->dispatch();
 1use Illuminate\Support\Facades\Bus;
 2use Throwable;
 3 
 4Bus::chain([
 5    new ProcessPodcast,
 6    new OptimizePodcast,
 7    new ReleasePodcast,
 8])->catch(function (Throwable $e) {
 9    // A job within the chain has failed...
10})->dispatch();

Customizing The Queue and Connection

Dispatching to a Particular Queue

By pushing jobs to different queues, you may "categorize" your queued jobs and even prioritize how many workers you assign to various queues. Keep in mind, this does not push jobs to different queue "connections" as defined by your queue configuration file, but only to specific queues within a single connection. To specify the queue, use the onQueue method when dispatching the job:

 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use App\Http\Controllers\Controller;
 6use App\Jobs\ProcessPodcast;
 7use App\Models\Podcast;
 8use Illuminate\Http\RedirectResponse;
 9use Illuminate\Http\Request;
10 
11class PodcastController extends Controller
12{
13    /**
14     * Store a new podcast.
15     */
16    public function store(Request $request): RedirectResponse
17    {
18        $podcast = Podcast::create(/* ... */);
19 
20        // Create podcast...
21 
22        ProcessPodcast::dispatch($podcast)->onQueue('processing');
23 
24        return redirect('/podcasts');
25    }
26}
 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use App\Http\Controllers\Controller;
 6use App\Jobs\ProcessPodcast;
 7use App\Models\Podcast;
 8use Illuminate\Http\RedirectResponse;
 9use Illuminate\Http\Request;
10 
11class PodcastController extends Controller
12{
13    /**
14     * Store a new podcast.
15     */
16    public function store(Request $request): RedirectResponse
17    {
18        $podcast = Podcast::create(/* ... */);
19 
20        // Create podcast...
21 
22        ProcessPodcast::dispatch($podcast)->onQueue('processing');
23 
24        return redirect('/podcasts');
25    }
26}

Alternatively, you may specify the job's queue by calling the onQueue method within the job's constructor:

 1<?php
 2 
 3namespace App\Jobs;
 4 
 5 use Illuminate\Bus\Queueable;
 6 use Illuminate\Contracts\Queue\ShouldQueue;
 7 use Illuminate\Foundation\Bus\Dispatchable;
 8 use Illuminate\Queue\InteractsWithQueue;
 9 use Illuminate\Queue\SerializesModels;
10 
11class ProcessPodcast implements ShouldQueue
12{
13    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
14 
15    /**
16     * Create a new job instance.
17     */
18    public function __construct()
19    {
20        $this->onQueue('processing');
21    }
22}
 1<?php
 2 
 3namespace App\Jobs;
 4 
 5 use Illuminate\Bus\Queueable;
 6 use Illuminate\Contracts\Queue\ShouldQueue;
 7 use Illuminate\Foundation\Bus\Dispatchable;
 8 use Illuminate\Queue\InteractsWithQueue;
 9 use Illuminate\Queue\SerializesModels;
10 
11class ProcessPodcast implements ShouldQueue
12{
13    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
14 
15    /**
16     * Create a new job instance.
17     */
18    public function __construct()
19    {
20        $this->onQueue('processing');
21    }
22}

Dispatching to a Particular Connection

If your application interacts with multiple queue connections, you may specify which connection to push a job to using the onConnection method:

 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use App\Http\Controllers\Controller;
 6use App\Jobs\ProcessPodcast;
 7use App\Models\Podcast;
 8use Illuminate\Http\RedirectResponse;
 9use Illuminate\Http\Request;
10 
11class PodcastController extends Controller
12{
13    /**
14     * Store a new podcast.
15     */
16    public function store(Request $request): RedirectResponse
17    {
18        $podcast = Podcast::create(/* ... */);
19 
20        // Create podcast...
21 
22        ProcessPodcast::dispatch($podcast)->onConnection('sqs');
23 
24        return redirect('/podcasts');
25    }
26}
 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use App\Http\Controllers\Controller;
 6use App\Jobs\ProcessPodcast;
 7use App\Models\Podcast;
 8use Illuminate\Http\RedirectResponse;
 9use Illuminate\Http\Request;
10 
11class PodcastController extends Controller
12{
13    /**
14     * Store a new podcast.
15     */
16    public function store(Request $request): RedirectResponse
17    {
18        $podcast = Podcast::create(/* ... */);
19 
20        // Create podcast...
21 
22        ProcessPodcast::dispatch($podcast)->onConnection('sqs');
23 
24        return redirect('/podcasts');
25    }
26}

You may chain the onConnection and onQueue methods together to specify the connection and the queue for a job:

1ProcessPodcast::dispatch($podcast)
2              ->onConnection('sqs')
3              ->onQueue('processing');
1ProcessPodcast::dispatch($podcast)
2              ->onConnection('sqs')
3              ->onQueue('processing');

Alternatively, you may specify the job's connection by calling the onConnection method within the job's constructor:

 1<?php
 2 
 3namespace App\Jobs;
 4 
 5 use Illuminate\Bus\Queueable;
 6 use Illuminate\Contracts\Queue\ShouldQueue;
 7 use Illuminate\Foundation\Bus\Dispatchable;
 8 use Illuminate\Queue\InteractsWithQueue;
 9 use Illuminate\Queue\SerializesModels;
10 
11class ProcessPodcast implements ShouldQueue
12{
13    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
14 
15    /**
16     * Create a new job instance.
17     */
18    public function __construct()
19    {
20        $this->onConnection('sqs');
21    }
22}
 1<?php
 2 
 3namespace App\Jobs;
 4 
 5 use Illuminate\Bus\Queueable;
 6 use Illuminate\Contracts\Queue\ShouldQueue;
 7 use Illuminate\Foundation\Bus\Dispatchable;
 8 use Illuminate\Queue\InteractsWithQueue;
 9 use Illuminate\Queue\SerializesModels;
10 
11class ProcessPodcast implements ShouldQueue
12{
13    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
14 
15    /**
16     * Create a new job instance.
17     */
18    public function __construct()
19    {
20        $this->onConnection('sqs');
21    }
22}

Specifying Max Job Attempts / Timeout Values

Max Attempts

If one of your queued jobs is encountering an error, you likely do not want it to keep retrying indefinitely. Therefore, Laravel provides various ways to specify how many times or for how long a job may be attempted.

One approach to specifying the maximum number of times a job may be attempted is via the --tries switch on the Artisan command line. This will apply to all jobs processed by the worker unless the job being processed specifies the number of times it may be attempted:

1php artisan queue:work --tries=3
1php artisan queue:work --tries=3

If a job exceeds its maximum number of attempts, it will be considered a "failed" job. For more information on handling failed jobs, consult the failed job documentation. If --tries=0 is provided to the queue:work command, the job will be retried indefinitely.

You may take a more granular approach by defining the maximum number of times a job may be attempted on the job class itself. If the maximum number of attempts is specified on the job, it will take precedence over the --tries value provided on the command line:

 1<?php
 2 
 3namespace App\Jobs;
 4 
 5class ProcessPodcast implements ShouldQueue
 6{
 7    /**
 8     * The number of times the job may be attempted.
 9     *
10     * @var int
11     */
12    public $tries = 5;
13}
 1<?php
 2 
 3namespace App\Jobs;
 4 
 5class ProcessPodcast implements ShouldQueue
 6{
 7    /**
 8     * The number of times the job may be attempted.
 9     *
10     * @var int
11     */
12    public $tries = 5;
13}

If you need dynamic control over a particular job's maximum attempts, you may define a tries method on the job:

1/**
2 * Determine number of times the job may be attempted.
3 */
4public function tries(): int
5{
6    return 5;
7}
1/**
2 * Determine number of times the job may be attempted.
3 */
4public function tries(): int
5{
6    return 5;
7}

Time Based Attempts

As an alternative to defining how many times a job may be attempted before it fails, you may define a time at which the job should no longer be attempted. This allows a job to be attempted any number of times within a given time frame. To define the time at which a job should no longer be attempted, add a retryUntil method to your job class. This method should return a DateTime instance:

1use DateTime;
2 
3/**
4 * Determine the time at which the job should timeout.
5 */
6public function retryUntil(): DateTime
7{
8    return now()->addMinutes(10);
9}
1use DateTime;
2 
3/**
4 * Determine the time at which the job should timeout.
5 */
6public function retryUntil(): DateTime
7{
8    return now()->addMinutes(10);
9}

Max Exceptions

Sometimes you may wish to specify that a job may be attempted many times, but should fail if the retries are triggered by a given number of unhandled exceptions (as opposed to being released by the release method directly). To accomplish this, you may define a maxExceptions property on your job class:

 1<?php
 2 
 3namespace App\Jobs;
 4 
 5use Illuminate\Support\Facades\Redis;
 6 
 7class ProcessPodcast implements ShouldQueue
 8{
 9    /**
10     * The number of times the job may be attempted.
11     *
12     * @var int
13     */
14    public $tries = 25;
15 
16    /**
17     * The maximum number of unhandled exceptions to allow before failing.
18     *
19     * @var int
20     */
21    public $maxExceptions = 3;
22 
23    /**
24     * Execute the job.
25     */
26    public function handle(): void
27    {
28        Redis::throttle('key')->allow(10)->every(60)->then(function () {
29            // Lock obtained, process the podcast...
30        }, function () {
31            // Unable to obtain lock...
32            return $this->release(10);
33        });
34    }
35}
 1<?php
 2 
 3namespace App\Jobs;
 4 
 5use Illuminate\Support\Facades\Redis;
 6 
 7class ProcessPodcast implements ShouldQueue
 8{
 9    /**
10     * The number of times the job may be attempted.
11     *
12     * @var int
13     */
14    public $tries = 25;
15 
16    /**
17     * The maximum number of unhandled exceptions to allow before failing.
18     *
19     * @var int
20     */
21    public $maxExceptions = 3;
22 
23    /**
24     * Execute the job.
25     */
26    public function handle(): void
27    {
28        Redis::throttle('key')->allow(10)->every(60)->then(function () {
29            // Lock obtained, process the podcast...
30        }, function () {
31            // Unable to obtain lock...
32            return $this->release(10);
33        });
34    }
35}

In this example, the job is released for ten seconds if the application is unable to obtain a Redis lock and will continue to be retried up to 25 times. However, the job will fail if three unhandled exceptions are thrown by the job.

Timeout

Often, you know roughly how long you expect your queued jobs to take. For this reason, Laravel allows you to specify a "timeout" value. By default, the timeout value is 60 seconds. If a job is processing for longer than the number of seconds specified by the timeout value, the worker processing the job will exit with an error. Typically, the worker will be restarted automatically by a process manager configured on your server.

The maximum number of seconds that jobs can run may be specified using the --timeout switch on the Artisan command line:

1php artisan queue:work --timeout=30
1php artisan queue:work --timeout=30

If the job exceeds its maximum attempts by continually timing out, it will be marked as failed.

You may also define the maximum number of seconds a job should be allowed to run on the job class itself. If the timeout is specified on the job, it will take precedence over any timeout specified on the command line:

 1<?php
 2 
 3namespace App\Jobs;
 4 
 5class ProcessPodcast implements ShouldQueue
 6{
 7    /**
 8     * The number of seconds the job can run before timing out.
 9     *
10     * @var int
11     */
12    public $timeout = 120;
13}
 1<?php
 2 
 3namespace App\Jobs;
 4 
 5class ProcessPodcast implements ShouldQueue
 6{
 7    /**
 8     * The number of seconds the job can run before timing out.
 9     *
10     * @var int
11     */
12    public $timeout = 120;
13}

Sometimes, IO blocking processes such as sockets or outgoing HTTP connections may not respect your specified timeout. Therefore, when using these features, you should always attempt to specify a timeout using their APIs as well. For example, when using Guzzle, you should always specify a connection and request timeout value.

Failing on Timeout

If you would like to indicate that a job should be marked as failed on timeout, you may define the $failOnTimeout property on the job class:

1/**
2 * Indicate if the job should be marked as failed on timeout.
3 *
4 * @var bool
5 */
6public $failOnTimeout = true;
1/**
2 * Indicate if the job should be marked as failed on timeout.
3 *
4 * @var bool
5 */
6public $failOnTimeout = true;

Error Handling

If an exception is thrown while the job is being processed, the job will automatically be released back onto the queue so it may be attempted again. The job will continue to be released until it has been attempted the maximum number of times allowed by your application. The maximum number of attempts is defined by the --tries switch used on the queue:work Artisan command. Alternatively, the maximum number of attempts may be defined on the job class itself. More information on running the queue worker can be found below.

Manually Releasing a Job

Sometimes you may wish to manually release a job back onto the queue so that it can be attempted again at a later time. You may accomplish this by calling the release method:

1/**
2 * Execute the job.
3 */
4public function handle(): void
5{
6    // ...
7 
8    $this->release();
9}
1/**
2 * Execute the job.
3 */
4public function handle(): void
5{
6    // ...
7 
8    $this->release();
9}