Upgrading to Composer 2: good reasons and key instructions

One of the goals of our blog posts is to spread the word about the best web development practices. When it comes to the best practices for PHP-based CMSs like Drupal, the famous package manager Composer is always on top of the list. Some time ago, we published an article about the superpowers of Composer in Drupal development but would also like to dedicate a special post to its new release. Read on to see why it’s a great idea and how to upgrade to Composer 2.

Why upgrade to Composer 2

Composer has been around for 8 years performing its mission of a great assistant to developers in installing, updating, or removing all kinds of PHP packages. The major new version of this dependency management CLI tool was released in October 2020.

Version 1 is actually deprecated. Jordi Boggiano, one of the tool’s creators, says in his release announcement that v1 will continue receiving critical fixes, but it should be everyone’s goal to upgrade to Composer 2 as soon as possible. In the Composer 1 deprecation notes, he also says they are going to support the v1 metadata format just because they do not want to disrupt too many workflows, but this mission is not easy due to a number of issues.

However, it’s not just the v1 deprecation that should inspire you to upgrade — there are many much more positive reasons for upgrading to Composer 2. These are, of course, its numerous improvements in the sphere of performance, architecture, runtime, and more. Let’s take a closer look at its most prominent new features that make your Composer upgrade a very lucrative idea.

What’s new in Composer 2: an overview of key features

Improved performance

The dependency management tool has a noticeable performance boost, as well as memory and CPU usage optimization in its v2. Here are some of the changes that are very helpful for faster work without losing time:

• The parallel download functionality using curl is available out-of-the-box.
• The previously installed packages are now ignored, which speeds up the update process.
• The install command does not change the vendor folder until all the packages are installed.

Jordi Boggiano offers a comparison between v2 vs v1 performance for Drupal, Laravel, and Symfony. An initial update and installation for the Bootstrapped projects with an empty cache and ext-curl enabled take roughly 60% less time.

Partial updates possible

Updating a single package to a particular version without updating your “require” in composer.json is now easy — you will just need to constrain the needed version. Here is an example of a command that will update only the vendor/package to a specific version with constraints imposed:

composer update vendor/package:1.0.*

Offline work

Composer 2 can partially work offline, which you may find very useful when having a slow connection or running a benchmark. The tool will try installing the packages based on the composer.lock file and the cached versions of the packages and metadata. To get this to work, you will need to:

• make sure your composer.lock file is in place
• set the COMPOSER_DISABLE_NETWORK variable with the value of 1 in your environment variables or add it when running commands — like this:

COMPOSER_DISABLE_NETWORK=1 composer install

You will then see warnings that the network is disabled but the dependency manager continues the job anyway. If there are any packages that are not cached, you will also get notified about this.

Dry-run mode for some commands

Sometimes developers need to simulate an installation without actually installing a package just to see what happens. This is where the dry-run mode comes in. In v2, it’s possible to use dry-run with the popular “composer require” and “composer remove” commands.

Runtime platform check

Composer 2 has a new platform_check.php file whose mission is to check your server environment before the autoloader is initialized. Namely, your PHP version and extensions (optionally) are checked for matching your project’s dependencies. If something is wrong, you will get an error with detailed explanations.

Running Composer as root with a confirmation

Whenever you attempted to run commands in v1 as the super user (root), you saw a message that you should not be doing this. In v2, you need to confirm your decision to continue as root with a “yes” in the CLI. Your terminal should support the interactive mode for you to see this confirmation message. This new feature will prevent possible human errors on the part of the super user running the dependency manager.

New options for multiple repositories

Despite the fact that packagist.org is Composer’s default repository, most projects use other repositories as well. If we talk about Drupal websites, they have their official Composer repositories. V2 allows you to configure the details of how the tool should work with multiple repositories for the same project in the composer.json file. Among them are the following:

• Priorities. You can set the repository priorities so that a specific repository order is followed when the tool is looking for packages. As long as the dependency manager finds the package, it stops looking in lower-priority repositories.
• Canonical repositories. For v2, all repositories are canonical. If a package is found in one repository, other repositories cannot provide the same package.
• Filtering. You can set up filtered package search using the “only” and “exclude” directives in the repository configuration. For example, with the “only” directive used, the tool will only search for packages with drupal/* in your Drupal repository. The “exclude” directive, on the contrary, excludes packages from search.

How to upgrade to Composer 2

The above-described features are just a few examples of what the new release of the dependency manager has to offer. All you need to do is to perform the upgrade so you can make the most of its new features and use a version with full support. But is it easy to do the upgrade?

The creators say it was their priority to make it easy for everyone to upgrade to Composer 2. They achieved this thanks to the following:

• V2 supports PHP versions as old as 5.3 (however, the support is very likely to be stopped in the next major Composer release).
• If something goes wrong with the upgrade, you can just roll back to v1 thanks to the interoperability of the composer.lock files.
• Composer 2 has basically the same commands and arguments as Composer 1.

To upgrade to Composer 2, you can run this command:

composer self-update --2

If you come across any issues like your project’s incompatibility with v2 or any others, you will be able to roll back using this command:

composer self-update --1

Here are some things to pay attention to when upgrading Composer:

• If you have an automatic installation process and want to stay with v1 for now, add the --1 argument to the composer-setup.php or other installer script you are using. However, think of it as a temporary decision.
• If you see an error saying that the "self-update" command is not defined, you will need to find out the path to where the dependency manager is installed (for example, /usr/bin/composer) by running the which composer command and then add --install-dir /usr/bin --filename composer (or adjust this based on your path) to the php composer-setup.php/ line.
• Plugins are considered to be the main source of possible troubles with Composer upgrade because they need to be updated to support v2. If there is a plugin that does not support it, Composer will show warnings and will not resolve the dependencies.
• The most common Сomposer 1 to 2 upgrade issues and workarounds are listed on github, as well as directions based on a particular CMS (Drupal, Symfony, Laravel, and more), with exact lists of plugins that need to be updated or removed for the successful upgrade process.

Final thoughts

We know from our experience how important it is to follow the best web development practices and use the newest versions of useful software. Hopefully, our post will inspire you to upgrade to Composer 2. Drop us a line if you ever need help from a strong web development team!