PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys

SEO Metadata

SEO Title Options

1. PHP Workers and Queues: Supervisor, Horizon
2. PHP Workers and Queues: Supervisor: Practical 2026 Guide
3. Tooling Playbook: PHP Workers and Queues: Supervisor

Meta Description Options

1. Learn PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys with a practical Tooling framework, expert mistakes, implementation steps, examples.
2. Production guide for managing PHP queue workers - Supervisor config, graceful restarts, deploy coordination, and alerting setup.

URL Slug

php-workers-queues-supervisor-horizon-zero-downtime-deploys

Focus Keyword

PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys

Additional LSI Keywords

• Tooling
• PHP
• Queues
• Supervisor
• Horizon
• Deployments
• PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys
• production checklist
• implementation guide
• best practices
• architecture decisions
• testing strategy

Table of Contents

• Article overview
• What PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys means
• Why it matters now
• Implementation framework
• Practical comparison
• Expert workflow
• Common mistakes
• Media and link plan
• Original technical deep dive
• FAQ
• Structured data
• Conclusion

Article overview

PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys is the kind of topic that looks simple until it reaches production. Teams usually discover the real cost late: unclear boundaries, weak defaults, hidden maintenance work, and decisions that seemed harmless when the codebase was small.

The problem gets worse when the article, tutorial, or implementation guide only explains the happy path. This guide closes that gap with a practical framework, a comparison table, common mistakes, and a deep technical section you can use while planning real work.

Keep reading for the non-obvious part: the safest implementation is rarely the most impressive-looking one. It is the one your team can debug, test, document, and evolve without turning every future change into archaeology.

Key Takeaways

• PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys should be evaluated as a production decision, not only as a syntax or tooling choice.
• The best implementation keeps responsibilities visible, with clear ownership, tests, documentation, and rollback paths.
• Search visibility improves when practical depth, structured answers, and expert examples live on the same page.

[IMAGE: A mobile-first technical article layout showing the main concept, decision table, implementation checklist, and FAQ blocks. Alt: PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys expert guide for Tooling]

What PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys means

PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys means applying tooling knowledge to a concrete engineering decision, then turning that decision into reliable code, documentation, and operational behavior. In practice, it combines the topic's core concepts with trade-off analysis, implementation boundaries, testing strategy, and maintenance discipline.

This is the definition worth optimizing for featured snippets because it avoids hype. It tells the reader what the topic does and what a professional implementation must include.

Why it matters now

The technical web is more crowded than it was a few years ago. Thin tutorials can still get indexed, but they rarely earn trust from senior developers, buyers, AI answer systems, or teams that need production guidance.

For tooling topics, the strongest content now has three layers:

• a clear answer for fast scanning
• a practical framework for implementation
• expert context that explains what breaks later

That same structure helps search engines understand the page. It also helps readers decide whether the advice fits their project.

Implementation framework

Use this framework before adopting the approach described in this article.

1. Define the user problem and the production risk.
2. Identify the smallest reliable implementation boundary.
3. Keep configuration, secrets, and environment-specific behavior outside the article's core logic.
4. Add tests for the behavior that would hurt if it regressed.
5. Document the trade-off, not only the final code.
6. Measure the result with logs, metrics, or user-facing outcomes.
7. Revisit the decision after real usage exposes edge cases.

The sequence is deliberately conservative. It keeps the work grounded in outcomes instead of novelty.

[IMAGE: A seven-step implementation framework with discovery, boundary design, configuration, tests, documentation, measurement, and iteration. Alt: PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys implementation framework]

Practical comparison

This table is intentionally practical. It gives a reviewer something to check before the implementation becomes expensive to change.

Expert workflow

Expert tip: "Treat PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys as a system boundary. If the next developer cannot find where the decision lives, how it is tested, and when it should be avoided, the implementation is not finished."

A useful workflow is simple:

• Start with the smallest working example.
• Add the constraints that exist in your real project.
• Remove anything that only demonstrates cleverness.
• Write down the failure modes.
• Add links to related decisions so future readers can navigate the topic cluster.

That last point matters for both humans and search systems. A single article can answer a question; a cluster proves authority.

Common mistakes

Mistake 1: Copying a pattern without its context

