Due to the quick change of pace in Drupal, documentation can sometimes struggle to keep up. Here’s an abbreviated method for updating an older install of Drupal 8.x that uses drupal-composer/drupal-project (a common framework) to drupal/recommended-project, for use with 8.8+ and 9.0+ projects. I've successfully run this on a few of mine.
Note: there are two paths you can follow: drupal/legacy-project and drupal/recommended-project. The former installs your site in the root project folder where your composer.json resides. This can create potential security issues, so it would be best to use the latter (drupal/recommended-project), where the vendor directory is outside of the install root folder. For the sake of this demo, it’s assumed your install root is named web, and that your site is already Composer-managed.
First, if you aren’t already doing so, having your project under version control (such as Git) is an easy way to roll back changes if something doesn’t work. In addition, it’s recommended to have reliable backups of your site code and database(s), in case of major issues. Also, if your .gitignore and .htaccess files have modifications, it would be advisable to back them up, as well.
Prerequisites:
- PHP 7.3+
- A current version of Composer
- Drush 9 (10 is recommended, and necessary for Drupal 9).
- Ensure any contributed or custom modules code are compatible with Drupal 8.8+ You may need to set a specific version for some using
composer require, or manually.
Then, in your settings.php file
(usually located at web/sites/default/):
Change this:
$config_directories['sync'] = 'my/config/dir';
To this:
$settings['config_sync_directory'] = 'my/config/dir';
You may have to temporarily change permissions on this file to 777 in order to make changes. If you have to do this, change the permissions back to 755 after updating.
Special note: If you are updating from an older version of Pathauto (pre 8.x-1.6), it would be advisable to run drush updb now, in order to apply the configuration directory changes that are required in Drupal 8.8+.
Then:
rm -rf vendor
This removes older projects, that may cause issues with the update. Alternately, you can manually delete the contents of this folder.
Then:
rm composer.lock
My experience in updating projects had a number of conflicts that were resolved doing this.
Then, in composer.json:
If it contains this, remove it:
"drupal-scaffold": {
"initial": {
".editorconfig": "../.editorconfig",
".gitattributes": "../.gitattributes"
}
}
And, the same with this:
"autoload": {
"classmap": [
"scripts/composer/ScriptHandler.php"
],
"files": ["load.environment.php"]
},
And this:
"scripts": {
"pre-install-cmd": [
"DrupalProject\\composer\\ScriptHandler::checkComposerVersion"
],
"pre-update-cmd": [
"DrupalProject\\composer\\ScriptHandler::checkComposerVersion"
],
"post-install-cmd": [
"DrupalProject\\composer\\ScriptHandler::createRequiredFiles"
],
"post-update-cmd": [
"DrupalProject\\composer\\ScriptHandler::createRequiredFiles"
]
},
And, add this under extra:
"drupal-scaffold": {
"locations": {
"web-root": "web/"
}
},
Change the name: (usually line 2) to:
"name": "drupal/recommended-project",
Then, under require, change this:
"drupal-composer/drupal-scaffold": "^2.5",
To this (or add if not there):
"drupal/core-composer-scaffold": "^8.8",
This (your version may be different):
"drupal/core": "^8.6.0",
To this:
"drupal/core-recommended": "^8.8",
N.B: This will update your project to the latest stable version of core 8.x (8.9.0) at time of writing. If you require a specific version of 8.8, edit this line to reflect that.
If this isn’t there, add it:
"drush/drush": "^9.0.0",
This is because this structure no longer includes Drush automatically, and your build will fail without it.
Then run:
composer clearcache
composer install
If this has run successfully, then run:
drush updb
drush cr
Carefully check your site status, advisably first at admin/reports/status, then admin/reports/dblog, as well as carefully testing your site operation for anomalies. This would also be a good time to check for legacy files in your project root, such as scripts/Composer/ScriptHandler.php, which won’t be needed any more.
Depending upon your team needs, it may also be good to update your project’s readme.