PHP Deployment Strategies

When to use

• The user wants to run database migrations as part of a release without breaking in-flight requests.
• The user needs to roll back a failed PHP deployment quickly and safely.
• The user wants to release a new version of a PHP application without dropping requests or serving a maintenance page.

When NOT to use

• Do not apply release strategies when the user only wants to run the application on their own machine.
• Do not use this skill for provisioning servers, DNS, or cloud infrastructure with Terraform or similar.

Core guidance

• Release by atomically swapping a current symlink — Deploy each release into its own timestamped directory, then flip a current symlink to it in one atomic operation rather than editing files in place.
• Migrate schema with expand-and-contract, never destructive-in-place — Split schema changes into an expand phase (add nullable columns/tables, deploy code that writes both) and a later contract phase (drop the old shape).
• Deploy an immutable artifact built once — Build one immutable artifact per commit (a container image or a versioned tarball) and promote that exact artifact through staging to production.

Quick recipe

1. Copy or extract the immutable artifact into releases/<timestamp> and run the expand-phase migrations against the shared database. (verify: The new release directory exists and expand migrations applied cleanly)
2. Warm the new release, hit its health endpoint, and only on success atomically repoint the current symlink and reload PHP-FPM. (verify: The health check passes and current now resolves to the new release)
3. Watch error and latency signals; if healthy, prune old releases and later run contract migrations, otherwise flip current back to the previous release. (verify: Metrics are green and either old releases pruned or rollback completed)

Best practices

• Route traffic to a new release only after a readiness/health endpoint confirms the app booted, connected to its dependencies, and warmed critical caches
• Keep the last few release directories (or image tags) so rollback is an instant symlink flip or image redeploy, and prune older ones on a schedule
• After swapping the release, gracefully reload PHP-FPM (or reset opcache) so workers pick up the new code path instead of serving cached bytecode
• Before routing traffic, prime opcache and application caches on the new release (a health-check request or a warmup command) so the first users do not pay the cold cost

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Dropping a column mid-rollout breaks old workers — Running a destructive migration (drop/rename column) during a rolling deploy breaks the old code still serving traffic. Fix: Use expand-and-contract: add the new shape, deploy dual-writing code, backfill, then drop the old column in a later release once no code references it.
2. New code deployed but opcache still serves the old bytecode — After swapping the symlink, opcache with validate_timestamps=0 keeps serving the previous release until FPM reloads. Fix: Reload PHP-FPM (kill -USR2) or reset opcache as the final deploy step, or roll the container so a fresh process loads the new code.
3. FPM resolves the symlink once and pins the old path — PHP-FPM and opcache can cache the resolved real path of the current symlink, so a swap has no effect until reload. Fix: Reload FPM after every symlink swap, or reference the release directory by its real path in the pool config and reload on deploy.

Version notes

• opcache_reset behavior is unchanged across PHP 7.4 through 8.4 (PHP >=7.4) — The graceful FPM reload signal (SIGUSR2) and opcache_reset() semantics are stable from PHP 7.4 through 8.4, so the same reload step works across versions.

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/devops/deployment-strategies.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Prerequisites: devops/docker-php
Related: devops/ci-github-actions, devops/docker-php, devops/env-config, laravel/queues