A pattern that works in a small demo can fail in a real application. The missing context is usually data volume, team experience, deployment process, security requirements, or observability.

Before copying the pattern, ask what assumption made it safe in the original example.

Mistake 2: Putting business logic in the wrong layer

This is the fastest way to make future debugging expensive. In Laravel, PHP, and server-rendered websites, presentation should receive prepared data, not discover rules on its own.

Keep decision logic in models, actions, services, policies, requests, jobs, or documented helpers where it can be tested directly.

Mistake 3: Optimizing for novelty instead of maintainability

Newer tools and language features can be valuable. They can also hide simple behavior behind unfamiliar syntax.

Use the option that makes the next production incident easier to understand.

Mistake 4: Publishing without a measurement plan

If the article describes a performance, SEO, security, or architecture improvement, define how success will be checked. Logs, tests, crawl diagnostics, analytics, and user behavior are all stronger than assumptions.

[IMAGE: A common-mistakes board with context loss, wrong layer, novelty bias, and missing measurement highlighted. Alt: PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys common mistakes]

Media and link plan

Image placeholders

• [IMAGE: A concept diagram for PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys with input, decision boundary, implementation, tests, and production feedback. Alt: PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys concept diagram]
• [IMAGE: A mobile screenshot-style checklist for PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys. Alt: PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys mobile checklist]
• [IMAGE: A comparison table visualization for strong versus weak implementation choices. Alt: PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys comparison table]

Video placeholder

[VIDEO: Insert a 5-8 minute YouTube walkthrough that demonstrates the main decision, the implementation boundary, the test strategy, and the production caveats for PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys.]

Trustworthy outbound links

• PHP manual - use this as the trust reference for language-level reference.
• Google Search quality guidance - use this as the trust reference for people-first content and E-E-A-T alignment.

Internal linking opportunities

• Internal guide: PHP Webhooks With Filament: Admin Panels and - use this when readers need a related Tooling follow-up.
• Internal guide: PHP Rector: Automated Code Upgrades and - use this when readers need a related Tooling follow-up.

Original Technical Deep Dive

The short version

Queue workers are long-running production processes. Treat them like application servers, not helper scripts.

The baseline setup is:

• Run every worker under Supervisor, systemd, a container orchestrator, or a platform process manager.
• Give workers explicit timeouts, retry limits, memory limits, and queue names.
• Keep job timeout lower than the queue retry or visibility timeout.
• Restart workers on every deploy so they load the new code.
• Let workers finish their current job before exit.
• Alert on queue age, queue depth, failed jobs, worker count, worker restarts, and memory growth.

Laravel gives you two common production modes:

The important production idea is the same in all three modes: the process manager keeps workers alive; the application tells old workers when to drain.

Worker lifecycle

A queue worker usually does this loop:

1. Boot the application.
2. Reserve one job from a queue.
3. Run the handler.
4. Acknowledge, delete, or release the job.
5. Repeat until the process is stopped.

That boot step matters. A daemon worker keeps framework state, configuration, singletons, static variables, loaded classes, database clients, and service clients in memory. A web request starts fresh often enough that code changes are naturally picked up by new requests. A queue worker can keep running old code for hours unless you restart it.

Deploying code without restarting workers creates production bugs that are hard to reproduce:

• A new web request dispatches a job class shape the old worker cannot deserialize.
• A migration removes a column while an old worker still writes it.
• A config change is cached in the new release but old workers keep the old config in memory.
• A singleton or static variable carries state from one job into the next.
• A memory leak slowly turns into failed jobs instead of failed HTTP requests.

[IMAGE: Supporting visual 1 for PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys, showing PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys decisions, examples, and PHP, Queues, Supervisor. Alt: PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys php-workers-queues-supervisor-horizon-zero-downtime-deploys visual 1]

[IMAGE: Supporting visual 1 for PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys, showing PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys decisions, examples, and PHP, Queues, Supervisor. Alt: PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys php-workers-queues-supervisor-horizon-zero-downtime-deploys visual 1]

The fix is not complicated. Workers must be disposable, and deployments must make them drain.

Production invariants

Use these rules before tuning worker counts:

If one of these is missing, adding more workers often makes the incident larger.

Plain Laravel workers

Start with explicit Redis queue configuration:

