Tips for upgrading Drupal 8 to Drupal 9!

Table of contents

This article is a step-by-step guide to upgrading Drupal 8 to 9. Through this tutorial find some tricks and tips that could help you apply the proceeding with updating.

As we know, Drupal 8 is dependent on Symfony 3, and Symfony 3’s end of life was November 2021. Consequently, Drupal 8 support ended on November 2, 2021. But the Drupal community worked hard to launch in June 2021 Drupal 8.9. That version makes easier the upgrading process to D9.

Make backups and meet system requirements

Before we share our Drupal 9 porting experience, it is important to understand our website’s current stack and create backups.

  • [x] Create DB and Site backups.

  • [x] Meet technical system requirements

  • [x] Verify if you get the D8 latest version, otherwise update your D8 que D8 tenga la última actualización disponible instalada.

Step by step for upgrading

After checking all the previous points we can start with the upgrade:

  1. Install the ✨ Status Upgrade ✨ module

composer require drupal/upgrade_status

  1. Install the ✨ Upgrade Rector ✨ module

composer require drupal/upgrade_rector

Tip 1: Create a guiding document or report to register all process information.

  1. Review the report generated for the Status upgrade module. This module helps identify deprecation in contributed/custom modules and themes and suggested an update to the available version, validates the system requirements, and much more. Go to this path: /admin/reports/upgrade-status

Upgrade status

Tip 2: Go to this URL and check the latest version of a module is compatible with Drupal 9.

  1. Add to the report all contributed modules that require an update.

Tip 3: At this point, we should have created the report that we mention in Tip 1, we will start adding information to help us with the updating process.

  1. Add all modules (contributed and customized) disabled on the site but required an update.

Tip 4: The unused modules should be uninstalled and removed from the project but we have to keep in mind if we are working in multisite we have to make sure to remove just modules that we’ll not need on any site, otherwise they have to update those.

  1. Install required modules from the Status upgrade. The required modules are complementary to running the updating.

composer require drupal/composer_deploy

composer require mglaman/drupal-check --dev

  1. We have three ways to generate the Upgrade rector report, follow one of these instructions:

  2. Select all modules in the Status upgrade report and go to the end of the page to click on the button Scan selected. This action shows you a column with the issues or changes that you have to do.

  3. Go to this path: /admin/reports/upgrade-rector. Choose the module that you need to review and click on the button to review. (Sometimes this option breaks the site or shows you an error message.)

  4. Run the next command in your terminal, this option shows all the issues on the site.

drupal-check -ad project/modules

  1. Add the results of point 7 to the general report. It will help you to don’t forget details.

Tip 5: Always start with fixes in the top general section of the Status upgrade. Update versions of PHP, Drush, Mysql, etc.

  1. Update modules and themes contributed.

Tip 6: Check if you have a special requirement to upgrade your theme. Sometimes we have to do extra steps for specific themes like Acquia site studio.

  1. Update our custom modules follow the Upgrade rector instructions.

Tip 6: Install PHPCS tool in our editor with this command: composer global require squizlabs/php_codesniffer.

  1. Check and validate our files with PHPCS tool.

  2. Temporarily add write access to protected files and directories:

chmod 777 web/sites/default

chmod 666 web/sites/default/*settings.php

chmod 666 web/sites/default/*services.yml

  1. Next, you’ll need to pull Drupal 9 packages and dependencies.:

Tip 7: Write –no-update at the final of the command to avoid a chicken-and-egg problem with mutual dependencies

composer require  'drupal/core-recommended:^9'  'drupal/core-composer-scaffold:^9'  'drupal/core-project-message:^9' --update-with-dependencies --no-update

  1. If you have drupal/core-dev installed, run the next command:

composer require  'drupal/core-dev:^9' --dev --update-with-dependencies --no-update

  1. Now, actually perform the update to the code itself:

composer update

Tip 8: If we get a module error, please review the Tip 2 and apply the fix or patch.

  1. Run any pending database updates, required if you update module code and that module needs to update the database. We have two ways to do it:

  2. Desde el navegador con el path /update.php

  3. Por consola con el comando Drush:

drush updatedb

  1. When complete, restore read-only access to the sites/default directory:

chmod 755 web/sites/default

chmod 644 web/sites/default/*settings.php

chmod 644 web/sites/default/*services.yml

  1. Verify if our site has a ✨ D9✨ version installed, /admin/reports/status.

You probably won’t need to do all of these steps, and some of them may not be exactly right for your use case, every upgrade is different but we’ll do our best to explain the most common cases so hopefully, you can get it all working.

Tip 9: Don’t forget we have a great and enthusiastic Drupal community that loves sharing their learnings. Ask them and enjoy the process.