Implementing Laravel’s Redis Queue Driver: A Practical Guide

Desired Outcome

Set up a production‑ready job queue in Laravel 10+ that uses Redis for high‑throughput, durable background processing. After following this guide you will be able to dispatch jobs from your application, run workers that consume those jobs, and monitor their status with Laravel Horizon.

Prerequisites

• Laravel 10 or newer installed (composer create-project laravel/laravel)
• Redis server running and accessible from your app (local or remote)
• PHP 8.1+ and Composer
• Basic knowledge of Artisan commands and .env configuration

1. Configure the Redis Queue Connection

Laravel ships with a Redis queue connection out of the box. Open config/queue.php and confirm the redis driver is defined:

'redis' => [
    'driver' => 'redis',
    'connection' => 'default',
    'queue' => env('QUEUE_NAME', 'default'),
    'retry_after' => 90,
],

In your .env file set:

QUEUE_CONNECTION=redis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

Verify the connection with php artisan queue:failed --queue=default – if it returns an empty list, Redis is reachable.

2. Create a Job Class

Generate a job that will run asynchronously:

php artisan make:job EmailReminderJob --queue=default

In app/Jobs/EmailReminderJob.php, keep the payload small (IDs, strings, not whole models). Example:

class EmailReminderJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    protected int $userId;

    public function __construct(int $userId)
    {
        $this->userId = $userId;
    }

    public function handle()
    {
        $user = User::findOrFail($this->userId);
        Mail::to($user)->send(new ReminderEmail($user));
    }
}

3. Dispatch Jobs

From a controller or event listener:

EmailReminderJob::dispatch($userId);

Laravel will serialize the job and push it onto the Redis list named queues:default.

4. Run the Queue Worker

Start a worker process on the server:

php artisan queue:work redis --queue=default --tries=3 --timeout=60

• --tries=3 limits the number of retry attempts if a job fails.
• --timeout=60 aborts jobs that run longer than 60 seconds.

For production, supervise the worker with Supervisor or systemd to auto‑restart on crash.

5. Optional: Install Laravel Horizon

Horizon gives a real‑time dashboard and queue management:

composer require laravel/horizon
php artisan horizon:install
php artisan migrate
php artisan horizon

Visit /horizon to see job throughput, failures, and worker health. Horizon automatically detects the redis driver and shows the default queue.

6. Verification Checks

1. Job appearance in Redis – Open a Redis CLI and run LLEN queues:default before dispatch; it should increase by one after dispatch.
2. Worker execution – Observe Horizon or the worker console; the job should transition from queued to processing to completed.
3. Retry logic – Force a failure (e.g., throw an exception in handle) and confirm the job is retried up to the --tries count, then marked as failed.
4. Timeout enforcement – In handle, add sleep(120) and verify the worker logs a timeout and the job is requeued or failed.
5. Graceful degradation – Stop Redis (e.g., sudo systemctl stop redis) and dispatch a job. Laravel should fall back to the database driver; the job will appear in the jobs table. Restart Redis and confirm the worker picks it up.

7. Recovery Options

• Persisting Redis – Enable AOF or RDB snapshots to avoid job loss on server reboot.
• Worker restarts – Horizon’s --daemon mode or Supervisor’s autorestart=true ensures workers resume after a crash.
• Monitoring failures – Configure Horizon alerts or Laravel’s failed_jobs table to trigger notifications.
• Failover to database – Ensure QUEUE_DRIVER=database is set in .env as a fallback; run php artisan queue:work database if Redis is permanently unavailable.

Limitations & Practical Check

Redis queues store jobs as serialized PHP objects. Large payloads increase memory usage; always pass IDs or simple arrays. Horizon requires a running Redis instance; if you prefer no extra monitoring, skip it and use php artisan queue:work directly.

To double‑check your setup, run a small test script that dispatches a job, then run php artisan queue:work --once to process it immediately and confirm the expected side effect (e.g., an email is queued).

Conclusion

By following these steps you’ll have a robust, production‑grade job queue powered by Redis, with automatic retries, timeouts, and optional Horizon monitoring. This configuration scales horizontally – add more workers or Redis instances as load grows.