Streamlining Your Drupal Migration: A Time-Saving Guide

Image

Tick-tock, Drupal 7 users! The clock is winding down to January 5, 2025 – the day Drupal 7 reaches its end of life. After that, the Drupal project will drop support including security updates and bug fixes. While Pantheon offers a Drupal 7 extended life program to help those needing an additional runway to plan their next step, it’s time to get serious. 

Even if you're on a more recent version, upgrading to Drupal 11 is a smart move to stay ahead of potential problems and capitalize on the latest features and improvements.

What Are the Benefits of Migrating to a Newer Version of Drupal?

For those who have worked with Drupal 7 or earlier, updating to a newer version often felt like a massive, complex project. It was a full-on migration that required extensive planning and effort. 

However, with the introduction of Drupal 8, the process has significantly improved. Migrating from Drupal 8 or 9 to Drupal 10 is much more straightforward an upgrade rather than a rebuild. And it brings numerous benefits and new features that make the upgrade worthwhile.

PHP version 8.1+

As of version 10, Drupal requires PHP 8.1, bringing significant performance improvements and new features to the table. Thanks to a reduced memory footprint and better scalability, this upgrade will make your Drupal site faster and more efficient. This means quicker load times and a more powerful platform that can grow with your needs and handle more traffic.

Symfony 6

Drupal relies heavily on Symfony components within its core codebase. By updating to Symfony 6, Drupal 11 brings many benefits, such as:

• Essential bug fixes and vulnerability patches to enhance the overall stability and security of your Drupal site.
• Optimizations that boost your site's performance to ensure faster load times and better resource management.

Symfony 6 also introduces better tools for debugging and development. For example, the improved Drupal Console, built on Symfony Console, offers enhanced functionality to streamline your development workflows. These tools make it simpler to identify and fix issues, accelerating the development process and reducing downtime.

Modern JavaScript

Drupal 11 embraces the shift to modern JavaScript and ES6 standards, moving away from the reliance on jQuery. This transition brings a fresh wave of improvements: 

• Removing unnecessary parts of the jQuery library means faster page load times and a smoother, more efficient user experience. 
• Native browser functions for tasks like DOM manipulation and AJAX requests are more streamlined and effective, making your site feel more responsive.

Drupal now integrates with popular JavaScript frameworks like React, Vue.js and Angular. This allows to create dynamic and interactive user interfaces.

Olivero

Olivero is the new default front-end theme for Drupal 11, replacing Bartik, the go-to for over a decade. This new theme brings a fresh, modern and accessible face to Drupal websites right out of the box:

• Designed with accessibility in mind at every stage ensuring it meets the Web Content Accessibility Guidelines (WCAG) at the AA level.
• The typography is designed to be accessible, even supporting right-to-left languages. 
• You’ll also appreciate the intuitive collapsible header and menus (as well as secondary dropdown menus), along with a handy sidebar.

For developers, Olivero implements PostCSS to reduce maintenance and uses CSS Grid for layout, providing a powerful foundation that can be extensively customized. 

Claro

Drupal 11 introduces a new default administration theme – Claro. For the Seven theme users, Claro will be a significant upgrade. It offers a clean, accessible and powerful admin interface built as part of the Admin UI and JavaScript modernization initiative.

Claro brings a refreshed look with updated icons, improved accessibility and better support for keyboard navigation and screen readers. It’s responsive and adjusts beautifully to different screen sizes, including mobile devices.

Theme Starterkit

The Starterkit theme is a fantastic new feature in Drupal 11. It provides a better starting point for creating custom themes, making it easier for developers to get up and running. 

The Starterkit is a command-line tool that simplifies generating a new theme, improving the onboarding experience for theme developers. It also allows more flexibility by enabling any theme branded as "starterkit" to be used as a source for generating new themes. This approach allows core maintainers to ship theme improvements more frequently without worrying about backward compatibility.

CKEditor 5

Perhaps, one of the most exciting new features in Drupal 11 is the CKEditor 5 integration. It’s a powerful and modern text editor that enhances content creation capabilities. 

