A PHP deploy ended up running a different version of a Composer package than CI tested; which Composer workflow mistakes cause this, and how do you prevent them?

## The invariant Composer gives you one guarantee: `composer install` with the same `composer.lock` installs the same package versions everywhere. Production can differ from CI only if that invariant was broken somewhere, which means someone **resolved** versions (ran the solver) instead of **replaying** the lock, or the two environments replayed **different** locks. ## How it breaks | Cause | What actually happened | |---|---| | `composer.lock` not committed | the deploy's `install` found no lock, printed `No composer.lock file present`, and resolved the newest versions | | deploy runs `composer update` | the server re-resolved at deploy time; whatever was newest that minute shipped | | CI runs `composer update` | CI tested fresh resolutions; the deploy installed the older committed lock | | lock edited or merged by hand | the committed lock no longer matches what anyone tested | | a hotfix ran `composer require` on the server | `composer.json` and the lock on the server diverged from git | A subtle variant: a branch was merged where both sides touched `composer.lock`, and someone "fixed" it by running a full `composer update`. Composer's merge guide warns that the exact versions one branch had locked are lost at that point; the newest compatible versions come in untested. ## What is not a cause - **`--no-dev`.** Composer 2 resolves `require` and `require-dev` together during `update` and records both in the lock. `install --no-dev` omits the dev-only packages but installs the runtime packages at the versions CI had. A class that exists in CI but not in production is a misplaced `require-dev` entry, not a version difference. - **A stale `content-hash` alone.** `install` warns but still installs the locked versions, so CI and production still match each other; they just may not match `composer.json`. ## Prevention in the pipeline 1. **Commit `composer.lock`** in every application, and never list it in `.gitignore`. 2. **CI checks the lock first**: `composer validate --strict` fails on a lock that is out of date with `composer.json`; then `composer install`, never `update`, before the tests. 3. **Deploy with `composer install --no-dev --no-interaction`**, never `update` or `require`. Autoloader optimisation flags belong on the same command; they do not change versions. 4. **Build once, deploy the artifact.** The strongest guarantee is that the image or archive CI tested, `vendor/` included, is exactly what production runs, so no second install happens at all. 5. **Updates are code changes.** Dependency updates arrive as a commit that changes `composer.lock`, reviewed and tested like any other change, whether a developer or an update bot makes it. ## Diagnosing after the fact - Compare the lock the deploy used with the one CI used: `git diff <ci-sha> <deploy-sha> -- composer.lock`. - On the server, `composer show vendor/package` prints the installed version, and `vendor/composer/installed.json` records what was installed; compare it with the version in the lock. - Check the deploy log for `No composer.lock file present` or `Updating dependencies`, the lines that show resolution happened on the server. - If a text merge is suspected, `composer validate` reports required packages that are missing from the lock, and `composer install --dry-run` shows what an install would change. ## A worked incident A team's deploy script ran `composer install --no-dev` inside a container build. The build context excluded `composer.lock` through a broad ignore pattern meant for local files. Every deploy printed the no-lock warning, resolved the newest versions, and passed its smoke test. Weeks later a minor release of a date library changed a default, and invoices printed with the wrong timezone in production only. CI had been testing the committed lock the whole time. The fix was one line in the ignore file; the lasting fix was a build step that **fails** when `composer.lock` is absent, plus comparing `composer show` output from the image with the lock as part of the release checklist. ## Why this is worth an interview question The failure is quiet. Nothing errors at deploy time; a minor release with a behaviour change simply ships without having passed a single test. Candidates who have lived through it describe the invariant and the pipeline rules, not just "commit the lock".