Pre-deploy checklist and quick rollback plan for PHP applications in production

By Kevin Marcondes · Published on Oct 15, 2026 · 8 min read

This guide provides a pre-deploy checklist and a quick rollback plan for PHP applications in production. You’ll get concrete steps, go/no‑go criteria and a compact runbook to safely revert when things go wrong. Copy it, adapt it to your team and use it before your next deployment.

When to use this checklist and who it’s for

Use this checklist before any release that changes code, dependencies, configuration, database or infrastructure. It applies to PHP monoliths and microservices running on VMs, bare metal or containers. The focus is reducing operational risk with clear checks and a rehearsed quick rollback plan.

It complements your CI/CD pipeline and change policies. Adapt names and commands to your framework and environment. Do not promise zero risk: prepare to detect failures early and revert quickly.

Pre-deploy: mandatory technical validations

Freeze the target version with a tag and immutable artifacts. Build and install dependencies off your production servers. Check PHP versions, required extensions and OPCache settings. Ensure the application healthcheck and PHP-FPM readiness are in place.

Validate environment variables and secrets. Compile assets, generate caches and run smoke tests. If any step fails, do not force the deploy: investigate and rebuild the artifact. For server security hardening see the VPS Linux security checklist.

Integrate these checks into the pipeline to standardize them. If you use GitHub Actions for PHP projects, this CI/CD guide for PHP helps structure reproducible stages.

• Release tag created and signed
• Reproducible composer install (no dev), idempotent build
• Compatible PHP and extensions; OPCache warmup
• Env vars and secrets present at runtime
• Versioned assets and regenerated caches
• Healthcheck returns HTTP 200 and error tracing enabled
• Smoke tests pass against staging/partial environment

Database: safe migrations and rollback

Plan migrations in two phases to keep backward compatibility. Avoid long locks on hot tables. Create indexes asynchronously where possible. Test with realistic data and measure execution time.

Keep a documented rollback procedure: how to revert columns, indexes and data. Tested backups are mandatory. Rehearsing a targeted restore reduces panic. For strategies, see the migrations and rollbacks guide.

• Avoid destructive DDL during peak windows
• Split renames into add+populate+switch+remove
• Collect execution plan before/after
• Monitor locks and deadlocks during deploy
• Record rollback commands per change

Quick rollback plan: criteria and practical steps

Define objective rollback criteria: spike in errors, p95 latency increase, timeout rate, failures in critical endpoints or growing queues. Assign owners and a maximum time between decision and execution.

Keep releases versioned by directory and an active symlink. Rollback swaps the symlink to the previous known-good release and reloads services. If an irreversible migration exists, prefer a controlled roll‑forward fix.

• Clear and observable rollback criteria
• Immutable, traceable releases
• Atomic symlink to switch versions
• Reload PHP-FPM and HTTP without dropping connections
• Documented schema/data reversal steps

# Exemplo genérico de rollback via symlink atômico
# Ajuste caminhos e nomes de serviços ao seu ambiente

export PREV_RELEASE="/var/www/releases/2026-10-07_2230"  # versão estável
ln -sfn "$PREV_RELEASE" /var/www/current

# Recarregar serviços para pegar novo path/opcache
sudo systemctl reload nginx 2>/dev/null || true
sudo systemctl reload php-fpm 2>/dev/null || sudo systemctl reload php8.2-fpm 2>/dev/null || true

# Opcional: limpar cache da aplicação (depende do framework)
# php /var/www/current/artisan cache:clear  # Laravel (exemplo)

Deploy window, communication and post-release monitoring

Coordinate the window with business and support. Notify internal channels and have a prepared message for customers if needed. Maintenance mode will drop sessions—use it only for operations that require exclusive access.

Monitor errors, latency, queues, CPU/memory and logs. Set observation milestones: T+5, T+15, T+60. Have a roll‑forward plan if the issue is small and isolated.

• Communication before, during and after
• Approval points and go/no‑go gates
• Dashboards and alerts enabled
• War room and named owners
• Post-deploy functional validation checklist

Risk-reducing strategies: blue/green, canary and feature flags

