Using the superpowers of Composer in Drupal development

28 Sep 2020

There are tools that make Drupal development much easier, faster, and more efficient. Imagine all components and packages on a project working in perfect harmony like a well-tuned orchestra. This is possible thanks to Composer! Read further to learn more about Composer and its special powers in Drupal web development.

A little introduction: what is Composer?

Composer is a command-line package management tool for PHP-based projects. Examples of its “colleagues” in the world of other programming languages include NPM for JavaScript and Bundler for Ruby.

Composer allows you to use third-party packages without hassle. Just “tell” this helpful assistant which libraries your project depends on, and it will manage them for you (download in the right versions, validate, update, and so on). All you need is to have the packages listed at the heart of Composer — in the composer.json file, and then to execute a few CLI commands.

The tool is widely used by the PHP community by developers, site builders, and other experts involved in web development. The statistics from the Packagist, the PHP Package Repository, show that there are currently 280+ thousand packages available to install via Composer and they have been installed 28+ billion times.

Why use Composer in Drupal development?

Drupal 8 has embraced Composer in its core, which has allowed it to fully take advantage of powerful libraries like Symfony components. This has transformed Drupal development practices and made them “composerized.” Composer is now a preferred solution for managing the Drupal core, contributed modules and themes, and all third-party libraries.

Even those who are a bit intimidated by the command-line and prefer other ways of installing or updating the modules, also appreciate Composer with time. Here are just a few reasons why using the tool is cool:

  • Composer saves a lot of your time and effort in everyday web development routines related to managing your ever-growing list of packages. For example, it can be very tedious to manually download libraries next after installing modules, as well as keeping them all updated.
  • It can help you avoid various issues and inconsistencies in your website’s work. For example, some contributed modules will simply fail to work if installed in a way other than via Composer, especially ones using third-party libraries or need specific versions of PHP and Drupal. Usually, the creators of contributed modules mention this in the module descriptions. However, it’s better to have a unified approach to module installation and use Composer for all of them without exception.
  • It’s hard to overestimate Composer’s great advantage — it builds bridges between the non-Drupal components and Drupal projects, making it possible to fully leverage various libraries’ capabilities with no need to reinvent the wheel.

How to work with Composer in Drupal development

Let’s review some examples of tasks Composer can do for you. But it all begins with installing the tool on your development environment.

Installing Composer

Start with downloading Composer from getcomposer.com that has detailed instructions. To provide the correct work of all the packages when the website goes live, make sure the PHP version on your development environment matches the one that will be used on the production environment.

The logic of key Composer commands

Basically, all Composer commands are built around the three key actions widely used in Drupal web development:

  1. Installing a package: composer require [vendorname]/[packagename]
  2. Updating a package: composer update [vendorname]/[packagename]
  3. Removing a package: composer remove [vendorname]/[packagename]

Let’s look at them in more detail right now.

Downloading the Drupal core via Composer

The best web development practice is to start a new Drupal site than using Composer. For downloading the Drupal core, there is a famous special template called drupal-project. However, beginning with Drupal 8.8.0, the official template has changed to drupal/recommended-project. The use of the recommended template ensures consistency in the versions of the Drupal core dependencies.

It will provide a Composer project template to start a new project. Composer will create a project called project-name-dir and automatically download the latest Drupal version with all the necessary dependencies. It executes the “composer install” command for all required projects listed in the composer.json file of the template.

To download the Drupal core, you will need to run the following command:

$ composer create-project drupal/recommended-project [project-name-dir]

If you prefer a specific version of the Drupal core, you can provide it after the colon:

$ composer create-project drupal/recommended-project:9.0.0 [project-name-dir]

When Composer completes its task, you can go to your new website’s URL in the browser and finish the Drupal installation. You will be asked your database credentials (name, username, and password), site name, email address, password, type of Drupal installation profile, and so on.

Switching your existing project to the recommended template

What about existing projects that are not based on the Drupal/recommended-project template (for example, because they use an older version of Drupal than 8.8.0)? Moving to the recommended project will give them a lot of benefits (always getting the right versions of packages, avoiding compatibility issues, strong support from the community, and more). You should also move to the recommended project when upgrading to Drupal 8.8.0 or higher.

This migration involves replacing the packages with the ones used in the Drupal/recommended-project template. The key meta package there is the drupal/core-recommended. Its great difference from the traditional drupal/core package is that it guarantees your site gets the right versions of dependencies tested for your current version of Drupal.

For example, to replace the current drupal/core with the drupal/core-recommended for Drupal 8.0, you can use these commands:

$ composer remove drupal/core --no-update
$ composer require composer/installers:^1.7 --no-update
$ composer require drupal/core-recommended:^8.8 --no-update

Downloading contributed Drupal modules and themes via Composer

To download a contributed project, go to the root of your Drupal install and run this command:

$ composer require drupal/[modulename]
For example:

$ composer require drupal/ctools

When entering the module or theme name, stick with the machine name that can be found in the URL of this contributed project’s page. This is important because the machine name (e.g. “ctools”) and the actual name (e.g. Chaos Tool Suite) may differ.

You can require multiple modules within the same command by typing drupal/[modulename] for each of them and separating them with a space.

With the require command, Composer will download the module or theme with all its dependencies, as well as add it to your composer.json file. You will just need to enable the downloaded module — either on the Extend tab of your Drupal admin dashboard or using command-line tools like Drush or Drupal Console.

If you want the module to only work in the development environment and never be used in production, you can add the “--dev” as in this example:

$ composer require --dev drupal/ctools

Downloading specific module versions via Composer

In most cases it would be fine to just tell Composer the name of the module. However, you may need a specific version of the module or theme — for example, if this is the only version compatible with your project. Get it by putting a colon after the module name:

$ composer require 'drupal/[modulename]:[version]'
When specifying the version, you need to bear in mind that the Composer syntax doesn’t include Drupal versions like 8.x. For example, to get the 8.x-3.4 release of the Chaos Tool Suite module, you should write the command as follows:

$ composer require 'drupal/ctools:^3.4'

Read more details about the tilde (~) and the caret (^) constraints in specifying the Drupal module version. In addition, as you can see, this command is used with quotes in the example, which is recommended in order to avoid potential issues with different terminals.

Updating the Drupal core via Composer

Drupal core is also a package. When the time comes to update it, you can rely on this command (and then also do not forget to update the database):

$ composer update drupal/core-recommended --with-dependencies

Updating modules and themes via Composer

When you need to update a contributed module or theme, rely on the command as in this example:

$ composer update --with-dependencies drupal/ctools

By adding “--with-dependencies”, you make sure Composer updates all packages the module depends on and not just the module itself.

Here is also the command that automatically updates absolutely all packages listed in the composer.json file:

$ composer update --with-dependencies

Removing modules and themes via Composer

It’s a routine task to remove contributed modules or themes in Drupal development, for which you should run a Composer command as in this example:

$ composer remove drupal/ctools

Before removing a module with Composer, it’s necessary to remove it in the admin dashboard as well.

Updating Composer

While taking care of the latest versions of everything, Composer itself needs to be updated, for which there is a special command:

$ composer self-update

To wrap up

This has been just a quick overview of what Composer can do in Drupal web development. We would like to emphasize once again that managing Drupal projects with this tool is the best practice that improves the development efficiency. Whenever you need custom Drupal development or other Drupal services, choose teams that adhere to the standards! One of them is here for you.

Truly yours,
Golems.