Laravel 5.2 Queue Commands Explained: A Practical Guide to Queue Management
Laravel provides a built-in queue system that allows applications to process time-consuming tasks asynchronously. Common use cases include sending emails, processing uploaded files, generating reports, and handling background operations.
Laravel 5.2 provides several Artisan commands for managing queues, including starting workers, restarting background processes, and handling failed jobs.
This article explains the most commonly used Laravel 5.2 queue commands, their purposes, and when to use each one in a real production environment.
1. Understanding Laravel Queue Architecture
Before looking at individual commands, it is important to understand how Laravel queues work.
A typical queue workflow looks like this:
- The application dispatches a job.
- Laravel pushes the job into a queue backend, such as a database or Redis.
- A queue worker retrieves the job.
- The worker executes the job.
- If execution fails, Laravel can record the failure in the
failed_jobstable.
There are three important components:
| Component | Responsibility |
|---|---|
| Queue Driver | Stores pending jobs |
| Queue Worker | Retrieves and executes jobs |
| Failed Jobs Storage | Records jobs that fail during execution |
Laravel 5.2 supports several queue drivers, including sync, database, beanstalkd, and Redis.
For production environments, database or Redis is generally more suitable than the synchronous driver.
2. Queue Initialization Commands
These commands are primarily used when setting up the queue system for the first time.
2.1 queue:table
Generate a migration file for the jobs table.
php artisan queue:table
The generated migration creates the database table used by Laravel’s database queue driver.
Run the migration afterward:
php artisan migrate
When to use it:
- When configuring the database queue driver for the first time.
- When the
jobstable does not exist.
You do not need this command if you are using Redis as your queue backend.
2.2 queue:failed-table
Generate a migration file for the failed_jobs table.
php artisan queue:failed-table
Then execute:
php artisan migrate
This table stores information about failed jobs, including their connection, queue name, payload, exception details, and failure timestamp.
When to use it:
- When enabling failed job tracking.
- When setting up a new production queue environment.
- When you need to investigate and retry failed jobs.
It is recommended to configure failed job storage even when using Redis or another queue backend.
3. Queue Worker Commands
These are the commands you will use most frequently when running Laravel queues.
3.1 queue:work
Start a queue worker.
php artisan queue:work
In Laravel 5.2, queue:work can run in different modes.
For a continuously running daemon worker:
php artisan queue:work --daemon
The --daemon option keeps the worker process alive and allows it to process multiple jobs without bootstrapping the entire Laravel application for every job.
This significantly reduces overhead and improves processing efficiency.
A typical production command is:
php artisan queue:work --daemon --tries=3
You can also specify additional options:
php artisan queue:work --daemon \
--sleep=3 \
--tries=3 \
--timeout=60
| Option | Description |
|---|---|
--daemon | Run the worker as a long-lived process |
--sleep=3 | Wait 3 seconds when no jobs are available |
--tries=3 | Maximum number of attempts before failure |
--timeout=60 | Maximum execution time for a job, in seconds |
When to use it:
- Production queue processing.
- Running background jobs continuously.
- Deploying queue workers under Supervisor.
Because daemon workers keep the Laravel application in memory, they do not automatically load newly deployed application code. A graceful restart is required after deployment.
3.2 queue:listen
Start a queue listener:
php artisan queue:listen
Unlike a daemon worker, queue:listen starts a fresh application process for each job.
This means application code changes can be picked up automatically by subsequent jobs without manually restarting a long-running worker.
However, this approach introduces additional application bootstrapping overhead.
When to use it:
- Local development.
- Debugging queue jobs.
- Environments where automatically loading updated code is more important than worker performance.
For production environments with high queue throughput, queue:work --daemon is generally more efficient.
3.3 queue:restart
Gracefully restart running queue workers.
php artisan queue:restart
This is one of the most important commands when deploying Laravel applications.
In Laravel 5.2, daemon workers load application code when they start. If you deploy new code while workers are running, existing workers may continue using the old code.
The queue:restart command solves this problem.
How it works:
- Laravel writes a restart timestamp to the configured cache.
- Running workers periodically check this timestamp.
- When a worker detects a restart request, it finishes its current job.
- The worker exits gracefully.
- Supervisor starts a replacement worker if it manages the process.
Importantly, queue:restart does not immediately terminate a worker that is processing a job.
When to use it:
- After deploying new application code.
- After modifying existing Job classes.
- After modifying code used by queue workers.
- When you want to reload workers without interrupting their current jobs.
For production deployments, this command should generally be included in your deployment process.
Example:
# Deploy application code
# Refresh Composer autoload files if necessary
composer dump-autoload -o
# Gracefully restart Laravel queue workers
php artisan queue:restart
Important: queue:restart only requests workers to exit. It does not start new workers by itself. A process manager such as Supervisor should be responsible for bringing them back online.
Also ensure that the application cache used by the restart mechanism is shared with the running workers.
4. Failed Job Management Commands
Jobs can fail for various reasons:
- Database connection problems.
- Third-party API timeouts.
- Invalid application data.
- Unhandled exceptions.
- External service outages.
Laravel provides several commands to investigate and manage failed jobs.
4.1 queue:failed
List all failed jobs.
php artisan queue:failed
The output typically includes:
| Field | Description |
|---|---|
| ID | Failed job identifier |
| Connection | Queue connection |
| Queue | Queue name |
| Class | Job class |
| Failed At | Failure timestamp |
When to use it:
- When background tasks are not completing successfully.
- When investigating production errors.
- When identifying jobs that need to be retried.
4.2 queue:retry
Retry a failed job.
php artisan queue:retry 5
Here, 5 represents the failed job ID.
To retry all failed jobs:
php artisan queue:retry all
Laravel moves the selected failed jobs back into the queue for processing.
When to use it:
- After fixing a bug that caused job failures.
- After restoring an unavailable third-party service.
- When retrying jobs that failed because of temporary infrastructure problems.
Before retrying, make sure the underlying problem has been resolved.
Also consider whether the job is safe to execute more than once. Operations such as payments and order creation should use appropriate idempotency protection.
4.3 queue:forget
Delete a specific failed job record.
php artisan queue:forget 5
This removes the failed job with ID 5 from the failed_jobs table.
When to use it:
- When a failed job is no longer relevant.
- When a job contains invalid or outdated data.
- When you have investigated the failure and decided not to retry it.
Be careful: deleting the record removes the stored failure information.
4.4 queue:flush
Delete all failed job records.
php artisan queue:flush
This clears the failed job storage.
When to use it:
- When old failed jobs are no longer needed.
- During maintenance after reviewing historical failures.
- When cleaning up accumulated failed job records.
Warning: This operation is destructive. Once the records are deleted, you cannot use queue:retry to retry those jobs.
Always review failed jobs before running this command in production.
5. Recommended Production Workflow
For a Laravel 5.2 production application, a typical queue management setup looks like this:
Step 1: Configure the Queue Driver
Set the queue driver in .env:
QUEUE_DRIVER=database
For Redis:
QUEUE_DRIVER=redis
The appropriate queue backend must also be configured in config/queue.php.
Step 2: Initialize Queue Tables
If using the database driver:
php artisan queue:table
php artisan queue:failed-table
php artisan migrate
Step 3: Start Queue Workers
Use a daemon worker:
php artisan queue:work --daemon --tries=3
For production, use Supervisor to manage the worker process.
Step 4: Deploy New Code
After deploying new application code:
composer dump-autoload -o
php artisan queue:restart
Supervisor will restart workers that exit after finishing their current jobs.
Step 5: Monitor Failed Jobs
Periodically check:
php artisan queue:failed
Retry jobs after resolving their underlying problems:
php artisan queue:retry all
Only retry jobs when doing so is safe.
6. Common Queue Commands Cheat Sheet
Here is a quick reference for the commands covered in this article.
| Command | Purpose | Typical Usage |
|---|---|---|
queue:table | Generate jobs table migration | Initial setup |
queue:failed-table | Generate failed jobs migration | Initial setup |
queue:work | Start a queue worker | Queue processing |
queue:listen | Listen for and process jobs | Development |
queue:restart | Gracefully restart workers | After deployment |
queue:failed | List failed jobs | Troubleshooting |
queue:retry | Retry failed jobs | Recovery |
queue:forget | Delete one failed job | Cleanup |
queue:flush | Delete all failed jobs | Maintenance |
7. Important Notes for Laravel 5.2
When managing queues in Laravel 5.2, keep the following points in mind:
- Daemon workers need to be restarted after deployment. They do not automatically reload modified PHP classes.
- Use Supervisor in production. It ensures that queue workers are automatically restarted when they exit.
- Use
queue:restartfor graceful restarts. It allows workers to finish their current jobs before exiting. - Monitor failed jobs regularly. Do not blindly retry all failed jobs without understanding why they failed.
- Configure appropriate timeouts and retry limits. Make sure job execution time, worker timeout, and queue visibility or retry timing are configured consistently.
Conclusion
Laravel 5.2 provides a complete set of Artisan commands for managing the queue lifecycle, from initial database setup to worker execution and failed job recovery.
For everyday production operations, the most important commands are:
# Start a queue worker
php artisan queue:work --daemon --tries=3
# Gracefully restart workers after deployment
php artisan queue:restart
# Check failed jobs
php artisan queue:failed
# Retry a failed job
php artisan queue:retry 5
Understanding these commands helps you maintain stable background processing, deploy application updates safely, and troubleshoot queue-related issues without unnecessarily interrupting running tasks.
The key takeaway: Use queue:work --daemon with Supervisor for production processing, and use queue:restart whenever you deploy updated application code.
