Welcome! If you need to update your Drupal 8 site to the latest feature branch, this post is for you.
Drupal 8.8.0 introduced many exciting changes. On the heels of this release, we also saw a security release for Drupal 8.8.1, which covers four distinct security advisories (SAs). Drupal 8.7.11 also has fixes for those SAs, but developers might consider this a golden opportunity to take care of both updates at once.
This post will cover four common pitfalls of upgrading to the 8.8.x branch:
- Pathauto version conflicts
- New sync directory syntax
- Temporary file path settings
- Composer developer tools
Prerequisites
These instructions assume you are:
- Maintaining a Drupal 8 site on version 8.7.x
- Using Composer to manage dependencies
- Comfortable using the command line tool Drush
Pathauto version conflicts
The Pathauto module has been around for a long time. With over 7 million downloads and 675K reported sites using Pathauto, chances are high that this section applies to you.
Drupal core 8.8.0 introduced the path_alias module into core. However, this module conflicts with the Pathauto contrib module at version 8.x-1.5 or below. If you have Pathauto installed on your site, you must first update to Pathauto 8.5-1.6 or later.
I strongly suggest updating Pathauto as a first step, and deploying all the way to production. The order of operations is important here, because updating Pathauto after core will result in data loss. While the release notes say it is safe to update “before or at the same time” as core, it is good to have some extra precaution around the sequence of events.
Visit the full change record for more details: Drupal 8.8.0 requires pathauto version 8.x-1.6 or higher if installed.
Diagnosing path alias issues
What if I neglect to update Pathauto? How can I identify the symptoms of this problem? After running drush updb, I would expect to see this SQL error:
[error] SQLSTATE[23000]: Integrity constraint violation: 1062 Duplicate entry '7142' for key 'PRIMARY': INSERT INTO {path_alias}
...
This Drupal core bug report provides more detail. It also describes how to walk it back to a working state if you encounter this problem.
New sync directory syntax
The configuration management system introduced a new sync directory syntax for 8.8.0. The default location for Drupal’s config sync is sites/default/files/config_[HASH]. It is very common practice to customize this location. It makes config files easier to understand and manage. If you do customize this location, note that Drupal no longer uses the $config_directories variable.
Here is what a custom config sync directory might have looked like in Drupal 8.7.x or lower. In your settings.php file:
$config_directories['sync'] = dirname(DRUPAL_ROOT) . '/config';
Now in Drupal 8.8.x, this setting should be updated to look like this:
$settings['config_sync_directory'] = dirname(DRUPAL_ROOT) . '/config';
Read the full change record for more technical details: The sync directory is defined in $settings and not $config_directories.
Diagnosing sync directory issues
You can tell right away if there is a problem with your sync directory if config files are showing up in an unexpected place. You can also use drush to discover the current value of your config sync directory.
Interactive:
$ drush php
>>> Drupal\Core\Site\Settings::get('config_sync_directory')
=> "/var/www/html/foo/bar"
Non-interactive:
drush php-eval '$path = Drupal\Core\Site\Settings::get("config_sync_directory"); print $path;'
Here are a few more ways to retrieve the same information, using the drush status command.
For Drush 8 only:
drush status config_sync
For Drush 9 or 10:
drush status --fields=%paths
Temporary file path settings
In this new feature release, the old procedural function file_directory_temp() is deprecated. Drupal now uses the FileSystem service instead, and this has implications if you are setting a custom value for temporary file storage.
To customize the temporary file location the old way, you may have something like this in your settings.php file:
$config['system.file']['path']['temporary'] = '/tmp';
Change this setting to the new syntax before running database updates:
$settings['file_temp_path'] = '/tmp';
Read the full change record to learn more: file_directory_temp() is deprecated and moved to the FileSystem service.
Diagnosing temp directory issues
Take a look at your database logs. In Drupal’s logs at /admin/reports/dblog, you can filter on “file system”. Any errors about temporary file placement may indicate an issue.
Composer developer tools
Composer Support in Core is just one of many strategic initiatives in the Drupal community. Some early ways of using Composer are now deprecated in favor of this new support. For example, Drupal now has an official Composer template project. If you used the unofficial template (but recommended at the time) drupal-composer/drupal-project to install Drupal before, you will have a bit of updating to do.
Manually edit composer.json to remove deprecated packages. Remove this line:
"require-dev": {
"webflo/drupal-core-require-dev": "^8.7.0"
},
And replace it with this one:
"require-dev": {
"drupal/core-dev": "^8.8"
},
Then edit the require statement for Drupal core itself:
"require": {
...
"drupal/core": "^8.8"
...
},
Now that composer.json is up to date, you can go ahead and run Composer updates in the usual way, with composer update --lock.
If you are starting a new Drupal 8 site from scratch, refer to this guide on Starting a Site Using Drupal Composer Project Templates. It has instructions on how to use the new recommended way of handling Composer templates, using drupal/recommended-project.
Diagnosing deprecated Composer tools
Without following the steps above, if you try to run composer update, Composer will fail with this error:
Your requirements could not be resolved to an installable set of packages.
Depending on what package versions are installed, and the syntax of your composer.json file, the rest of the error output will vary. Here is an example:
...
The requested package webflo/drupal-core-require-dev (locked at 8.7.11, required as ^8.8) is satisfiable by webflo/drupal-core-require-dev[8.7.11] but these conflict with your requirements or minimum-stability.
...
The important thing to know here is that Composer is being helpful. It is preventing you from upgrading a deprecated package.
You can verify this by using the Composer prohibits command:
$ composer prohibits drupal/core:^8.8
webflo/drupal-core-require-dev 8.7.11 requires drupal/core (8.7.11)
drupal/core 8.8.0 requires typo3/phar-stream-wrapper (^3.1.3)
drupal-composer/drupal-project dev-my-project does not require typo3/phar-stream-wrapper (but v2.1.4 is installed)
Or its alias:
$ composer why-not drupal/core:^8.8
But wait! There’s more!
These are just a few pitfalls. There are other considerations to make before updating to 8.8.x. Make sure to read the release notes carefully to see if any other advisories apply to you.