Deploy PHP to Production: Configuration, OPcache, Migrations, Health Checks, and Rollback

Production Release

A deployment changes more than source files. The PHP runtime, extensions, configuration, Composer dependencies, web server, workers, cache state, database schema, secrets, permissions, and monitoring must agree on one compatible release.

After this lesson, you can build an immutable artifact, separate production diagnostics from user responses, coordinate OPcache and migrations, define a meaningful health check, and write a rollback plan before release pressure begins.

Release Artifact

Build from a reviewed commit, install locked production dependencies, and avoid editing application files on the server. Record the commit or release identifier so logs and health output can identify deployed code.

Install Locked Dependencies

composer install --no-dev --classmap-authoritative --no-interaction
php -l public/index.php

install honors composer.lock; authoritative classmaps trade dynamic discovery for predictable production autoloading when the project supports it.

Production Configuration

Log enough context to diagnose a request, but exclude passwords, session identifiers, authorization headers, private uploads, and full payment or identity data.

Concern	Production Direction
display_errors	Off for user responses
log_errors	On with protected destination
Secrets	Injected outside source control
Session cookies	Secure, HttpOnly, appropriate SameSite
File permissions	Least privilege; writable storage only where required

OPcache Coordination

OPcache caches compiled bytecode. If timestamp validation is disabled, a deployment must reset OPcache or restart the relevant PHP workers after atomically activating the new release; otherwise requests may continue executing stale code.

Size OPcache from measured application file count and memory use.
Keep comments when libraries depend on attributes or documentation metadata.
Coordinate web and worker restarts so both execute compatible code.
Do not tune obscure options without measurements and the current official reference.

Migration Sequence

For rolling releases, use expand-and-contract migrations: add backward-compatible schema first, deploy code that works with old and new shapes, migrate data, then remove obsolete columns in a later release.

Back up data and test restoration, not just backup creation.
Estimate lock time for index and table changes with production-like data.
Keep irreversible data transformations out of an automatic rollback assumption.
Run migrations once with recorded ownership and outcome.

Health Evidence

A liveness endpoint proves the process responds; a readiness check proves the instance can serve traffic. Keep checks fast and avoid causing a dependency outage by probing every downstream service on every request.

Minimal Release Health

<?php
header('Content-Type: application/json; charset=utf-8');
echo json_encode([
    'status' => 'ok',
    'release' => getenv('APP_RELEASE') ?: 'unknown',
], JSON_THROW_ON_ERROR);

Expose a non-secret release identifier; protect deeper diagnostic endpoints from public access.

Rollback Trigger

Define error-rate, latency, queue, and functional signals that stop or reverse a rollout.
Keep the previous artifact available and configuration-compatible.
Verify one login, one protected read, one write, one job, and one monitored error path after deployment.
Document who decides rollback and how database compatibility affects that decision.

Approve the Release

0 of 2 checked

Q1. Why can new files still execute old code?

OPcache may retain compiled scripts PDO edits PHP files HTML caches sessions

Q2. What makes a migration friendly to rolling deployment?

Old and new code can both use the expanded schema It deletes the old column first It requires manual source edits

Try this next

Write a Release Runbook

0 of 2 completed

Map the deployment order
List build, backup evidence, migration, artifact activation, OPcache or worker restart, smoke checks, and monitoring.
Define rollback limits
State which changes reverse cleanly and which database transformations require a forward fix.

Previous Next