Guide to the Drupal 8.8 Update

If you're currently running a Drupal 8 site and are interested in upgrading to Drupal 9 when it is released in the summer of 2020, the first step is to update to the recently-released Drupal 8.8. Drupal 8.8 contains both the deprecated APIs and the new APIs that will become standard in Drupal 9, so once your site is on 8.8, you can begin to review your contrib modules and update your custom code to move from deprecated APIs to the state of the art. No new features will be added in the 9.0 release, which means that 8.8 has feature parity to streamline the upgrade path between 8.x and 9.x.

The update to 8.8 is more involved than previous Drupal 8 point releases because 8.8 renames some configuration variables and changes the core drupal packages and dependency structure in composer.json, which means that updates need to be made to both settings.php and composer.json.

At Palantir, our team maintains many Drupal 8 sites in both active development and support, and we've documented some important tips that are important to keep in mind when updating your site to 8.8. We also want to give a shout-out to the folks at PreviousNext for their post on what they learned when updating to the 8.8 beta release.

Update process overview

1. Contrib module conflicts: If your site is using the contrib modules Pathauto, Workspace, or Coder, update those first.
2. Update settings.php: Change the temp and config sync directory variables settings.php
3. Update composer.json: Manually update your composer.json
4. Run the Drupal database updates
5. Export changed config

Contrib module conflicts

Pathauto

We use the Pathauto module on all of the sites we build, and Pathauto needs some handholding in this update process. If you don't update Pathauto while you're still on Drupal core 8.7, you could lose your path alias data!

1. While your site is still running Drupal 8.7, update Pathauto to the latest release (8.x-1.6):

   composer require drupal/pathauto:^1.6

2. Deploy the updated code

3. Run the database updates:

   drush updatedb

4. Begin your Drupal 8.8 update

Workspace

Workspace isn't common on our sites, so running into an issue with it usually means doing some research. The contrib Workspace module has been moved into core, and renamed "Workspaces"; installing both modules on the same site creates code-level conflicts. Additionally, the Drupal 8.8 release introduces an incompatibility between core Content Moderation module and the contrib Workspace module.

As of December 2019, there is no ready-made upgrade path from the contrib module to the core module; the recommendation is to uninstall the contrib module -- which will delete all workspace content that is not yet live -- and then install core's module (documentation).

• Check this bug report on the contrib Workspace module
• For now, if you're using the contrib Workspace module and the core Content Moderation module, you will not be able to update to Drupal 8.8

Coder

If you're using Coder to do automated code review against the Drupal coding standards, you may need to update. Drupal 8.8 requires a minimum of version 8.3.2.

1. Check your coder version:

   composer show drupal/coder

2. You'll see the package information with the version -- in this case, 8.2.10:

   [ 3:15P ~/repos/example] (develop) $ composer show drupal/coder
   name     : drupal/coder
   descrip. : Coder is a library to review Drupal code.
   keywords : code review, phpcs, standards
   versions : * 8.2.10
   type     : library
   ...

3. Update the package:

   composer require drupal/coder:^8.3.2

Updating settings.php

First, find your settings.php file; this will be within your Drupal site at sites/default/settings.php, or may be an include file named like sites/default/settings.*.php.

Config sync directory

The config sync directory is where Drupal stores your exported configuration YAML files. Before Drupal 8.8, you could configure multiple directories for exporting config; now there's only one, and the variable name has changed.

Check settings.php files for the $config_directories variable:

$config_directories = [];
$config_directories[CONFIG_SYNC_DIRECTORY] = '../config/sites/default';

Replace this (using your original path) with:

$settings['config_sync_directory'] = '../config/sites/default';

More information

• The sync directory is defined in $settings and not $config_directories

Temporary (temp) directory

The temp directory is usually specific to your host or the environment where your Drupal site is running, so you may need to set this differently for production vs. local development.

Check your settings.php files for the temp directory configuration:

$config['system.file']['path']['temporary'] = $_ENV['TEMP'];