QUEUE_CONNECTION=redis
REDIS_QUEUE_RETRY_AFTER=120

Then keep the worker command explicit:

php artisan queue:work redis \
    --queue=critical,default,low \
    --sleep=1 \
    --tries=3 \
    --timeout=90 \
    --memory=256 \
    --max-time=3600

The settings are operational controls, not decoration:

For Laravel's Redis queue driver, set --timeout several seconds lower than retry_after. If retry_after is 120 seconds, --timeout=90 leaves enough room for the worker to die before Redis releases the job for another attempt.

For SQS, use the same idea with the queue's visibility timeout. The worker timeout must be lower than the visibility timeout, or duplicate processing becomes likely.

Supervisor for queue:work

Create one Supervisor program per worker pool. A useful first production config looks like this:

[program:app-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/app/current/artisan queue:work redis --queue=critical,default,low --sleep=1 --tries=3 --timeout=90 --memory=256 --max-time=3600
directory=/var/www/app/current
user=www-data
numprocs=4
autostart=true
autorestart=true
startsecs=5
stopwaitsecs=180
stopasgroup=true
killasgroup=true
redirect_stderr=true
stdout_logfile=/var/log/supervisor/app-worker.log

[IMAGE: Supporting visual 2 for PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys, showing PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys decisions, examples, and PHP, Queues, Supervisor. Alt: PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys php-workers-queues-supervisor-horizon-zero-downtime-deploys visual 2]

Use separate programs for queues with different runtime needs:

[program:app-export-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/app/current/artisan queue:work redis --queue=exports --sleep=3 --tries=1 --timeout=900 --memory=512 --max-time=3600
directory=/var/www/app/current
user=www-data
numprocs=1
autostart=true
autorestart=true
startsecs=5
stopwaitsecs=1200
stopasgroup=true
killasgroup=true
redirect_stderr=true
stdout_logfile=/var/log/supervisor/app-export-worker.log

The long export pool gets one process and a larger timeout. It cannot consume capacity reserved for critical jobs.

Load the config:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start "app-worker:*"
sudo supervisorctl status

When changing Supervisor config, use reread and update. When deploying code, prefer Laravel's drain signal:

php artisan queue:restart

[IMAGE: Supporting visual 2 for PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys, showing PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys decisions, examples, and PHP, Queues, Supervisor. Alt: PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys php-workers-queues-supervisor-horizon-zero-downtime-deploys visual 2]

queue:restart tells workers to finish the current job and exit. Supervisor sees the exit and starts new processes. Those new processes load the new release.

Zero-downtime deploy sequence

Zero-downtime queue deploys are mostly about compatibility. You will always have a period where old workers, new web code, old jobs, and new jobs can overlap.

A safe symlink-based deployment looks like this:

set -euo pipefail

RELEASE=/var/www/app/releases/20260414120000

git clone --depth=1 git@github.com:example/app.git "$RELEASE"
cd "$RELEASE"

composer install --no-dev --prefer-dist --no-interaction --optimize-autoloader
php artisan config:cache
php artisan route:cache
php artisan view:cache

php artisan migrate --force

ln -sfn "$RELEASE" /var/www/app/current

php /var/www/app/current/artisan queue:restart
sudo supervisorctl status "app-worker:*"

This works because Supervisor runs the command through /var/www/app/current/artisan. After the symlink changes, restarted workers boot from the new release.

Do not make these mistakes:

• Do not run supervisorctl restart first. That can kill a job in the middle of work.
• Do not remove old release directories before old workers have exited.
• Do not deploy incompatible job payloads without a transition period.
• Do not use local cache for queue:restart on multi-host deployments unless every host receives the signal.
• Do not run destructive migrations before all old workers can tolerate the schema change.

For schema changes, use expand and contract:

1. Add new nullable columns, tables, or indexes.
2. Deploy code that writes both old and new shapes or reads both shapes.
3. Backfill data.
4. Deploy code that depends only on the new shape.
5. Remove old columns or behavior in a later deploy.

That matters more for queues than HTTP because a queued job may run minutes or hours after it was created.

Plain PHP worker signal handling

If you are not using Laravel, build the same drain behavior into your CLI worker. Handle SIGTERM, stop reserving new work, finish the current job, and exit cleanly.

<?php

declare(strict_types=1);

pcntl_async_signals(true);

$running = true;

pcntl_signal(SIGTERM, function () use (&$running): void {
    $running = false;
});

pcntl_signal(SIGINT, function () use (&$running): void {
    $running = false;
});

while ($running) {
    $job = $queue->reserve(timeout: 5);

    if ($job === null) {
        continue;
    }

    try {
        $handler->handle($job);
        $queue->ack($job);
    } catch (Throwable $exception) {
        $queue->releaseOrFail($job, $exception);
    }
}

$logger->info('Worker drained after stop signal');

Do not exit from the signal handler while a job is midway through a database write or external API call. Set a flag and let the loop exit between jobs.

[IMAGE: Supporting visual 3 for PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys, showing PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys decisions, examples, and PHP, Queues, Supervisor. Alt: PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys php-workers-queues-supervisor-horizon-zero-downtime-deploys visual 3]

Supervisor should still have a long enough stopwaitsecs for the largest valid job. The graceful signal is only useful if the process manager waits long enough for the process to comply.

Horizon in production

Horizon is best when you use Laravel Redis queues and want visibility, balancing, and queue wait-time alerts.

Start with a small config/horizon.php production section:

'waits' => [
    'redis:critical' => 30,
    'redis:default' => 60,
    'redis:low' => 300,
],

'environments' => [
    'production' => [
        'supervisor-critical' => [
            'connection' => 'redis',
            'queue' => ['critical'],
            'balance' => 'auto',
            'minProcesses' => 2,
            'maxProcesses' => 8,
            'balanceMaxShift' => 1,
            'balanceCooldown' => 3,
            'tries' => 3,
            'timeout' => 90,
            'memory' => 256,
        ],

        'supervisor-default' => [
            'connection' => 'redis',
            'queue' => ['default', 'low'],
            'balance' => 'auto',
            'minProcesses' => 1,
            'maxProcesses' => 6,
            'balanceMaxShift' => 1,
            'balanceCooldown' => 3,
            'tries' => 3,
            'timeout' => 90,
            'memory' => 256,
        ],
    ],
],

Keep long-running work out of the same supervisor:

'supervisor-exports' => [
    'connection' => 'redis',
    'queue' => ['exports'],
    'balance' => 'simple',
    'processes' => 1,
    'tries' => 1,
    'timeout' => 900,
    'memory' => 512,
],

[IMAGE: Supporting visual 3 for PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys, showing PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys decisions, examples, and PHP, Queues, Supervisor. Alt: PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys php-workers-queues-supervisor-horizon-zero-downtime-deploys visual 3]

Horizon supervisors are not OS process managers. They supervise Laravel worker processes inside Horizon. You still need a real process manager for the php artisan horizon process itself.

Supervisor for Horizon

Use one OS process for Horizon. Horizon handles its own worker pool internally.

[program:horizon]
process_name=%(program_name)s
command=php /var/www/app/current/artisan horizon
directory=/var/www/app/current
user=www-data
autostart=true
autorestart=true
redirect_stderr=true
stdout_logfile=/var/log/supervisor/horizon.log
stopwaitsecs=3600
stopasgroup=true
killasgroup=true

Load and start it:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start horizon
sudo supervisorctl status horizon

Deploy Horizon with:

php /var/www/app/current/artisan horizon:terminate

Horizon exits, Supervisor restarts it, and the new Horizon process boots the new code. Keep stopwaitsecs higher than the longest job Horizon may let finish.

Alerting setup

Queues need alerts based on delay and failure, not only process uptime.

Minimum alert set:

For plain Laravel queues, schedule queue:monitor:

<?php

use Illuminate\Support\Facades\Schedule;

Schedule::command('queue:monitor redis:critical,redis:default --max=100')
    ->everyMinute();

Then listen for QueueBusy and notify your team:

<?php

namespace App\Providers;

use App\Notifications\QueueBacklogDetected;
use Illuminate\Queue\Events\QueueBusy;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\Facades\Notification;
use Illuminate\Support\ServiceProvider;

final class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Event::listen(function (QueueBusy $event): void {
            Notification::route('slack', config('services.ops.slack_webhook'))
                ->notify(new QueueBacklogDetected(
                    connection: $event->connection,
                    queue: $event->queue,
                    size: $event->size,
                ));
        });
    }
}

