Understanding composer.lock

composer.lock records the exact dependency graph selected by Composer. It makes application installs repeatable across developer machines, CI, staging, and production.

Working Knowledge

• Commit the lock file for applications.
• Use composer install to install locked versions.
• Use composer update vendor/package for a deliberate targeted update.
• Review transitive package changes, not only the package named in the command.
• Regenerate the lock file through Composer rather than hand-editing it.

Install Versus Update

composer install
  uses the versions already selected in composer.lock

composer update monolog/monolog
  asks Composer to resolve an allowed newer version and rewrite the lock file

Use targeted updates when changing one package. A broad composer update may change much more of the dependency graph than the task requires.

Review The Lock-File Diff

Do not hand-edit composer.lock. Let Composer regenerate it, then inspect:

git diff -- composer.json composer.lock
composer audit

Look for the intended package, transitive changes, removals, newly installed plugins, changed source URLs, and platform requirement changes.

Applications And Libraries

Applications normally commit the lock file so CI and production install the tested graph. Reusable libraries are different: consumers resolve the library inside their own application graph, so library lock-file conventions vary. Follow the repository's existing practice.

In Application Work

A lock-file diff is part of the code review. Large unexpected dependency changes are a reason to stop and understand what the resolver selected.

What To Check

Before moving on, make sure you can explain repeatable installs, run a targeted update, inspect transitive changes, and describe why application and library repositories may treat lock files differently.