How to (Force) Update Your composer.lock

When using Composer, you might know that you should almost always include the composer.lock file in VCS.

Now, the lock file includes a hash, which is generated from the contents of the composer.json file, and more. Therefore, changing something in this file, for example, the description, or something in the extra or config sections, will invalidate the hash that is currently included in the composer.lock file.

If you try to interact with Composer, with an outdated lock file, it will tell you:

tfrommen@XPS:/hm/foo/bar (main * u=)$ composer install
Loading composer repositories with package information
Installing dependencies (including require-dev) from lock file
Warning: The lock file is not up to date with the latest changes in composer.json. You may be getting outdated dependencies. It is recommended that you run `composer update` or `composer update <package name>`.

So, the question is how to refresh the lock file, right?

Well, Composer already said to run either composer update, and thus update any package to the most recent version according to your version constraints, or composer update <package name>, which still means updating, but just a single package. However, most of the time, you might not want to do this.

If you needed to change some config value—for Composer itself, or something else—can’t you just update just the composer.lock file?

Yes, you can! And it’s even—somewhat hidden—in the official documentation:

composer update --lock

The above command will update the lock file, and nothing else.

It’s rather simple, but I don’t think a lot of people know about this, which is why we sometimes run into outdated composer.lock files.

Maybe now not any longer…?

By the way, if you want to prevent this from happening, you could easily make composer validate a required step in your build routine.

tfrommen@XPS:/hm/foo/bar (main * u=)$ composer validate
The lock file is not up to date with the latest changes in composer.json, it is recommended that you run `composer update` or `composer update <package name>`.
./composer.json is valid

If you don’t care about unnecessary extra information, use this:

composer validate --no-check-all --no-check-publish