Stopping Daemon Queue Workers Without Maintenance Mode
When running a high-volume queue worker, specifically using the --daemon flag in Laravel, managing the lifecycle of these processes often requires precision. You might start with five workers for testing but scale up to 25 or even 100 in production to maintain throughput within a specific time window. The standard workflow during deployment involves placing the application into maintenance mode via php artisan down. This is necessary because the daemon worker only loads the framework when it starts; without maintenance mode, you risk accepting new requests while the old codebase is still executing background jobs that haven't picked up your latest deployment changes.
However, there are scenarios where you need to terminate workers without shutting down the entire application or preventing incoming HTTP requests. The core requirement is a graceful shutdown: allowing the worker to finish its current job before exiting, rather than terminating it abruptly mid-process. While php artisan queue:restart effectively stops and restarts the worker, there is no built-in Artisan command equivalent to queue:stop that halts the daemon without triggering maintenance mode or forcing an immediate kill.
The most straightforward alternative to the missing queue:stop command is using the system's process management tools directly on the specific PHP processes. You can identify the worker processes by running ps aux | grep php and filtering for your application name. Once you have the Process IDs (PIDs), you can use kill with a specific signal to achieve a graceful exit.
# Find the PIDs of your Laravel queue workers
ps aux | grep [y]our_app_name
# Gracefully stop them using SIGTERM
kill -TERM <PID>
Sending the SIGTERM signal instructs the PHP process to initiate its shutdown sequence. The worker will catch this signal, process any remaining jobs in its queue or currently executing job, and then terminate cleanly. This is functionally equivalent to what queue:restart does internally before spinning up new instances, but applied specifically to stopping existing ones.
If you prefer not to manually parse ps output, you can iterate through the PIDs found for your specific process name:
for pid in $(ps aux | grep [y]our_app_name | awk '{print $2}'); do
kill -TERM "$pid"
done
This approach ensures that no job is dropped mid-execution. The trade-off here is the lack of a single, atomic Artisan command to perform this action. You cannot simply run php artisan queue:stop because such a command does not exist in the standard Laravel installation. This forces you to rely on system-level signals or scripting to manage the worker state independently of the web server status.
It is important to note that while kill -TERM is safe, using kill -9 (SIGKILL) should be avoided unless absolutely necessary. A SIGKILL bypasses the shutdown hook entirely, potentially causing data loss if a job was in the middle of writing to a database or saving state to disk. Always prioritize graceful termination to maintain data integrity across your queue jobs.
If you find yourself needing this capability frequently during deployments or scaling operations, consider creating a custom Artisan command. You can write a simple script that accepts PIDs from the environment or scans for running processes and sends the SIGTERM signal programmatically. This encapsulates the logic into a familiar php artisan interface without requiring direct interaction with shell process lists.