Introduction to Composer for Drupal Users

Composer is the recommended way to download Drupal core, contributes modules and themes, and any other 3rd party PHP libraries. While it's not strictly speaking required, we highly recommend taking the time to learn Composer and then using it to manage your projects.

Composer is also the preferred dependency management solution for PHP. List your project's dependencies in a composer.json file and, after issuing a few commands at the command line, Composer will download your project's dependencies for you. Use a couple more commands and you can update projects to their latest versions. Composer is analogous to NPM in the node.js world, or Bundler in the Ruby world.

Drupal core uses Composer to manage non-Drupal dependencies like Guzzle, and PHPUnit to name a few. Some (and more all the time) contributed modules also use Composer to integrate 3rd party PHP libraries into Drupal.

This series provides guidance for Drupal developers and site builders who would like to learn to use Composer to build and maintain a Drupal 8 application. It covers high-level concepts about Composer and walks you step-by-step through creating a new application, downloading PHP libraries, and implementing them using Composer. The tutorials within this series also cover Drupal-specific Composer configuration and provides guidance for accomplishing common Drupal tasks like updating core and installing a new module.

Composer is a command line application. Before diving in you'll want to make sure you're comfortable with Command Line Basics.

Author, Matthew Grasmick

Matthew, known as grasmash on Drupal.org, has been a member of the Drupal community since 2009. He maintains dozens of Drupal modules and the official Drupal Composer documentation. He is also the maintainer of Acquia's Build and Launch Tools, which automate Drupal 8 development, testing, and deployment processes.

Tutorials in this course
Drupal 7, 8, 9, and 10
More information

Composer is the preferred dependency management solution for PHP. List your project's dependencies in a composer.json file and, after issuing a few commands in the CLI, Composer will automatically download your project's dependencies and set up autoloading for you. Composer is analogous to NPM in the Node.js world, or Bundler in the Ruby world.

Drupal core uses Composer to manage non-Drupal dependencies like Guzzle and PHPUnit. An increasing number of contributed modules also use Composer to integrate third party PHP libraries into Drupal.

This series provides guidance for Drupal developers and site builders who would like to learn to use Composer to build and maintain a Drupal application.

It covers high-level concepts about Composer and walks you step-by-step through creating a new application, downloading PHP libraries, and implementing them using Composer!

It also covers Drupal-specific Composer configuration and provides guidance for accomplishing common Drupal tasks like updating core and installing a new module.

In this tutorial we'll:

  • Familiarize ourselves with the general concepts of dependency management
  • Learn about Composer and the role it plays in a PHP/Drupal project
  • Learn about some advantages and disadvantages of using Composer

By the end of this tutorial you should be able to explain what Composer is, what it's used for, and make the case for using it in your own projects.

Drupal 7, 8, 9, and 10
More information

This tutorial demonstrates the value of using Composer. This demonstration will employ the most basic use case of using Composer to create a new, non-Drupal application that writes a message to the system log. It will encompass the fundamental concepts of Composer installation, requiring (installing) a new dependency, autoloading it, and implementing it.

In this tutorial we'll:

  • Install Composer
  • Use Composer to start a new project
  • Use Composer to require a 3rd party dependency
  • Use the required code in an example application

By the end of this tutorial you should be able to explain the value of Composer, and have Composer installed and working on your local machine.

More information

Every Composer project is made up of a few standard files and directories. This tutorial provides an overview of the anatomy of a Composer project, and the essential files and directories used by Composer, including:

  • What are composer.json and composer.lock files?
  • What is in a composer.json file?
  • What is the /vendor directory?

By the end of this tutorial you should be able to recognize the standard files and directories in a Composer project and know what they are each used for.

More information

Composer packages use semantic versioning to allow you to differentiate among different releases of a project. Knowing how this works, and how to specify a version constraint when requiring a Composer package are an important part of using Composer.

In this tutorial we'll:

  • Get an overview of semantic versioning
  • Look at how Composer version constraints work and related best practices
  • Learn how to define Composer package requirements such that you can quickly update all of your application's dependencies without breaking existing functionality

By the end of this tutorial, you should understand how semantic versioning relates to Composer, and how to specify version constraints for packages in your Composer project.

Drupal 7, 8, 9, and 10
More information

Managing a Drupal application with Composer requires a few modifications to Composer's default behavior. For instance, Drupal expects that specialized packages called "modules" be downloaded to modules/contrib rather than Composer's default vendor directory.

Additionally, it is common practice in the Drupal community to modify contributed projects with patches from Drupal.org. How do we incorporate Drupal-specific practices like these into a Composer workflow?

In this tutorial we will:

  • Address all of the Drupal-specific configuration necessary to manage a Drupal application using Composer

By the end of this tutorial you should know how to configure Composer to work with Drupal, and drupal.org.

More information

When managing your Drupal project with Composer you'll use Composer commands to download (require) modules and themes that you want to install, as well as issuing commands to keep those modules and themes up-to-date when new versions are released.

In this tutorial we'll:

  • Cover step-by-step instructions for performing common Composer tasks for a Drupal application
  • Install and update Drupal projects (core, modules, themes, profiles, etc.) using Composer
  • Convert an existing application to use Composer

By the end of this tutorial you should know how to use Composer to install, and update, Drupal modules and themes.

More information