CKEditor 5 supports collaborative editing, allowing multiple users to work together on content in real time. This includes features like track changes, comments and revision history, which are available via the CKEditor 5 Premium Features module. 

How To Plan and Prepare for a Drupal Migration

1. Assess Your Current Drupal Site

The first step in planning your migration is to thoroughly assess your current Drupal site. Start by determining which version of Drupal you are on – whether it’s Drupal 7, 8, 9 or 10. This will influence your migration strategy.

Next, create a list of all contributed and custom modules and themes used on your site. It’s crucial to identify which of these are compatible with Drupal 11 and which will need to be updated or replaced. Tools like the Upgrade Status module can be invaluable here, as they help you find deprecated code that needs fixing in custom modules and themes. This assessment phase will give you a clear picture of what needs to be done to get your site ready for Drupal 11.

If you’re on Drupal 10, it’s possible that some of your module dependencies are not ready for migration. If so, you can probably sit tight. However, if you’re currently on Drupal versions 7, 8, or 9, those versions are all past their end-of-life dates, and you should upgrade at least to version 10 to stay current with the project.

2. Plan Your Drupal Migration

With a clear understanding of your current site, it’s time to plan your migration. Decide on the approach that best suits your needs. You have two primary options: 

Option 1: Upgrading an existing Drupal 8/9 site to Drupal 10 

This approach is typically more straightforward if you have been keeping your site up-to-date with the latest minor releases.

Option 2: Building a fresh Drupal 10/11 site and migrating your content.

This approach is more time-consuming but offers a cleaner slate.

Once you’ve decided on an approach, set a timeline for the migration project and allocate the necessary resources. This includes your development team, budget and any additional tools you might need. Communicating the plan and timeline to all stakeholders is also crucial to ensure everyone is on the same page and can prepare accordingly.

3. Prepare Your Drupal 11 Environment

To set up your new Drupal 11 environment, start by setting up a new Drupal 11 site on a development server. This isolated environment will allow you to test and troubleshoot without affecting your live site.

Install and configure the core migration modules, which are Migrate, Migrate Drupal, Migrate Drupal UI and Migrate Tools. These will facilitate the migration process by providing the necessary tools to import content and configurations.

Additionally, install any contributed modules and themes that are compatible with Drupal 10. If you have custom modules and themes, develop or update them to be Drupal 10 compatible, ensuring that any deprecated code is fixed.

4. Perform a Test Migration

Before committing to a full migration, we encourage you to perform a test migration. Use the migration tools to import a subset of your Drupal 7 content into the Drupal 10 development site. This test run allows you to verify that content, users, menus and other site elements will migrate successfully.

Thoroughly test all site functionality on the development site to identify and resolve any issues. This step is crucial for ensuring that the actual migration goes smoothly and that your Drupal 10 site functions as expected.

What Tools and Modules Are Available To Facilitate the Migration Process?

Upgrade Status Module

The Upgrade Status module is an essential tool for assessing the Drupal 10 readiness of your installed modules. It scans your site to identify any modules that are not yet compatible with Drupal 10 and recommends alternative modules or solutions.

Migrate API

The Migrate API provides the underlying framework for migrating configuration and content to Drupal 11. It offers a powerful set of tools and processes for importing data, ensuring that your content and site configurations are accurately transferred to the new version. This API is the backbone of the migration process, allowing for customized migration scripts and automated data handling.

Migrate Drupal Module (Core)

The Migrate Drupal module, included in Drupal core, is specifically designed for migrating configuration and content from Drupal 8 to Drupal 10 or 11. It uses the Migrate API to facilitate a smooth transition.

Migrate Drupal UI Module (Core)

The Migrate Drupal UI module, also part of Drupal core, provides a user-friendly interface at /upgrade for performing upgrades from Drupal 7 to Drupal 10. This interface simplifies the migration process, offering a more intuitive approach to managing your site’s upgrade.

Drupal Rector

Drupal Rector is a powerful developer utility that automates many of the code upgrades needed to make custom modules compatible with Drupal 10 or 11. It supports fixing deprecations up to Drupal 10.1+, a priceless tool for developers looking to streamline the code update process. By automating these changes, Drupal Rector significantly reduces the manual effort required to prepare your custom code for Drupal 10.

