Our Guide to Upgrading Your Site with Drupal 9

It’s been ten years since the release of Drupal 7. In that time, building experiences for the web and digital marketing needs have grown more complex. The Drupal platform has had to evolve to keep pace with market trends and other content management solutions. This concept of an evolving platform aligns perfectly with "Embrace Change," which is Principle 7 from Drupal’s Values and Principles. There’s a long shared saying in the community stating that, "The drop is always moving." Drupal (the drop) needs to grow to remain competitive and developers need to embrace these changes to take advantage of the latest features and functionality.

When it comes to embracing the latest Drupal offerings, as a community we still have a lot of work to do. Of the over 950K sites reported on the Drupal Usage Statics page for November 21, 2021, roughly 520K of those websites are running some version of Drupal 7. Drupal 8 support ended November 2, 2021, and after an extension due to COVID, Drupal 7 support will end in November of 2023. This means for organizations running any version less than Drupal 9, now is the time to be planning the next steps.

Why Migrate to Drupal 9?

Before jumping into the process of planning and executing a migration, it’s important to understand the value of this effort to your business. This is the perfect time for an organization to evaluate if it makes sense to continue investing in Drupal and understand what they’ll receive from their investment. There are a number of compelling reasons to invest in moving to Drupal 9, but here are some highlights!

Drupal Is API-First

The API-First initiative, introduced in Drupal 8, simplified using REST APIs to pull content out of Drupal and into other systems. This means fully decoupling or progressively decoupling is easier in modern Drupal. Additionally, as composable architectures grow in popularity, Drupal enables developers to quickly surface REST endpoints as JSON in core or GraphQL via contributed modules. 

It’s also worth noting the Decoupled Menus initiative aims to prove the model for integrating JavaScript libraries with the RESTful Web Services API. The goals of this initiative are to make the JavaScript developer experience and the process of building decoupled experiences in Drupal rival competing content management platforms.

Drupal’s Continuous Innovation Model

Once you’ve migrated to Drupal 9, future updates (like Drupal 10) will be minor releases. This is due to introducing a continuous innovation model that aims to shorten release cycles, add new features and APIs, and simplify the upgrade path. This development model reduces the total cost of ownership and allows organizations to spend less time maintaining the platform and more time investing in features that will grow the business. 

More in Core With Drupal

Panels in Drupal 7 have been replaced with Layout Builder. This enables site administrators to visually configure content in Drupal by node or content type. Acquia customers can take this a step further by using the Site Studio low-code page building tool. Other enhancements include a native media library that enables content authors to upload and reuse media assets, a modernized administrative theme, improved multilingual support, enhanced accessibility features which comply with WCAG 2.0 and ATAG 2.0, customizable workflow tools, and robust configuration management. 

Where to Start With Your Migration?

Before any code is written or migrations are run, the first step to any successful platform upgrade should be putting together a plan and defining what success looks like. Many organizations will use these projects as an opportunity to make other enhancements to the website. For example, there may be content on your existing site that is out of date or doesn’t receive much traffic based on your analytics. You may manage a taxonomy structure that has grown unwieldy or content types that can be consolidated or removed altogether. In short, we want to ensure any incorrect assumptions, bad habits, or abandoned features don’t make their way into the new experience. 

If it’s been a few years since any visual updates have been made, this could also be a great opportunity to update the look and feel of the website. Moving from PHPTemplate to TWIG and including Layout Builder in core opens up new theming possibilities for developers. This may also be the right time to modernize the look of your site and revisit the information architecture while simultaneously updating the theme layer. As mobile traffic has increased, optimizing for a mobile-first approach that prioritizes performance, responsive assets, and serving the best experience regardless of the device should be part of the implementation plan.

Before jumping in, it’s important to understand if there’s a migration path for any modules in use and identify alternative approaches where there are gaps. This process typically starts with taking inventory of the existing modules and content, verifying and documenting existing functionality, and identifying deprecated code. Though this can be done manually, the Migrate Accelerate tool can significantly streamline this effort for organizations using the Acquia platform. The Acquia solution will recommend Drupal 9 modules and patches based on Drupal 7 and tooling that helps automate the content migration process. There are also some helpful solutions like the static PHP analysis tool, drupal-check, and using the upgrade status module.

The outcomes of this evaluation may reveal that an automated migration may not be the best approach. If the content, information architecture, and designs are changing significantly, it may make more sense to rebuild your site in Drupal 9 instead of porting over lots of content that is no longer relevant. The best approach will vary, but it's important to identify the unique needs of your organization before jumping straight into migrating data.

Migrating to Drupal 9

Due to underlying architecture changes in Drupal 8 and 9, more work is required to migrate a Drupal 7 site. Moving will require migrating both content and configuration to a clean Drupal 9 website. Drupal 9 also uses Composer for PHP package management, which is a shift from managing projects in Drupal 7. You’ll want to be mindful to structure your composer files correctly, but there are some helpful existing composer project templates like the Drupal Recommended Project, opinionated build tools via Acquia BLT, and the Acquia CMS project for Acquia customers. 

There are two approaches to migrating from Drupal 7 to 9, using the Migration UI or Drush. Using the Migration UI assumes you want to migrate everything and first requires enabling the core migration modules and any other required modules needed in the new experience. This includes installing and enabling the Migrate Upgrade, Migrate Plus, and Migrate Tools contributed modules.

To proceed with the UI approach, import the D7 database, visit the upgrade path, enter your credentials, and follow the on-screen instructions to run the migration. The core Migrate modules support most nodes, taxonomy, fields, users, content, and user roles. However, themes, custom modules, and views without a contrib migration path will need to be rebuilt. This also assumes the contributed modules used in Drupal 7 have a migration path to Drupal 9. Any modules without a clear upgrade path will require manual or custom migration. 

For developers looking for greater configuration options, using Drush provides more flexibility to pick and choose your migrations. After importing the D7 database, you can run the following Drush command to get a list of the available migrations:

drush migrate:upgrade --legacy-db-url=mysql://root:root@localhost/drupal7db --legacy-root=drupal7site/docroot --configure-only

From there, you can run Drush migrate-import (or Drush mim) for the individual migrations you’d like to bring over to the Drupal 9 website. For example: 

drush mim d7_user

Lastly, there is a lot of helpful documentation on this process on Drupal.org. There is also a running list of known issues which may be a helpful resource for troubleshooting migration issues. Depending on the amount of content that needs to be migrated and the complexity of the Drupal 7 site, developers should expect some level of trial and error to ensure all intended content was migrated successfully. Stripping down the Drupal 7 site to the bare essentials before starting this process can help greatly streamline this effort. 

The Drupal Drop will Keep Moving

The Drupal project celebrated its 20th anniversary in January 2021. The web has changed significantly over that time as we’ve seen internet fads come and go. However, it’s a testament to the Drupal project leads and the developer community for continuing to push the platform forward so that it remains relevant today. 

There are some exciting initiatives planned, including making Drupal easier for new users with the Easy out-of-the-box initiative, making it easier to find and install relevant modules with Project Browser, and simplifying the Drupal contribution process with GitLab Acceleration. For any organization evaluating a migration from Drupal 7, this should be the last significant upgrade needed to take advantage of all the new and exciting features now available in modern Drupal.