Restarting Laravel's queue workers should be an essential part of your deployment script. Running this simple command should do the trick:
php artisan queue:restart
It works by setting a illuminate:queue:restart key in your cache store that holds the timestamp of when the command ran. After workers finish each job, they check for that key and see if it was updated since the last time they checked. If that's the case, the worker process will exit and your process manager may start a new one.
If you're using Laravel Forge, you'll have easy access to information on the uptime of each of your workers. If you check the status of a worker after it was restarted, you should see something like this:
worker-:worker-_00 RUNNING pid 75, uptime 0 days, 00:00:20
This indicates the process is brand new. Your process manager just started it.
If the worker doesn't exit after a restart signal and you checked its status, you'll find the uptime much longer. If that's the case, here are a couple of things to check.
Ensuring The Worker Runs in Daemon Mode
If you start your worker using queue:listen instead of queue:work, the listener process will start a separate child process for each job. Once the job runs, the child process is terminated and a new one starts to process the next job. That means your jobs will always run using the latest code deployed. In other words, no need to restart a listener process and thus running queue:restart won't have any effect.
The only way to restart a listener process is manually:
supervisorctl restart worker-name:*
Ensuring The Cache Store Is Correctly Configured
Another thing to check is the configuration of your cache store. Basically all worker instances running your application should have access to the same cache store. They all need to be able to see the value of the illuminate:queue:restart cache key when it's set by the restart command.
Also if you're using the file cache driver, make sure the permissions of the storage/framework/cache directory are correctly set so that the instance running the queue:restart can write the cache key and the worker instances can read it.
sudo chown -R forge:forge storage/framework/cache
Running this command will ensure that the files in the cache directory are all owned by the forge system user. Now if your worker processes are run by the forge user, they will have access to the cache files even if the restart command was executed by a different system user.
Changing The Cache Prefix
If you change the cache prefix, the restart command will set a cache key with the new prefix. Existing workers won't be able to detect that prefix change and will keep checking the old cache key.
If you are going to change the cache prefix, you'll have to restart the workers manually after the change.
supervisorctl restart worker-name:*
If you want to learn more about Laravel's queue system, make sure to check Laravel Queues in Action! I've put everything I know about the queue system in an eBook format along with several real-life uses cases.
I'm Mohamed Said. I work with companies and teams all over the world to build and scale web applications in the cloud. Find me on twitter @themsaid.