For Horizon, route notifications and tune wait thresholds:

<?php

namespace App\Providers;

use Laravel\Horizon\Horizon;
use Laravel\Horizon\HorizonApplicationServiceProvider;

final class HorizonServiceProvider extends HorizonApplicationServiceProvider
{
    public function boot(): void
    {
        parent::boot();

        Horizon::routeMailNotificationsTo('ops@example.com');
        Horizon::routeSlackNotificationsTo(config('services.ops.slack_webhook'), '#alerts');
    }
}

Horizon wait thresholds belong in config/horizon.php:

'waits' => [
    'redis:critical' => 30,
    'redis:default' => 60,
    'redis:exports' => 900,
],

Use different thresholds per queue. A 60-second wait is severe for a payment confirmation and normal for a nightly export.

Deploy checklist

Before the deploy:

• Confirm jobs are idempotent.
• Confirm old workers can read new payloads, or new producers are not active yet.
• Confirm database migrations are expand-only for this deploy.
• Confirm --timeout < retry_after or --timeout < visibility_timeout.
• Confirm stopwaitsecs is greater than the longest expected job.
• Confirm Supervisor or the platform restarts exited workers.
• Confirm queue alerts are enabled.

[IMAGE: Supporting visual 4 for PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys, showing PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys decisions, examples, and PHP, Queues, Supervisor. Alt: PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys php-workers-queues-supervisor-horizon-zero-downtime-deploys visual 4]