Blue/green switches traffic between two identical environments. Reversion is fast and predictable. Canary releases go to a fraction of users, limiting the blast radius.

Feature flags decouple deploy from release. Enable features gradually and turn them off in seconds if something goes wrong. See how to apply them in feature flags for PHP monoliths.

If you use orchestrators, rollout patterns help minimize downtime. This comparison of zero-downtime deployment strategies in Kubernetes explains trade-offs applicable to any stack.

• Blue/green: fast route switch, simple rollback
• Canary: limited impact with targeted metrics
• Flags: fine-grained control and logical rollback
• Gatekeepers for critical endpoints
• Observability driving decisions

Consolidated checklist to copy and paste

Use this quick view as the final validation before the go/no‑go. Adapt names, severity levels and owners. Keep a copy in the application repository, versioned alongside the code.

Runbook templates and useful commands (adapt)

Keep a short, actionable and tested runbook. Include owners, exact commands, checkpoints and success criteria. For Laravel, check official docs on maintenance and caches. See also the deploy Laravel guide.

Document equivalents for your framework. For CLI and syntax reference consult PHP/OPCache docs at php.net and Laravel docs at laravel.com.

• Pre-check: green metrics, backups OK, communication sent
• Deploy: publish release and warm caches
• Verify: smoke tests and dashboards
• Decide: keep, roll‑forward or rollback
• Rollback: ready commands and validation checklist

# Exemplo genérico de passos (adapte ao seu ambiente)
# 1) Criar tag e build
# git tag -a release-2026-10-08 -m "Release"
# 2) Instalar dependências no build server
composer install --no-dev --prefer-dist --no-interaction --optimize-autoloader
# 3) Publicar release versionada
rsync -a --delete ./build/ /var/www/releases/2026-10-08_1530/
ln -sfn /var/www/releases/2026-10-08_1530 /var/www/current
# 4) Recarregar serviços
systemctl reload nginx 2>/dev/null || true
systemctl reload php-fpm 2>/dev/null || systemctl reload php8.2-fpm 2>/dev/null || true
# 5) Backup do banco (exemplo; escolha seu SGBD)
# PostgreSQL: pg_dump -Fc -h HOST -U USER DB > /backups/app_$(date +%F_%H%M).dump
# MySQL: mysqldump -h HOST -u USER -p DB > /backups/app_$(date +%F_%H%M).sql
# 6) Rollback rápido (se necessário)
# ln -sfn /var/www/releases/ULTIMA_ESTAVEL /var/www/current && systemctl reload nginx php-fpm

Frequently asked questions

What’s the difference between rollback and roll‑forward?

Rollback returns to a previously known-good state, usually by switching the production version. Roll‑forward applies a new fix to correct the current issue. Choose rollback when impact is high and reversal is simple.

Should I always enable maintenance mode during deploy?

No. For most deploys use atomic switching (symlink or blue/green) and reload PHP-FPM. Maintenance mode is useful only for exclusive operations, like migrations that cannot coexist with traffic.

How do I decide when to roll back?

Define metric thresholds before deploy, such as 5xx errors, p95 latency, timeout rate and queue stability. If thresholds are exceeded for a short defined period, execute the rollback without debate. Objective criteria prevent indecision.

How can I ensure the database backup is valid?

Perform regular test restores. Restore the backup in an isolated environment, run migrations and smoke tests. Document recovery time and steps. A backup that hasn’t been restored and tested is not trustworthy.

Can I use this checklist with Docker containers?

Yes. Build the image reproducibly, publish an immutable tag, warm caches in the entrypoint and use readiness probes. Rollback can point the service to the previous image or the green slot in a blue/green setup.

How do I warm OPCache after deploy?

Use preloading, map critical scripts into the cache and perform an initial call to the most used endpoints. Reloading PHP-FPM also helps. Tune memory size and timestamp validation according to your application load.

See also

• Security checklist for CI/CD pipelines with self‑hosted runners and secrets management
• Guide: Centralize logs with Fluentd and Elasticsearch for PHP apps on a VPS
• Guide: Organizing PostgreSQL Migrations and Rollbacks for Small Teams
• VPS Linux security checklist before putting services into production: hardening, SSH, backups and monitoring