Composer

Composer is another essential tool for managing dependencies and updating contributed modules to versions compatible with Drupal 10 and 11. The Upgrade Status module integrates with Composer to streamline this process, ensuring that your modules are up-to-date and ready for migration.

Step-by-Step Guide to Migrating from Drupal 9 to Drupal 10

Step 1: Review the Release Notes

Before starting the upgrade, review the Drupal 10 release notes. These notes provide important information about new features, changes and deprecations. Understanding these will help you prepare for what’s to come.

Step 2: Backup Your Site

Make sure you have a complete backup of your Drupal 9 site. This includes the database and all site files. A backup is essential in case anything goes wrong during the upgrade process, allowing you to restore your site to its previous state.

Step 3: Update to the Latest Minor Version of Drupal 9

Ensure your hosting environment meets the platform requirements of Drupal 10. This includes the PHP version, database and other server configurations. If you're not already on Drupal 9.4.x or 9.5.x, update to one of these versions. Replace any removed modules or themes with their respective contributed projects.

Step 4: Manage Altered Scaffold Files

Drupal core files, such as .htaccess, will change during the upgrade. Note any customizations you've made and reapply them after upgrading.

Remember that deprecated modules and themes in Drupal 9 are removed in Drupal 10. For example, the Seven admin theme and CKEditor 4 module have been deprecated. Switch to alternatives like Olivero and CKEditor 5 before upgrading.

Step 5: Update Contributed Modules and Projects

1. Use the Upgrade Status module to check the compatibility of your contributed modules. Update them using Composer:

composer require drupal/webform:^6.2 --no-update

2. Manually check for compatible versions or patches if Upgrade Status does not identify them.
3. Modify your composer.json file to include versions required by both Drupal 9 and Drupal 10:

"drupal/remove_http_headers": "^1.0 || ^2.0"

4. Remove tools not compatible with Drupal 10, such as Drupal Console:

composer remove drupal/console --no-update

5. Once all modules are compatible, uninstall and remove Upgrade Status:

drush pm-uninstall upgrade_status -y
composer remove drupal/upgrade_status --no-update

Note: Some users prefer removing Drush before updating and reinstalling it afterward to prevent update conflicts.

Step 6: Upgrade to Drupal 10

Make sure you’re performing the upgrade from your Drupal site's root directory. To do this:

1. 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

2. Update core-recommended packages:

composer require 'drupal/core-recommended:^10' 'drupal/core-composer-scaffold:^10' 'drupal/core-project-message:^10' --no-update
composer remove drupal/core --no-update
composer require 'drupal/core-dev:^10' --dev --no-update
composer require 'drush/drush:^12' --no-update

3. Run the update in dry-run mode to check for errors:

composer update --dry-run

4. If there aren’t any errors, perform the actual update:

composer update

You can verify this step by running the following command:

composer install

5. Update the database:

drush updatedb

6. Restore read-only access:

