Upgrading Drupal 8 to Drupal 9: Observations.

Posted on 24 May 2021 by Alexei Raiu
Upgrading Drupal 8 to Drupal 9: Observations.

Drupal 8 is supported until November 2, 2021. All Drupal 8 sites need to be upgraded to Drupal 9 by then. Drawing from the lessons of hard and painful migration from Drupal 7 to Drupal 8, Drupal devs have decided to make the transition from 8 to 9 as smooth as possible. Reading tweets and blog posts it may seem "it's just the matter of running update.php". Is it though? Here are some things you may want to know.

1. Incompatible Modules.

Drupal 8 had a lot of API calls that were marked as deprecated and then removed ini Drupal 9. Technically, this does constitute an API break, which Drupal had promised not to do any time soon after it's break between versions 7 and 8. But it did.

Even with rigorous maintenance, your Drupal 8 site is likely to have contrib and custom code incompatible with Drupal 9. In the custom code, these are usually deprecated API calls, as well as legacy constructs which were frequently employed by the developers in their transition from Drupal 7. In the contrib code, problems come from the neglected and abandoned modules. In the early stages of transition from Drupal 7, there were many new Drupal 8 modules that filled this or that niche, and were later abandoned, either because of a competing module, or because their module did not become very popular and the developers lost interest in supporting it. If your Drupal site was created before Drupal 8.7, you are likely to have all kinds of deprecated and abandoned code that will break your site when you try to convert to Drupal 9.

What should you do? Install the Upgrade Status module and scan your modules for incompatibilities. Likely, you will need to uninstall some abandoned modules and install newer alternatives instead.

2. File to Media Conversion.

In Drupal 8.7, the Media module was introduced into the core. Media is a wrapper around the file, which allows reusing images and documents, as well as adding additional fields to them. However celebrated, Media remained unusable for about a year after it was first introduced, due to the delayed development of the Media Library module. Many earlier Drupal 8 sites are not using the Media correctly, or are using file_entity module instead.

What should you do? If you are not using the Media module correctly, you will need to migrate your images into media and re-architecture your fields, the custom code, and the theming layer to work with Media correctly. Expect dozens of hours spent on the conversion. The module that will facilitate the conversion is Migrate File to Media. When I say "dozens of hours", I mean if you use this module.

3. Panelizer to Layout Builder.

Panelizer, Panels, Page Manager was a widely used set of tools in Drupal 7. There was a whole distribution built around this paradigm, called Panopoly. At some point, in Drupal 8, it seemed that this approach would become standard and go into core. But over time, it's popularity decreased. There was, however, a product of this initiative, called Layout Builder, that did go into the core. It allows creating layouts with the node's fields and adding custom blocks to it, which has prompted some of the companies to switch their editorial experience into composing their pages of reference fields of custom blocks of different types, laid out with the layout builder.

What should you do? If you are using the suite of Panels, Panelizer, and Page Manager, you will need to migrate to Layout Builder to use that kind of layout in Drupal 9.

4. Paragraphs to Layout Builder + Blocks.

If you have read the above point #3, you already know that the Layout Builder has been introduced as the way to lay out content in Drupal 9. While there are other ways to do it (Paragraphs are still possible to use), the "official" method in Drupal 9 is Layout Builder + Blocks. Paragraphs are incompatible with the Layout Builder without an additional layer in between them, like the paragraphs_blocks module.

What should you do? If you want to use the Layout Builder + Blocks, you will need to add the custom block types, and then rebuild the pages. In many cases, it will be much cheaper to not switch to this official approach, especially if you are already using paragraphs. If you are already using some other layout, like paragraphs or panels, your upgrade to Drupal 9 can be very hard, unless you agree to forfeit the benefits of the Layout Builder tool.

5. Composer 2.

Composer 2 is much faster and less memory-hungry than its predecessor. However, chances are that your Drupal 8's composer.json file is incompatible with Composer 2.

What should you do? See the list of incompatible Composer plugins and how to replace them. See the help on migrating to Composer 2.


So... Unless you have been using the "naked" out-of-the-box Drupal 8 and started your site with Drupal 8.8 or higher, it is unlikely that upgrade to Drupal 9 will be as easy as "just running update.php". On the contrary, if your site is complex, has lots of contrib and custom modules, and was started before Drupal 8.8, then it is likely that you are in for a hard upgrade. You will likely need to migrate file to Media. If you are already using paragraphs for page layout, you may want to continue using them if you don't want to migrate all paragraphs to custom blocks - an architectural rebuild that is a project all by itself.