Versioning in Composer

Written by Antony D'Andrea

Composer is an incredibly simple, yet powerful tool for installing 3rd-party libraries into your projects. I can't imagine life without it! I have previously written about composer and how to set it up. This post will be about how to fine tune the versions of the libraries that you use.

What not to do

It is very easy and tempting to install your libraries like this:

{ 
    "require": { 
        "symfony/yaml": "*" 
    } 
}

* is a wildcard character that will default to the very latest version of whichever level of the version you use it.

For example, 2.* will give you the very latest version of version 2, but no higher. Using * alone will give you the very latest.

In both those cases, you could have some issues (especially the first one). You do not know that a library will always be compatible with your project and whilst it is easy to just say "always keep it up to date", you could one day find yourself missing features and breaking your project.

In my opinion, the wildcard should only be used on the hotfix level, e.g. 2.3.*. But it depends on the library and their method of versioning and their policy of breaking backwards compatibility. So always check their documentation.
https://getcomposer.org/doc/articles/versions.md

Other operators

So, what can you do in the composer file?

Greater than, less than
Let's say that you know about a particular backwards incompatible change and you want to ensure that your version is always kept less than a certain version, you can use the standard less-than, greater-than symbols to achieve this:

{ 
    "require": { 
        "symfony/yaml": "<2.3.4" 
    } 
}

You can use, <, >, <=, => and !=. You can also create ranges, for example:

 { 
    "require": { 
        "symfony/yaml": "<2.3.4, >=2.3.0" 
    } 
 }

Valid versions to be installed in this example are: 2.3.0, 2.3.1, 2.3.2 and 2.3.3.

You can also specify a range using an hyphen, -. For example, the above could be written like: 2.3.0 - 2.3.3. A little gotcha: if you use a partial version, for example, 2.3 - 2.4, it would be appended internally with a wildcard, so 2.3 - 2.4 would be treated like 2.3.* - 2.4.* and install versions over 2.4.0 but less than 2.5.

Tilde
The tilde symbol, ~, or as I call it, the sqiggly line, is used to sort of express a range of versions like above.

An example:

{ 
    "require": { 
        "symfony/yaml": "~2.3.4" 
    } 
 }

Is the same as doing a range like:

{ 
    "require": { 
        "symfony/yaml": ">=2.3.4, <2.4.0" 
    } 
 }

So it is used to state the minimum version but do not go over to the next 'bigger version' if that makes sense. Again, it depends on the project, but this would protect against any potential backwards incompatible changes. You can do ~2.3 which would keep upgrading but not to 3.0.0. It depends on the versioning policy of the project as to what exactly you do.

Caret
The caret operator, ^, is also a range operator but rather than just strictly looking at the numbers of the versions, it works on the versions themselves and allows and non-breaking updates to happen.

For example, as I said earlier, ~2.3.4 is the same as >=2.3.4, <2.4.0, but ^2.3.4 is the same as >=2.3.4, <3.0.0, because there shouldn't be any breaking changes before version 3.

Summary

I hope that this has begun to show you what you can do in composer. A full explanation and more information of what I have written about today, can be found on their website here. Happy composing!

© 2012-2023