Most PHP projects eventually pull in open source libraries from Composer. They make complex topics easier (PDF manipulation, software development kits for APIs, user authentication helpers, etc).

All of these Composer dependencies must be updated regularly to avoid security holes or incompatibility issues with our constantly evolving software practices.

Updating Composer dependencies in PHP projects all the while avoiding regressions can be daunting.

How to figure out what might break

Some Composer packages provide a CHANGELOG.md file, which is a great way to know if updating will break a website. But reading through dozens of changelogs can take a long time.

Because most Composer packages (or at least well known ones) rely on SemVer to publicize what might have changed between two releases, there is usually no need to read through changelogs.

SemVer says that any software packages should have a version of the form <major>.<minor>.<patch>, for instance 5.1.34.

Whenever the major part changes, there is a breaking change in the package. That means we will have to verify if our code is affected, or else something might stop working.

Whenever the minor part changes, there is a new feature in the package but it shouldn't break existing code. In practice, I've experienced breakages with minor version changes, so tread carefully.

Whenever the patch part changes, a bug was fixed. This is non-breaking, unless we "used" the bug as expected behavior, which we should avoid if at all possible.

How to leverage this information with Composer

As we just saw, only major and minor version bumps usually break our software. That means that we only need to read the changelog files of packages which have had their major or minor version updated.

In a large project with lots of dependencies, how can we know what was updated ?

First, update composer.json to reflect our needs.

Then, run composer update, which will overwrite the composer.lock file and lock-in dependency versions (which helps with reproducible builds).

composer-update-status

Then, run the following command, which shows only packages which have changed versions:

git diff composer.lock | grep -B1 -E '            "version"'

The output looks like this:

composer-update-diff

From there, take a closer look at the changelogs from packages for which a major or minor version change has occured. If need be, update the PHP code to reflect those changes so that our website keeps running properly.