During the deploy:

php artisan migrate --force
ln -sfn "$RELEASE" /var/www/app/current
php /var/www/app/current/artisan queue:restart
# or:
php /var/www/app/current/artisan horizon:terminate

After the deploy:

sudo supervisorctl status
php /var/www/app/current/artisan queue:failed

Watch queue age, failures, and worker restarts for at least one full longest-job window. If your longest valid job is 15 minutes, a two-minute post-deploy glance is not enough.

Common mistakes

Restarting too hard

supervisorctl restart stops processes directly. If stopwaitsecs is too short, Supervisor can send SIGKILL before a job finishes. Prefer queue:restart or horizon:terminate during normal deploys.

One pool for every job

One default queue is easy until an import, export, or webhook outage blocks everything behind it. Separate queues by business priority and runtime.

[IMAGE: Supporting visual 4 for PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys, showing PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys decisions, examples, and PHP, Queues, Supervisor. Alt: PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys php-workers-queues-supervisor-horizon-zero-downtime-deploys visual 4]

Timeout values copied from a blog post

Timeouts must match your jobs. If a video transcode can take 12 minutes, do not run it in a pool with --timeout=90. If a password reset email normally takes 2 seconds, do not give it a 15-minute timeout.

Serializing too much state

Job payloads should carry IDs and simple values. Load fresh state inside the handler. This keeps payloads small and makes deployment overlap safer.

Forgetting old release directories

If a worker started in /var/www/app/releases/old, it may still need that directory until it exits. Remove old releases only after process drain is complete.

FAQ

What is PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys?

PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys is a practical tooling topic that should be evaluated through implementation scope, production risk, testing, documentation, and long-term maintainability.

When should a team use PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys?

Use PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys when it solves a real project constraint, improves clarity, or reduces operational risk. Avoid it when it only adds novelty or hides behavior from future maintainers.

What is the biggest risk with PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys?

The biggest risk is copying a pattern without its context. Production systems need clear boundaries, rollback options, tests, and observability before a technique becomes dependable.

How do you test PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys?

Test the smallest unit that owns the behavior, then add integration coverage for the path users or systems actually rely on. Include failure cases, configuration differences, and regression checks.

How does PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys affect SEO and AI search visibility?

It improves visibility when the article gives a direct answer, expert context, structured headings, internal links, trustworthy references, and FAQ content that matches the visible page.

Conclusion

PHP Workers and Queues: Supervisor, Horizon & Zero-Downtime Deploys is worth doing when the implementation improves clarity, reliability, or delivery speed. It is not worth doing when it hides ownership, increases operational risk, or makes the system harder to explain.

Use the framework above as a review checklist. Then connect this topic to the rest of the project documentation so readers can move from concept to implementation without losing context.