Composer Lock & Colleague Hair Loss

beethoven the grumpy composer
Right, that’s it sonny, your name is going on my list

One of the more confusing aspects of Composer is the purpose of the composer.lock file.

Firstly, it doesn’t appear until you have initially run a composer update.

Except when it does – which is when you join a project that’s already in progress.

If you clone an existing modern PHP project, you *should* get the composer.lock file, alongside the expected composer.json.

If you open your composer.lock file, it’s a big old file, packed full of JSON, but because it has the extension of .lock, it has no syntax highlighting.

Ok… close file. That was scary. What was all that?

Locking in the Fun

When a modern PHP project is born, usually a small handful of entries are added to your composer.json file.

Things like Symfony, or PHPUnit, or any of the 69,632 other packages that live on packagist. (Hey, that figure was accurate when I wrote this).

Then you run composer install, and aside from pulling down all those remote files and stashing them helpfully in your vendors directory – and creating the vendors/autoload.php file – composer creates a record of the exact installed versions of each of those dependencies.

An example of the ‘require’ section in a composer.json file, taken from a Symfony project

So What?

A Quake 1 LAN party, according to Google.

You may wonder why this is important. Without giving it much initial thought, I felt the same way.

The reason is: stuff changes.

I’m not talking about code you change – I’m talking about the code in your vendors folder.

Development is often tricky enough with your own code. Letting your dependencies update at will is like playing Quake 1 on Nightmare.

It’s a fair assumption to think those Symfony dependencies are going to be used together frequently.

Symfony’s test suite likely encompasses the various interactions relatively well, and 99% of the rest of them are going to be caught by the many, many users of Symfony.

But what about the third party dependencies you have specified for your particular project?


Chances are, many fewer people will have used this particular combination of dependencies.

And just look – two packages are set to dev-master – whilst sometimes unavoidable, this is exactly the sort of thing that’s going to lead to sad panda situations.

Colleagues and the Composer.lock File

If you can live with your dependencies potentially breaking your project in subtle, and unexpected ways – then that’s your call.

However, if you are part of a team, the composer.lock file suddenly becomes very, very important indeed.

conmposer lock out of sync

This is the sort of situation that leads to bad times.

The problem here is that whilst someone updated the composer.json, and they may very well have ran a composer update afterwards, and the dependencies they got still led to some nice green tests…

But they forgot to commit the resulting composer.lock file.

And that means that we too now need to run the composer update command.

The thing is, if we have dependencies on projects that are using dev-master, for example, we are very likely to get a different commit to what our team mate got when they originally changed the composer.lock file.

This leads to sometimes subtle, sometimes glaringly obvious bugs. Bugs of someone else’s making. The worst kind of bugs.

Not to mention all the other weird issues that you might run in too.

Let’s imagine that the composer.json file is telling you that Symfony is now at 2.7, but you might hit strangeness like this when trying to add in a new dependency:

a classic case of composer hatred

That might set you back ten minutes, half an hour, a couple of hours on a particularly bad afternoon.

But what about a junior team member?

I Never Use dev-master, Am I Safe?


Take a look at this guide on understanding Composer’s versioning syntax.

I think the tilde operator is the most confusing of all.

And even if you use definitive versions, you still can’t be sure someone didn’t delete and recreate the tag you are relying on.

Only the composer lock file holds the definitive proof because it records the exact commit hash / signature, and then until the composer lock file is next updated, everyone who installs using composer will get the expected version of each dependency.

Clever, but confusing 🙂


Can’t be bothered reading all that eh?

Well, if you open up any composer.lock file, right there at the very top you’ll find :

    "_readme": [
        "This file locks the dependencies of your project to a known state",
        "Read more about it at",
        "This file is @generated automatically"

Published by

Code Review

CodeReviewVideos is a video training site helping software developers learn Symfony faster and easier.

One thought on “Composer Lock & Colleague Hair Loss”

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.