Upgrading to Composer 2

The new major version of Composer has been available since the end of October 2020 and was announced with this post on the Packagist blog. Let’s see the most relevant improvements and how to upgrade to the new version.

Performance improvements

Probably one of the most important improvements about speed: it’s possible to see a 50% reduction of the time it takes to bootstrap an empty project, depending on the configuration. This is thanks to:

• Package management refactoring which produces a more efficient memory usage and less network traffic.
• Parallelization of HTTP requests (which requires ext-curl to be installed)  and usage of HTTP/2 features to reduce network traffic.
• Packages unzipped in parallel to reduce CPU usage, which requires cli command unzip available in your $PATH (available on Linux, macOS or WSL).

Package management enhancements

The workflow for installing and updating packages has been updated for better performance and stability. The update and install commands are now independent:

• The update command now resolves dependencies and writes the lock file.
• The install command downloads the packages not in cache and installs/updates/removes them.

When you run the update command, install will automatically be executed after the update is completed, so nothing changes for the user compared to the current workflow.

In addition:

• The update command now doesn’t use the state of the vendor directory, which in the previous version could have led to problems when the vendor directory and lock file were not in sync (for example, for a previous local upgrade attempt).
• The require, remove and partial update commands are faster because they now load only metadata needed by the package.
• The install command now first executes network related tasks and, if successful, proceeds installing packages, avoiding a partial update of vendor folder in case of network problems.
• The --dry-run option is available also for the require and remove commands.
• You can use temporary constraints when running partial updates, which is useful for when you want to test a specific version of a package or you are waiting for a bug fix and you don’t want to update composer.json file.

Error reporting

There are several improvements on errors reporting, making them more clear and helpful.

Conflicting version on package dependency

Trying to install a package whose dependency conflicts with one of your requirements:

Requiring non-installable package

Trying to install a package that conflicts with a dependency of one of your requirements:

Repositories

Composer 2 introduces new features in repository management aimed at better performance and security.

Canonical repositories

Composer searches packages in repositories in the order they are set in the composer.json file, assigning higher priority based on the order. 

Composer 1 treats all repositories as non-canonical, meaning that when a package is found in an higher priority repository, it can be replaced by a lower priority if it has a newer version (packagist.org is appended at the end of the repositories list with the lowest priority level).

With Composer 2, all repositories are instead canonical by default: when a package is found in a canonical repository it will not be searched elsewhere. If you want to keep the old behaviour, you need to tag the repository as non-canonical:

Filtered repositories

With Composer 2, you can filter which packages can (attribute only) or cannot (attribute exclude) be loaded  from a repository.

More on this topic can be read in this article.

Platform check

Composer 2 has a new feature that checks your environment requirements at run-time before autoloader initialization: this feature is enabled by default. By default only the PHP version is checked, but you can also check the extensions by setting "platform-check": true  in the "config" section of your composer.json file. 

When enabled, a platform_check.php file is created when the autoloader is dumped or updated; whenever the autoloader is loaded, it will first check the requirements and exit the application if they’re not met.

For example, this message will be shown when the PHP version requirement of a Symfony application is not met:

Composer detected issues in your platform: Your Composer dependencies require a PHP version “>= 7.3.0”.

To avoid issues in production (if you enable the platform check), it is recommended to run php composer.phar check-platform-reqs in your production environment during deployment.

Other features

There are lots of other features and improvements, just to mention a few:

• The pear repository type was removed;
• New API for plugins.

For a complete list you can read the Composer 2.0 changelog.

How to upgrade

All you have to do to upgrade to Composer 2 is to execute this command:

php composer.phar self-update --2

The --version option was added to the self-update command with version 1.10.2; if you’re using an older build, running

php composer.phar self-update

will do the trick.

Backwards compatibility

Lock file format and commands syntax remain the same, so there’s no need to update your code. 

As highlighted in the Composer upgrade guide, potential issues with the upgrade could arise from:

• Plugins in use: all plugins need to be updated to implement the new interface. If you’re using a plugin that has not been updated, Composer 2 will fail showing a message like this: “You are using Composer 2, which some of your plugins seem to be incompatible with. Make sure you update your plugins or report a plugin-issue to ask them to support Composer 2“.
• Platform check: you need to check that your production environment fulfills the PHP version before enabling the runtime check (use the check-platform-reqs command during deployment, and remember to do it against the PHP process that runs in production, not against the CLI one). If you expect some kind of issue, consider disabling the platform check.
• Repositories: check that canonical repositories don’t change the way your packages are resolved, as described above.
• PSR-0/PSR-4 configuration: classes that don’t respect PSR-0/PSR-4 will not be autoloaded anymore: check that directories/files match class names. See PSR-0 and PSR-4 documentation for more details.

---

Finally, thank you to all the contributors for all the new features and for keeping Composer updated.