Test Environment Parity
debt(d7/e7/b7/t5)
Closest to 'only careful code review or runtime testing' (d7). The detection_hints note automated=no and the tools listed (docker, github-actions, docker-compose) are infrastructure tools, not static analysers that flag mismatches. Version divergence between dev and production is only visible when you explicitly compare configurations or when a bug surfaces at runtime — there is no linter or compiler that catches 'PHP 8.1 in dev vs 8.3 in prod'.
Closest to 'cross-cutting refactor across the codebase' (e7). The quick_fix says 'run your test suite inside the same Docker image used for production', but achieving this in practice requires committing docker-compose files, aligning all developer machines, updating CI pipelines, and keeping versions in sync going forward. The common_mistakes list covers multiple independent environment dimensions (PHP version, MySQL strict mode, timezone, extension config) each requiring its own remediation across dev, CI, and production — this is a cross-cutting infrastructure change, not a single-file fix.
Closest to 'persistent productivity tax' (b7, leaning toward strong gravitational pull). applies_to covers both web and cli contexts, meaning every developer, every CI run, and every deployment pipeline is shaped by whether parity is maintained. An uncommitted or inconsistent docker-compose.yml means every new developer inherits drift, every PR risks environment-specific failures, and every future infrastructure decision must account for parity. The choice gravitationally pulls on all work streams.
Closest to 'notable trap' (t5). The misconception field explicitly states that developers believe staging parity is sufficient, when in fact the highest-value parity is dev-to-production. This is a documented, widely-encountered gotcha (12-factor Factor VI) that most developers eventually learn the hard way, but it does not fully contradict a similar concept elsewhere — it is more of a prioritisation mistake than a contradictory behaviour.
Also Known As
TL;DR
Explanation
Environment parity (12-Factor App Factor VI): dev, CI, staging, and production use identical PHP version, extensions, database version and configuration, OS, timezone, and locale. Docker Compose committed to the repository ensures all developers use the same stack. PHP version matrix in CI tests against all supported versions. Common divergences that cause bugs: PHP 7.4 vs 8.3 behaviour differences, MySQL strict mode enabled in production but not dev, different timezone configurations.
Common Misconception
Why It Matters
Common Mistakes
- System PHP on developer machines diverging from production version
- No committed docker-compose.yml — each developer's environment drifts over time
- Different MySQL strict mode between environments — queries accepted in dev rejected in production
- Wrong timezone in dev or CI — date calculation bugs that only appear in certain timezones
Code Examples
# Divergent environments — bugs appear only in production:
# Developer: PHP 8.1 (system PHP), MySQL 5.7, UTC timezone
# CI: PHP 8.2 (GitHub Actions default), MySQL 8.0, UTC
# Production: PHP 8.3, MySQL 8.0, Europe/London timezone
# Bug: MySQL 8.0 strict mode rejects query that 5.7 accepts
# Discovered: production deployment — emergency hotfix# docker-compose.yml committed — identical for all developers:
services:
php:
image: php:8.3-fpm-alpine # Same as production
environment:
APP_TIMEZONE: Europe/London # Match production
mysql:
image: mysql:8.0 # Same version as production
environment:
MYSQL_STRICT_MODE: '1' # Match production strict mode
# CI also uses mysql:8.0 and PHP 8.3 — identical stack