Zero-Downtime Deployment for PHP

By Khimananda Oli | Last reviewed: August 2026

Achieving true zero-downtime deployment for PHP requires decoupling file updates from active request processing. Most 502 Bad Gateway errors during releases stem from overwriting files in-place while PHP-FPM workers are still executing them or Nginx is holding stale file handles. The solution is an atomic symlink swap combined with a graceful process reload that drains existing connections before loading new code. This approach ensures users never see an error page, even during high-traffic database migrations or major version upgrades.

How does atomic symlink switching enable zero-downtime deployment for PHP?

The core mechanism behind reliable zero-downtime deployment for PHP is filesystem atomicity. On Linux, renaming a file or updating a symlink within the same mount point is an atomic operation—it either happens completely or not at all. There is no intermediate state where the symlink points to nothing or a partial path. When you structure your application in timestamped release directories, you can prepare an entire new version—including running composer install, compiling assets, and warming caches—without touching the live site. Only when every preparation step succeeds do you execute the symlink swap.

This pattern eliminates the most common cause of deployment outages: race conditions. If you overwrite files directly in the web root, a PHP worker might include a file that has been partially written or deleted mid-request. With atomic deploys, the old release remains fully intact and functional until the exact microsecond the symlink changes. Even if the new release is broken, you can roll back instantly by pointing the symlink to the previous release directory. For teams managing critical applications, pairing this with zero-downtime Laravel database migrations ensures the data layer stays consistent with the code layer during transitions.

Directory structure for atomic deploys

A standard atomic deployment layout separates immutable release code from mutable shared state. This structure is used by tools like Deployer and Capistrano and works for any PHP framework:

/var/www/myapp/
├── current -> /var/www/myapp/releases/20260819103000
├── releases/
│   ├── 20260819103000/
│   ├── 20260819090000/
│   └── 20260818150000/
└── shared/
    ├── .env
    ├── storage/
    │   ├── app/
    │   ├── framework/
    │   └── logs/
    └── vendor/  # Optional: shared vendor for faster deploys

The current symlink is what Nginx serves. Each release directory is self-contained. The shared directory holds persistent state that must survive deployments: environment files, user uploads, logs, and sometimes the vendor directory to avoid reinstalling dependencies on every deploy. During deployment, symlinks from the new release directory point back to these shared resources before the atomic swap occurs.

How do you configure Nginx and PHP-FPM for graceful reloads?

Even with atomic symlinks, misconfigured process managers cause 502 errors. Nginx and PHP-FPM must be reloaded gracefully—not restarted—to drain in-flight requests. A hard restart kills worker processes immediately, dropping active connections. A graceful reload signals workers to finish their current request before exiting, while new workers spawn with the updated configuration or code paths.

For Nginx, use systemctl reload nginx or nginx -s reload. This sends a SIGHUP to the master process, which reads the new config and spawns new workers while old workers continue serving existing connections. For PHP-FPM, the equivalent is systemctl reload php8.4-fpm (adjust for your version). This sends SIGUSR2 to the FPM master, triggering a graceful pool recycle. Crucially, verify your FPM pool configuration includes pm.max_requests to prevent memory leaks from long-lived workers, but set it high enough (e.g., 1000–5000) to avoid excessive recycling overhead.

Nginx configuration for symlinked deploys

Your Nginx server block must reference the symlink path, never a specific release. Disable realpath_cache awareness issues by ensuring fastcgi_param SCRIPT_FILENAME uses $document_root$fastcgi_script_name rather than hardcoded paths. Also, set fastcgi_intercept_errors on; to catch PHP fatal errors cleanly:

server {
    listen 443 ssl http2;
    server_name example.com;
    root /var/www/myapp/current/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.4-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_intercept_errors on;
        fastcgi_buffer_size 16k;
        fastcgi_buffers 4 16k;
    }
}

After updating the symlink, always validate config before reloading: nginx -t && systemctl reload nginx. This prevents taking down the site due to a typo in a config change deployed alongside your code.

What are the common pitfalls in PHP zero-downtime deployments?

