How to Build a Drupal Site with Composer, as Seen at DrupalCon

April 19, 2018
6 minute read

Fellow Acquian Matthew Grasmick and I just presented How to build a Drupal site with Composer AND keep all of your hair at DrupalCon Nashville, and though the session wasn't recorded, we posted the slides and hands-on guide to using Composer to manage your Drupal 8 sites to the linked session page. I wanted to dive into the session a little bit, because it was popular enough that many people couldn't even get in since the room was so full! Matthew, in case you didn't know, is the creator and a maintainer of Acquia BLT, a tool used to build, launch, and manage Drupal applications using all the best practices we've learned over years of Drupal experience at Acquia. And I'm the maintainer of Drupal VM, among other open source projects like an Ansible role for installing Composer. Both Matthew and I have a lot of experience with Composer, and we tried to distill as much of that as possible into this two-hour session. BLT heavily relies on Composer to bundle together and package up not only Drupal and contrib modules, themes, and install profiles—it also uses Composer to manage a local development environment (Drupal VM, currently), functional testing tools like Behat, and tools to help teams manage patches, front-end dependencies, and more! Unfortunately, most Drupal 8 applications that already exist weren't built with Composer, so teams who want to take advantage of all the things Composer has to offer are missing out until they convert their codebase to use Composer, or set up a new project using BLT or another popular Drupal application setup template, the Composer template for Drupal projects.

Composer Basics

To help people ease into the idea of using Composer, Matthew first walked through a very simple example of using Composer to build a very tiny PHP logging app based on Monolog, a PHP logging library available from Packagist. The basic outline was:

Use Composer to start a new PHP project's codebase (composer init).
Use Composer to require monolog (composer require monolog/monolog).
Add a tiny amount of code in index.php to log something with Monolog to a log file.
Run the new PHP project and see what happens!

Matthew's example was a great introduction to how Composer works, on a basic level, as a dependency management tool for PHP projects: How Composer resolves dependencies and installs vendor packages. This entire example is also laid out, step-by-step, in our Hands-on Drupal & Composer Agenda, if you want to try it out yourself.

Drupal and Composer

Moving on from a basic Composer example, Matthew jumped into some of the additional complexities involved in using Composer with Drupal projects. His slides presented dozens of ways you can ease the pain of managing a modern Drupal 8 codebase, and included examples for how to:

Manage core and contrib patches effortlessly.
Manage security updates and version constraints.
Automatically place dependencies in the right locations (install profiles in profiles/, modules in modules/, themes in themes/, etc.)
Safely scaffold Drupal core's 'special' files like .htaccess, index.php, robots.txt.
Integrate helpful Drupal tools like Drush and Drupal Console straight into your project.

Install Drupal modules using Composer. The example (which also has a guided walkthrough in our hands-on guide that accompanies the presentation) walks you through creating a brand-new Drupal 8 project, all the way from installing PHP and Composer on your computer, to running Drupal 8 locally so you can test everything, and it even gives examples for how to deploy the production website to the Cloud, excluding development dependencies which should only be used locally when developing and testing your Drupal project! Development and Production build artifact generation using Composer. For many Drupal 8 projects, it is necessary to use Composer to manage the project codebase, and this presentation gives you all the tips and tricks to make that process painless. During the question and answer portions of the session, many additional follow-up questions were asked, like:

What's the best way to update Drupal Core? And how long after Drupal Core updates for a new security release are those updates available on Packagist so we can update using Composer?
What if my current Drupal 8 site isn't already using Composer? What's the best way to convert my codebase to use Composer?
What if I'm using a Windows PC? Is it as easy to use Composer to manage my project on Windows?

Some of these questions we could answer during the session, but a few remain open questions (or at least have room for improvement) in the Drupal community. I'd encourage anyone interested in improving the developer experience with Composer and Drupal to follow these issues in the Drupal issue queue:

The Drupal Community just started using Composer in a big way a couple years ago, and there are definitely a few growing pains—but we're working through them, and now is better than ever to dive into learning Composer and Drupal!