This tutorial provides an overview of the concept of an "artifact" and provides step-by-step instructions for deploying a Composer-managed Drupal application to a hosting environment.

In this tutorial we'll:

  • Define what an "artifact" is
  • Look at how to use Composer and a build process to create and deploy an artifact
  • Talk about the benefits of this approach

By the end of this tutorial you should have a general understanding of the steps required in order to deploy a Composer-managed project into production.

More information

You will inevitably encounter Composer issues that require troubleshooting. This tutorial aims to provide some general troubleshooting advice for common Composer issues.

In this tutorial we'll look at:

  • Common issues you'll encounter when using Composer
  • Solutions to these common issues

By the end of this tutorial you should have some ideas of how to solve common issues that you might encounter when using Composer to manager your application's dependencies.

Categories
Drupal 8, 9, and 10
More information

Drupal's development has a regular release cycle consisting of major, minor, and patch releases. Drupal releases use semantic versioning for its version numbers. Since we're committed to making sure our tutorials are kept up-to-date with the latest and greatest version of Drupal we figured it would be a good idea if you knew how to keep your Drupal site up-to-date with the latest "point" releases as well.

This tutorial will cover:

  • How to determine the type of update
  • The standard update procedure
  • Update Drupal using Drush
  • Update Drupal using Composer

This tutorial won't cover:

  • How to perform a major version Drupal upgrade, for example, from Drupal 6 or 7 to the latest version of Drupal. For that, see our guide, Learn to Migrate to Drupal.
More information

Drupal 8.8.0 introduced a bunch of new features intended to make it easier over the long-term to maintain a Drupal project using Composer. In doing so it establishes some new best practices, and moves into Drupal core solutions that were previously maintained by the community. This is all good news. But, it means if you're using Composer to update from Drupal 8.7.x or lower to 8.8.0 or higher you'll need to do a bit of additional work to untangle everything.

This tutorial is especially useful if you started your Drupal project using the drupal-composer/drupal-project template and would like to convert to use the new templates (i.e. drupal/recommended-project or drupal/legacy-project) included with Drupal 8.8.x core.

In this tutorial we'll:

  • Convert our project to use the new drupal/core-recommended, and drupal/core-dev Composer packages
  • Explain which commonly used Composer packages are deprecated, and which new ones replace them
  • Learn how to use the drupal/core-composer-scaffold Composer plugin
  • Cover tips for troubleshooting updates

Furthermore, in order to Upgrade to Drupal 9 from Drupal 8, you will first need to update your Drupal 8 site to at least version 8.8, as the upgrade paths for Drupal 8 site from before Drupal 8.8.0 have been removed from Drupal 9.

By the end of this tutorial you should be able to update your Drupal projects using Drupal core 8.7.x or lower to Drupal core 8.8.0 or higher using Composer. And be ready for an upgrade to Drupal 9.

More information

There’s no one-size-fits-all path to upgrade from Drupal 8 to Drupal 9, but there is a set of common tasks that everyone will need to complete.

In this tutorial we’ll:

  • Explain the differences between Drupal 8 and Drupal 9 that affect the upgrade path.
  • Walk through the high-level steps required to upgrade from Drupal 8 to Drupal 9.
  • Provide resources to help you create an upgrade checklist and start checking items off the list.

By the end of this tutorial you should be able to explain the major differences between Drupal 8 and 9, audit your existing Drupal 8 projects for Drupal 9 readiness, estimate the level of effort involved, and start the process of upgrading.

More information

As new major versions of Drupal are released, contributed modules need to be updated for compatibility. As of right now (October 2021) there are a lot of contributed modules with a Drupal 8 release and a patch in the queue to make them work with Drupal 9. However, there's no official Drupal 9 compatible release for the module, so the module can't be installed with Composer. This creates a circular problem where you can't composer require the module if you don't patch it, but you can't patch it until after it's been downloaded by Composer.

To help solve this common issue, Drupal.org provides a lenient Composer endpoint that publishes all modules as compatible with Drupal 9 regardless of whether that's true or not. By using it, you can composer require the module and then use cweagans/composer-patches to apply any necessary patches.

In this tutorial we'll:

  • Add the lenient Composer endpoint to our project's composer.json file
  • composer require a non-Drupal 9 compatible module
  • Use Composer to download and apply a patch that makes the module Drupal 9 compatible

By the end of this tutorial you should be able to use contributed modules that require a patch to be compatible with Drupal 9.

More information

There’s no one-size-fits-all path to upgrade from Drupal 9 to Drupal 10, but there is a set of common tasks that everyone will need to complete.

In this tutorial we’ll:

  • Explain the differences between Drupal 9 and Drupal 10 that affect the upgrade path.
  • Walk through the high-level steps required to upgrade from Drupal 9 to Drupal 10.
  • Provide resources to help you create an upgrade checklist and start checking items off the list.

By the end of this tutorial you should be able to explain the major differences between Drupal 9 and 10, audit your existing Drupal 9 projects for Drupal 10 readiness, estimate the level of effort involved, and start the process of upgrading.

This course appears in the following guides:
Categories
Site Building, Theming, Module Development
Drupal 9, 10
Categories
Site Building
Drupal 7, 8, 9, and 10
Categories
Module Development, Backend and Infrastructure
Drupal 7, 8, 9, and 10