Even with perfect atomic symlinks, several subtle issues break zero-downtime deployment for PHP. Understanding these prevents production incidents that only surface under load.

• OPcache inconsistency: PHP’s OPcache stores compiled bytecode in shared memory. After a symlink swap, cached scripts may still reference the old release path. Always call opcache_reset() via CLI or HTTP endpoint after deployment, or configure opcache.validate_timestamps=1 with a short revalidate_freq in development (but disable validation entirely in production and reset explicitly).
• Queue workers holding stale code: Long-running queue workers (Laravel Horizon, Supervisor-managed processes) do not automatically pick up new code. You must restart them gracefully after deployment: php artisan queue:restart signals workers to finish current jobs and exit, allowing Supervisord to respawn them with fresh code.
• Database migration timing: Running migrations before the code deploy can break the old release if columns are renamed or removed. Always write backward-compatible migrations and run them before deploying code. For destructive changes, use a multi-release strategy detailed in database migration best practices.
• Asset versioning mismatches: If you compile assets during deploy, ensure the manifest is generated in the new release directory before the symlink swap. Serving old HTML with new asset hashes (or vice versa) causes broken UIs. Use mix.version() or Vite’s hash-based filenames tied to the release.
• Insufficient disk space: Keeping multiple releases consumes disk. Without cleanup, servers fill up and deployments fail mid-swap. Retain only 3–5 recent releases and automate pruning.

Handling OPcache resets safely

In production, disable timestamp validation for performance (opcache.validate_timestamps=0). This means OPcache won’t detect file changes automatically. Create a dedicated cache-clear endpoint or CLI command that runs post-deploy:

# In your deploy script, after symlink swap:
php -r "if(function_exists('opcache_reset')){opcache_reset();echo 'OPcache cleared';}else{echo 'OPcache not enabled';}"

# Or via HTTP (secured):
curl -s https://example.com/internal/opcache-reset?token=$DEPLOY_TOKEN

Never expose cache-reset endpoints publicly. Secure them with IP whitelisting or a shared secret. For Laravel, packages like laravel-opcache provide artisan commands for this.

How do Deployer and manual scripts compare for PHP deployments?

Choosing between a dedicated tool and custom scripts depends on team size, complexity, and compliance requirements. Both can achieve zero-downtime deployment for PHP, but they differ significantly in maintainability and safety features.

For most PHP teams in 2026, Deployer offers the fastest path to reliable zero-downtime deploys. Its atomic symlink logic is battle-tested, and community recipes handle framework-specific quirks. However, in regulated environments (fintech, healthcare in Nepal or globally), custom scripts integrated with CI pipelines provide the auditability and control needed for compliance. I’ve used both: Deployer for client projects where speed matters, and Ansible+Terraform for ISO 27001-certified infrastructure where every deployment step must be traceable.

Essential pre-deploy checklist

Before executing any deployment, verify these items to prevent avoidable downtime:

1. Disk space: Confirm ≥20% free space on the application volume (df -h /var/www).
2. Database compatibility: Ensure pending migrations are backward-compatible with the currently running code.
3. Queue drain: If deploying breaking changes, pause queue workers and wait for in-flight jobs to complete.
4. Health endpoint: Verify your application health check (/healthz) returns 200 on the current release before starting.
5. Rollback plan: Confirm the previous release directory exists and is intact. Test rollback procedure quarterly.
6. Monitoring active: Ensure error rate and latency dashboards are visible during deploy. Set up alerts for 5xx spikes as covered in the four golden signals of monitoring.

Implementing Zero-Downtime Deployment for PHP Reliably

Reliable zero-downtime deployment for PHP is not about finding a perfect tool—it’s about enforcing atomicity, draining connections gracefully, and validating every transition. Start with the atomic symlink pattern, configure Nginx and PHP-FPM for graceful reloads, and add explicit OPcache and queue worker resets to your deploy script. Automate health checks post-deploy and retain at least three prior releases for instant rollback. Whether you use Deployer or custom automation, the underlying principles remain identical: never mutate live code, always validate before swapping, and monitor during the transition. If your team needs help designing a deployment pipeline that meets both performance and compliance requirements, reach out to discuss your infrastructure.