What does "locked at" <tag> mean when running "composer update <package>"?

Question

I am trying to perform a composer update <package> but getting the following error:

The requested package <package> (locked at <tag>, required as <version>) is satisfiable by <package>[<tag>] but these conflict with your requirements or minimum-stability.

Meanwhile, the tag <tag> exists as a string only in my composer.lock file, which I thought was only modified by composer update, not read back.

I tried running composer why-not <package>, but its output didn't really explain the issue:

<program> <other-version> requires <package> (<version>)

What does 'locked at' mean in this context and how do I solve the issue?

Answer 1

The package is locked means the commit-hash of the last commit on the branch used with version-constraint dev-<branch> was saved during the last run of composer update in the lock-file to ensure deterministic (reproducible) builds upon deployment.

This commit-hash or tag is written to your lock-file (composer.lock) if you:

1. run composer update [<package>]

... or ...

2. run composer install with a composer.json present but not a lock-file in composer's current directory which does auto-generate the lock-file

Answer 2

When you specify a package name to composer update (e.g. composer update somevendor/somepackage), you're telling Composer that you want to update that package and leave everything else at the current version - you want to "lock" all the other packages where they are, and just update one.

That will only work if the new version of the package you specify is compatible with those already installed packages. If the new version requires a newer version of something else, or lists that it "conflicts with" a particular version, Composer will simply tell you that it can't do it.

The versions that the other packages are "locked at" are stored in the composer.lock file, but you should never edit that file by hand.

You have a few ways to tell Composer which packages it's allowed to update:

• Update more than one specific package at a time to resolve the specific problem: composer update somevendor/somepackage somethingelse/somedependency
• Update the selected package and all its dependencies except the ones you've listed directly in your composer.json: composer update somevendor/somepackage --with-dependencies
• Update the selected package and all its dependencies: composer update somevendor/somepackage --with-all-dependencies
• Just update everything: composer update with no arguments at all

All of these commands will still respect the version constraints you've specified manually in composer.json, you are just giving Composer additional instructions on the command-line about which packages it's allowed to update to meet those constraints.

Personally, I would advocate just running composer update with no arguments: if you want tighter control over when something gets updated, you can always list a more specific constraint in composer.json.