chmod 755 web/sites/default
chmod 644 web/sites/default/*settings.php
chmod 644 web/sites/default/*services.yml

Step 7: Post-Upgrade Tasks

Drupal uses a configuration management system to store site settings and configurations in YAML files. When you upgrade Drupal core, some configurations might change, either because of database updates or due to changes in YAML properties.

You’ll need to:

1. Export your site's configuration to ensure that any changes made during the upgrade are captured. This is especially important if you are working in a development environment and need to push changes to a staging or production environment.
2. Commit the changes to your version control system (e.g., Git). This helps track changes and ensures that the configurations are consistent across different environments. You can verify this step with the git diff command.
3. Apply automated and manual fixes using PHP CodeSniffer (PHPCS). This is a tool that helps ensure your PHP code adheres to Drupal’s coding standards. 
4. If you have custom tests set up for your site, such as PHPUnit or Behat tests, run them to ensure that the upgrade has not broken any functionality.
5. Use Drush to monitor the Drupal watchdog log in real time using the following command:

drush watchdog:tail

Address these issues as needed to ensure smooth functionality.

Now, all that’s left is launching your new Drupal 10 website and communicating this to your users and stakeholders!

Common Challenges Faced During a Drupal Migration

Architectural Differences

One of the most significant challenges when migrating from Drupal 7 to newer versions is the major architectural changes. Drupal 8 introduced a complete overhaul of the system, moving to a more modern and flexible architecture built on Symfony components. This shift means that, for updates prior to Drupal 8, a straightforward upgrade is not possible; instead, a complete rebuild of the site is necessary.

Developers need to familiarize themselves with the new architecture to effectively plan the migration. Understanding concepts such as the Entity API, configuration management and the shift from procedural code to object-oriented programming is necessary. This knowledge will aid in designing a more robust and scalable site in Drupal 11.

Compatibility of Custom Modules and Themes

Custom modules and themes developed for Drupal 7 are not directly compatible with newer versions. This incompatibility requires significant redevelopment or modifications to ensure they work correctly in Drupal 10 or 11.

Data Migration Complexity

Migrating data from Drupal 7 to newer versions can be particularly complex, especially for sites with extensive content and intricate data structures. Here are some best practices to make the process easier:

• Map out how each piece of data in Drupal 7 will translate to the new structure in Drupal 10 or 11.
• Perform migrations in small, manageable batches to minimize the risk of data loss or corruption.
• Use Drupal’s Migrate API and related modules to automate as much of the migration process as possible.

Learning Curve and Training

Transitioning to newer versions of Drupal comes with a learning curve due to new features and changes. Developers and content managers need adequate training to get up to speed with the new system.

Investing in training resources such as online courses, documentation and community forums can significantly reduce the learning curve. Allowing hands-on practice in a development environment before the complete migration can boost your team's confidence in the new platform.

Performance Optimization

After migrating to Drupal 10 or 11, optimizing the site for peak performance is essential. Common performance issues that may arise include slow page load times and inefficient database queries. To address these issues:

• Review and optimize custom code for better performance.
• Implement caching strategies such as Drupal’s built-in caching and reverse proxy caching with Varnish.
• Optimize your database queries and consider using tools like Redis or Memcached for better performance.

Minimizing Downtime

Minimizing downtime during the migration process is critical to maintaining a positive user experience. Thorough planning and testing are key to achieving a smooth transition. Strategies for minimizing downtime include:

1. Use a staging environment to test the migration process before applying it to the live site.
2. As mentioned earlier, perform migrations in stages to reduce the impact on the live site.
3. Have a rollback plan in place in case something goes wrong during the migration.

Security Considerations

Security is a major concern during any migration. Ensuring that your site remains secure throughout the migration process is vital. To maintain and enhance security: 

• Keep your Drupal core and contributed modules up to date with the latest security patches.
• Ensure that your new Drupal 10 site is configured securely, including proper permissions and access controls.
• Conduct security audits and thorough testing of your new site to identify and address any vulnerabilities.

Launch Your Migrated Drupal Site on Pantheon

Congratulations! You’ve made it through the process of migrating to Drupal 10. But, before you go, we’ll leave you with a final thought: 

Are you satisfied with your current hosting environment and know that it’s helping your online presence reach its full potential?

Transitioning to Drupal 10 is the ideal time to evaluate whether your current hosting provider meets your needs. This migration is your chance to update your site's software and reconsider your web host. After all, your hosting environment plays a critical role in your site’s performance, reliability and security.

Pantheon has the fastest Drupal hosting on the planet! 

We offer unparalleled speed and reliability to guarantee your Drupal site performs at its best. With Pantheon, you benefit from a hosting platform specifically optimized for Drupal, providing you with the performance edge you need. This includes:

• Upstreams for controlling site standards.
• Multidev for testing changes in isolated environments.
• Autopilot for automated updates.
• Localdev for local development.
• Object Cache (Redis) for improved performance.
• Global CDN for enhanced security and performance.

Thanks to our world-class security features, you can focus on growing your website, knowing that Pantheon will keep your site secure against emerging threats.

Don’t miss this opportunity! Download our technical sheet on Drupal 10 today to discover all the benefits of this powerful CMS.