Queues & Background Jobs
Relevant source files
The following files were used as context for generating this wiki page:The QashierWise backend utilizes Laravel's queue system for "robust background job processing" to handle time-consuming tasks asynchronously. This architecture offloads operations like sending messages or processing data to a background process, which improves the application's response time and user experience. The system is configured to use different queue drivers, with redis being the primary choice for production, managed by a persistent worker process.
This ensures that long-running tasks do not block the main application thread, making the API more responsive.
Sources: README.md:19, docker/supervisord.conf:1-10
Architecture Overview
The background job processing follows a standard producer-consumer pattern. The Laravel application acts as the producer, dispatching jobs to a queue (broker). A dedicated queue worker, running as a separate process, acts as the consumer, pulling jobs from the queue and executing them.
The diagram below illustrates the flow of a job from dispatch to execution.
This flow is orchestrated by:
- Laravel Application: Dispatches a job to the configured queue connection (e.g.,
redis). - Redis: Acts as the message broker, holding the serialized job payload until a worker is available.
- Supervisor: A process control system that ensures the
php artisan queue:workcommand is always running. - Queue Worker: The process that retrieves jobs from Redis and executes them.
Sources: config/queue.php, docker/supervisord.conf
Queue Configuration
The primary configuration for the queue system is located in config/queue.php. This file defines the available queue connections and the default behavior.
Sources: config/queue.php
Default Connection
The default queue driver is determined by the QUEUE_CONNECTION environment variable. If not set, it defaults to sync, which executes jobs immediately and is not suitable for production. For production, redis is the intended driver.
/*
|--------------------------------------------------------------------------
| Default Queue Connection Name
|--------------------------------------------------------------------------
|
| Laravel's queue API supports an assortment of back-ends via a single
| API, giving you convenient access to each back-end using the same
| syntax for every one. Here you may define a default connection.
|
*/
'default' => env('QUEUE_CONNECTION', 'sync'),
Sources: config/queue.php:14-24
Connection Drivers
The application is configured with several connection drivers, allowing flexibility between different environments.
| Driver | Table/Queue | Description |
|---|---|---|
sync | N/A | Jobs are executed synchronously within the request cycle. Used for local development or testing. |
database | jobs | Jobs are stored in a database table. Provides persistence but is slower than in-memory drivers. |
redis | default | Jobs are pushed to a Redis list. This is the recommended driver for production due to its high performance. |
Sources: config/queue.php:26-77
Database Schema for Jobs
When using the database driver, jobs are stored in the jobs table. The schema for this table is defined in the migration file.
Sources: database/migrations/0001_01_01_000002_create_jobs_table.php
jobs Table ER Diagram
The following diagram shows the structure of the jobs table.
Column Descriptions
| Column | Type | Description |
|---|---|---|
id | bigint | The primary key for the job record. |
queue | string | The name of the queue the job was pushed to. An index is created on this column. |
payload | longtext | The JSON-encoded payload containing the serialized job class and its data. |
attempts | unsignedTinyInteger | The number of times the worker has attempted to run the job. |
reserved_at | unsignedInteger (nullable) | A UNIX timestamp indicating when a worker has reserved the job. |
available_at | unsignedInteger | A UNIX timestamp indicating when the job is available to be processed. |
created_at | unsignedInteger | A UNIX timestamp indicating when the job was created. |
Sources: database/migrations/0001_01_01_000002_create_jobs_table.php:17-24
Worker Process Management
In the Docker environment, the queue worker is managed by supervisord, a process control system that ensures the worker process remains active.
Sources: docker/supervisord.conf
Supervisor Configuration
The configuration in docker/supervisord.conf defines a program named laravel-worker that executes the queue:work Artisan command.
[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/artisan queue:work redis --verbose --tries=3 --timeout=90
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
numprocs=1
redirect_stderr=true
stdout_logfile=/var/log/worker.log
stopwaitsecs=3600
Sources: docker/supervisord.conf:1-10
Worker Command Breakdown
The command php /var/www/artisan queue:work redis --verbose --tries=3 --timeout=90 has several important options:
| Parameter | Value | Description |
|---|---|---|
queue:work | - | The Artisan command to start a queue worker. |
redis | - | Specifies that the worker should process jobs from the redis connection defined in config/queue.php. |
--verbose | - | Enables verbose output for logging. |
--tries | 3 | The job will be attempted a maximum of 3 times before being marked as failed. |
--timeout | 90 | The worker process will be terminated if a job runs for more than 90 seconds. |
numprocs | 1 | Supervisor will run 1 instance of this worker process. |
Sources: docker/supervisord.conf:3
Job Scheduling
While no specific scheduled jobs are defined, the application includes the standard Laravel Kernel.php file, which is the central place for registering console commands and scheduling tasks. Any recurring jobs, such as cleanup tasks or report generation, would be defined here.
protected function schedule(Schedule $schedule): void
{
// $schedule->command('inspire')->hourly();
}
This setup allows for cron-like job scheduling within the Laravel application itself, which can then dispatch jobs to the queue system.
Sources: app/Console/Kernel.php:33-36