Drupal 8.8 is out today! This will be the last (minor) release of Drupal 8 (thanks Eli-T) and we are now looking at the release of Drupal 9 soon. Among the many improvements, we’ll talk about the developments in the composer initiative in Drupal.

For years, we have been using webflo’s composer template as the quasi-official template for starting up Drupal projects. It’s well supported and did its job well. Still, it seemed unofficial for someone who wouldn’t be into the community conversations. With Drupal 8.8, the community did amazing work to bring this into core and Drupal’s infrastructure. If you are starting a new project on Drupal today, all you have to do is follow the change record or the updated composer documentation to get started.

Note: You don’t have to use the new recommended template, but–like the name says– it is recommended you do. It locks all Drupal core dependencies to known and tested versions. If you like to be on the bleeding edge of your dependencies, then continue using drupal/core.

Existing Sites

Here, I’ll talk about updating the existing sites which used webflo’s template to the new recommended style. First of all, I should say you probably don’t need to do this. But I like to keep as close to the official versions as possible so that they are better maintained. If that’s you too, then read on.

Word of caution before going ahead: This article is about upgrading an existing site’s composer.json to use the new recommended packages IF you are already using webflo’s template or a close enough variant (such as my own fork or something generated with drupal-composer-init). A quick way to check this would be to see if you have the drupal/core project listed in your composer.json. If yes, then the steps below would most likely work for you. If you see drupal/drupal instead, this won’t work for you. There are some attempts to automate the upgrade but I’d prefer restructuring your site from scratch.

Let’s start with the upgrade

Before your begin, make sure your git repository is clean, so that you can easily revert. Taking a backup of your project won’t hurt either.

Second, the process would be a lot more smoother if you are on Drupal 8.7 required. If not, it would be a good idea to first upgrade to Drupal 8.7 and then follow these steps (but not required).

First, we need to remove the deprecated drupal-scaffold. Run composer remove drupal-composer/drupal-scaffold. Make sure the package is actually removed. There may be other packages that depend on this (for example, hussainweb/drupal-composer-helper).

Also, you may have to remove scaffold related commands in your composer.json. See Greg Knaddison’s comment below.

You may also have webflo/drupal-core-require-dev in your require-dev section. If you do, run composer remove --dev webflo/drupal-core-require-dev.

Let’s prepare our composer.json for the new scaffold plugin. Make sure you have the following block in the extra section of your composer.json.

"drupal-scaffold": {
    "locations": {
        "web-root": "web/"
    }
}

If you already have the drupal-scaffold entry, just add the locations entry under it making sure you set the correct location for your web-root.

Do the upgrade

Run composer require drupal/core-recommended:^8.8 drupal/core:^8.8 drupal/core-composer-scaffold:^8.8 --update-with-dependencies

This command does the entire upgrade. If you get errors here, resolve them before you move on. Composer errors are a science unto themselves, so it may be difficult to deal with all possible ones here. Some of the common errors you might see might be about patches failing to apply in which case you will need updated patches (or they may already be merged in 8.8). If you see memory errors, try raising the composer maximum_limit using the COMPOSER_MEMORY_LIMIT environment variable. Sometimes, packages like zaporylie/composer-drupal-optimizations would help here.

In the command above, we are also marking drupal/core for the upgrade to 8.8. This is required as composer may not be able to resolve the dependency tree otherwise. Once the above command is successful, we don’t need that package anymore, so let’s remove it with composer remove drupal/core.

If you are still running into errors, look at the composer.json in the drupal/core-recommended repository and figure out how is your composer.json different from that. Sometimes, it might be a really tiny non-obvious setting that might be causing a problem.

Working with changes

That concludes the upgrade. Check your git directory to see what else has changed. You might notice changes in files like .htaccess and others which is normal in a Drupal upgrade. Commit or ignore these files as per your needs.

In my case, I updated my settings.php to match the new default.settings.php. Particularly, I updated my directives for config sync directory and temporary files directory. I try to keep settings.php at minimum diff from default.settings.php. That’s not important, and also not relevant to this blog post. This is something you might be doing with any Drupal core upgrade.