Replace this (using your environment-specific path) with:

$settings['file_temp_path'] = $_ENV['TEMP'];

More information

• On Acquia hosting, the temp directory path can be found in the environment variable $_ENV['TEMP'], as shown in the snippets above.
• On Pantheon hosting, the host-specific temp directory is set in their drops-8 distribution.

Update composer.json

Drupal 8.8 introduced scaffolding in core and separated dev dependencies into a separate package. The scaffolding manages core files like index.php and .htaccess, which are required for Drupal to run but don't live within the core/ directory. You might already be using drupal-composer/drupal-scaffold for this purpose, which will need to be replaced.

Because these changes involve replacing existing packages and updating composer plugin configuration, they need to be manually applied to your composer.json.

Use the drupal/core-composer-scaffold package

Edit your composer.json and to the require section, add:

        "drupal/core-composer-scaffold": "^8.8",

This should replace the drupal-composer/drupal-scaffold package, if you were using it.

This is a composer plugin, and needs to be configured in the extra section of your composer.json. Add or update the drupal-scaffold configuration:

        "drupal-scaffold": {
            "locations": {
                "web-root": "web/"
            },
            "allowed-packages": [
                "drupal/core"
            ],
            "file-mapping": {
                "[web-root]/.htaccess": {
                    "mode": "replace",
                    "path": "web/core/assets/scaffold/files/htaccess",
                    "overwrite": false
                }
            }
        },

Double check the web-root location and change web/ if necessary -- for example, if you're hosting on Acquia, set this to docroot/.

Also check the file-mapping section and make sure the value for path is correct. This file-mapping configuration will prevent your .htaccess file from being overwritten if you've customized it, but can be left out otherwise.

More information

• Using Drupal's Composer Scaffold

Add the new drupal/core-recommended package to your Composer requirements

This will install your core Drupal requirements.

Edit your composer.json and in the require section, replace the drupal/core package with:

        "drupal/core-recommended": "^8.8",

Add the new drupal/core-dev package to your Composer dev requirements

This will install optional, development-specific core dependencies so that you can run things like automated testing.

Edit your composer.json and to the dev section, add:

        "drupal/core-dev": "^8.8",

This should replace the webflo/drupal-core-require-dev package, if you were using it.

More information

• Using Drupal Composer project templates
• Compare your composer.json to the recommended template
• ... or to the legacy template, if your composer.json lives inside your Drupal root

Finally, run Composer

Now that you've updated your composer.json file, run Composer to update your packages. In order to update only the packages you've changed (and not every package all at once), run:

composer update --lock

Troubleshooting Composer

After making these changes to your composer.json, you may see the following error when you run composer install or composer update:

Installation failed, reverting ./composer.json to its original content.
 [RuntimeException]
 Could not delete /srv/users/serverpilot/apps/sandbox/drupal/web/sites/default/default.services.yml:

This happens because the scaffolder (which runs on composer install and update) is trying to write files to your sites/default/ directory, but doesn't have the permissions. You can resolve this with:

chmod +w web/sites/default

See Troubleshooting: Permission issues prevent running Composer for more details.

Running the update scripts

Finally, you'll need to do the normal Drupal update process: run the database exports, and export any config changes:

drush updatedb
drush config:export

Troubleshooting the database updates

If you're testing the database updates multiple times on the same environment, you may run into this error:

[error] Update failed: system_update_8804

This happens because system_update_8804 creates new database tables. If you are using drush sql-sync to test and re-test the update against a copy of the production database, you'll need to clear your local database with drush sql-drop first, in order to delete tables created by a previous run.

What next?

Once your site has been updated to Drupal 8.8, you'll be in good shape for the upgrade to Drupal 9, which is currently anticipated on or around June 3, 2020. Between now and then, we'll be working alongside other Drupal contributors to make sure that key contributed modules are ready for Drupal 9, as well helping our clients make sure that custom code and modules on their sites are free of deprecated APIs. Stay tuned for more!