One of the more confusing aspects of Composer is the purpose of the
Firstly, it doesn’t appear until you have initially run a
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
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
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.
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
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.
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
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
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:
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 :
"This file locks the dependencies of your project to a known state",
"Read more about it at https://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file",
"This file is @generated automatically"