Composer dependency guidelines

Introduction

This page describes general guidelines that should be followed when working with a project that uses composer to manage dependencies.

Guidelines

Prefer composer install over composer update

Installing dependencies using composer install instead of composer update ensures that the lock file is being used. composer update ignores the lock file completely and installs all dependencies at their newest version, possibly risking random failures of the project.

Commit composer.lock

Lock files ensure that packages are installed exactly the same way they have been installed when the composer.lock was created. This means that a project does not randomly break when a dependency receives an update that introduces breaking changes (this even occurs on patch releases sometimes and cannot be avoided!).

You should therefore always commit your composer.lock. There is one exception though: If the project is a plugin, the composer.lock should not be committed! Plugins should always work when you add them using composer require.

You can read this blog post to find out more about the rationales behind using a lock file.

Only update our packages automatically

When a project references some of our composer packages, it might be tiresome to update the lockfile every time a package changes. To mitigate this, you can only update a specific set of dependencies.

For example, to update only packages in the scope ambimax, run the following command after a composer install:

composer update 'ambimax/*'

This updates the respective packages and creates a new lock file. This lock file does not need to be committed, as it only contains changes introduced by these packages.