Guide to the Drupal 8.8 Update
Updating to Drupal 8.8 is the first step in preparing your site for Drupal 9.
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
- Contrib module conflicts: If your site is using the contrib modules Pathauto, Workspace, or Coder, update those first.
- Update settings.php: Change the temp and config sync directory variables settings.php
- Update composer.json: Manually update your
- Run the Drupal database updates
- Export changed config
Contrib module conflicts
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!
- 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
- Deploy the updated code
- Run the database updates:
- Begin your Drupal 8.8 update
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).
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
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.
- Check your coder version:
composer show drupal/coder
- 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
- Update the package:
composer require drupal/coder:^8.3.2
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
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.
settings.php files for the
$config_directories = ;
$config_directories[CONFIG_SYNC_DIRECTORY] = '../config/sites/default';
Replace this (using your original path) with:
$settings['config_sync_directory'] = '../config/sites/default';
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.
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'];
- 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.
Drupal 8.8 introduced scaffolding in core and separated dev dependencies into a separate package. The scaffolding manages core files like
.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 and to the
require section, add:
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
Double check the
web-root location and change
web/ if necessary -- for example, if you're hosting on Acquia, set this to
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.
Add the new
drupal/core-recommended package to your Composer requirements
This will install your core Drupal requirements.
composer.json and in the
require section, replace the
drupal/core package with:
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.
composer.json and to the dev section, add:
This should replace the
webflo/drupal-core-require-dev package, if you were using it.
- Using Drupal Composer project templates
- Compare your
composer.jsonto the recommended template
- ... or to the legacy template, if your
composer.jsonlives 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
After making these changes to your
composer.json, you may see the following error when you run
composer install or
Installation failed, reverting ./composer.json to its original content.
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:
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.
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!