Getting Ready For The Upgrade To Drupal 9

Drupal 9 will be released on June 3rd, 2020 so with this just around the corner I thought I'd put together a post about how to check if your site is ready.

The transition from Drupal 7 to Drupal 8 was more of an upheaval than an upgrade. Updating a Drupal 7 site to Drupal 8 requires a lot of effort involving code changes and migration steps. Drupal 7 modules are not compatible with Drupal 8 and so any custom code written needs to be adapted to the new structure. The difficulty of this change made the Drupal community take notice and think about how future versions of Drupal are introduced.

During the lifecycle of Drupal 8 features have been added to the system, and some underlying changes have been made to improve the architecture of the system. During this process it has been very important to not break backwards compatibility so that a module for Drupal 8 will continue to work with the latest version. When code has been marked for removal it has been flagged as deprecated and left in the Drupal 8 codebase.

Drupal 8 was built on Symfony components version 3, and those components will be unsupported November 2021. It is not possible to update the Symfony components without breaking backwards compatibility so this will need to be done in Drupal 9. There are also a number of other third party dependencies within Drupal that can't be upgraded without incident, which includes the JQuery dependency.

Drupal 9 has always been on the horizon and has been thought about as Drupal 8 has progressed through its lifecycle. The aim of the community has been to make the progression to Drupal 9 as painless as possible. As a result, the plan to move to Drupal 9 will be to remove the deprecated code, update the Symfony components and third party libraries before tagging the Drupal 9.0.0 release. In essence, the last release of Drupal 8 (8.8.0) is very close to Drupal 9, and so the transition to Drupal 9 shouldn't require a great deal of effort.

In the run up to the release there has been a large amount of work done by the community to prepare the contributed module space for Drupal 9. This has resulted in initiatives such as automated issue creation to flag Drupal 9 incompatibilities, automated code fixes where simple things can be fixed easily in an automated fashion, and community driven events to update Drupal modules. This means that the problem up upgrading to Drupal 9 and waiting for the contributed space to catch up shouldn't be so prevalent this time around.

Tools

Whilst the contributed space is getting ready, you should start looking at your site to ensure that your own codebase is ready for Drupal 9. The following tools will help you spot any problems with your site so that you can work to rectify them.

Your IDE

Whilst doing development on your site you should have an IDE that is capable of showing deprecated code. As I mentioned above the Drupal 8 codebase now contains a collection of deprecated code, in which case your IDE should be shouting about this whilst you are looking at the code.

As an example I found the following deprecated code in a recent project I was working with. The editor I was using here is PHPStorm, which marks deprecations with a strikethrough.

Drupal 8 deprecated code

Following this took me to a class where all of the deprecations were clearly marked.

<?php

namespace Drupal\Core\Entity;

use Drupal\Core\Field\FieldDefinitionListenerInterface;
use Drupal\Core\Field\FieldStorageDefinitionListenerInterface;

/**
 * Provides an interface for entity type managers.
 *
 * @deprecated in drupal:8.0.0 and is removed from drupal:9.0.0.
 *
 * @see https://www.drupal.org/node/2549139
 */
interface EntityManagerInterface extends EntityTypeListenerInterface, EntityBundleListenerInterface, FieldStorageDefinitionListenerInterface, FieldDefinitionListenerInterface, EntityTypeManagerInterface, EntityTypeRepositoryInterface, EntityTypeBundleInfoInterface, EntityDisplayRepositoryInterface, EntityFieldManagerInterface, EntityRepositoryInterface {

  /**
   * @deprecated in drupal:8.0.0 and is removed from drupal:9.0.0. Use
   *   \Drupal\Core\Entity\EntityLastInstalledSchemaRepositoryInterface::getLastInstalledDefinition()
   *   instead.
   *
   * @see https://www.drupal.org/node/2549139
   */
  public function getLastInstalledDefinition($entity_type_id);

  /**
   * @deprecated in drupal:8.0.0 and is removed from drupal:9.0.0. Use
   *   \Drupal\Core\Entity\EntityLastInstalledSchemaRepositoryInterface::getLastInstalledFieldStorageDefinitions()
   *   instead.
   *
   * @see https://www.drupal.org/node/2549139
   */
  public function getLastInstalledFieldStorageDefinitions($entity_type_id);

}

To fix this I will need to do a little bit of refactoring, but it will largely consist of replacing the type of object that is passed to this class.

A good example of deprecated code is the old drupal_set_message() function, which was replaced with a messenger service in Drupal 8.5.0. Looking at the documentation above this function shows what to use instead.

/**
 * @deprecated in drupal:8.5.0 and is removed from drupal:9.0.0.
 *   Use \Drupal\Core\Messenger\MessengerInterface::addMessage() instead.
*/
function drupal_set_message($message = NULL, $type = 'status', $repeat = FALSE) {

drupal-check

The drupal-check tool was created by Matt Glaman as a way of scanning code to look for deprecations and produce a report. The tool is best installed via composer either as part of the project or globally.

composer require mglaman/drupal-check --dev

It doesn't rely on bootstrapping Drupal so it can be used outside of the project you want to inspect. Once installed you can run the tool by just calling, usually with an argument of the directory you want to analyse.

./vendor/bin/drupal-check docroot/modules/custom

I ran this over the same site that I found the previous deprecation in and this produced a report for me.

$ ./vendor/bin/drupal-check docroot/modules/custom
 37/37 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%

 ------ ----------------------------------------------------------------------------------------------------------------------------------------------
  Line   my_module/src/Plugin/Field/FieldFormatter/ExampleCommentFormatter.php
 ------ ----------------------------------------------------------------------------------------------------------------------------------------------
  90     Parameter $entity_manager of method Drupal\my_module\Plugin\Field\FieldFormatter\ExampleCommentFormatter::__construct() has
         typehint with deprecated interface Drupal\Core\Entity\EntityManagerInterface:
         in drupal:8.0.0 and is removed from drupal:9.0.0.
 ------ ----------------------------------------------------------------------------------------------------------------------------------------------


 [ERROR] Found 1 error

There is plenty more documentation on the git repo for the drupal-check tool, so please check that out if you want to install and run it.

Upgrade Status

Upgrade Status is a module that wraps the drupal-check tool in an easy to use module within your Drupal site. After installing the module and going to the path /admin/reports/upgrade-status you should see the main screen for this module. From here you can run a report on every module and see if there are deprecated modules that need to be addressed.

The following is a simple check from a sample project I was working on.

Upgrade status

I include the above screenshot as it shows that there is a little bit of work to be done, although most of the above issues were corrected by me just updating the modules.

Outside of updates I have been looking at a couple of contributed projects to get them up to speed with Drupal 9. Most of the changes haven't been too hard and have mostly involved adding in the correct string to the info file or swapping out hard coded dependencies with alternative services.

Get Involved!

Whilst many Drupal modules are ready for Drupal 9, there is still a lot of work to do, so if you want to get involved in a structured way then you'll be pleased to know that this weekend there is a Drupal 9 Porting Weekend. Last time 89 different modules were made ready for Drupal 9, so if you are looking to help out a module you rely on then get involved in the effort. There will be community volunteers available all day to help you out with Drupal 9 readiness questions.

Add new comment

The content of this field is kept private and will not be shown publicly.
CAPTCHA
1 + 4 =
Solve this simple math problem and enter the result. E.g. for 1+3, enter 4.
This question is for testing whether or not you are a human visitor and to prevent automated spam submissions.