Complete Guide: Migrating from Drupal 7 to Drupal 11

With Drupal 7’s end of life approaching on January 5, 2025, now is the critical time to plan your migration to Drupal 11. This comprehensive guide walks you through each step of the migration process, helping you avoid common pitfalls and ensure a smooth transition.

Introduction

Drupal 7 has been a trustworthy platform for many organizations for over a decade, but its end of life is rapidly approaching. After January 5, 2025, Drupal 7 will no longer receive security updates or bug fixes, leaving websites vulnerable to security threats and compliance issues. Migrating to Drupal 11 (released in August 2024) not only resolves these security concerns but also provides access to modern features, improved performance, and better user experience.

It’s important to understand that migrating from Drupal 7 to Drupal 11 is not a simple upgrade but rather a complete rebuild due to fundamental architectural changes. This guide will help you navigate this complex process step by step.

Prerequisites

Before beginning your migration, ensure your environment meets these Drupal 11 requirements:

• PHP: Version 8.3 with zlib extension enabled
• Web Server: Apache 2.4.7+, Nginx 1.1+, or any web server with proper PHP support
• Database: Compatible with MariaDB/MySQL (specific versions supported by Drupal 11)
• Memory: Minimum 1GB RAM for Composer (more recommended for complex sites)
• Tools: Drush 13, Composer

Step 1: Comprehensive Site Analysis

Timeline: 1-2 weeks

Begin with a thorough inventory of your Drupal 7 site to understand its structure and complexity:

1. Document content types: List all content types and their field structures
2. Catalog modules: Identify all contributed and custom modules
3. Analyze theme: Document theme structure and customizations
4. Map user roles and permissions: Detail all user roles and their access rights
5. Identify integrations: List all third-party integrations and APIs

Tools to use:

# For generating a comprehensive site audit
drush @yoursitealias pm-list --format=csv > modules.csv
drush @yoursitealias sql-query "SELECT type, COUNT(*) FROM node GROUP BY type" > content_types_count.csv
  

Alternatively, if you have the Devel module enabled, you can use the data collection tool to extract necessary information for estimating migration costs.

Step 2: Set Up Development Environment

Timeline: 2-3 days

1. Install local development environment:
   • Set up DDEV, Lando, or another local development tool
   • Install appropriate PHP version (8.3+)
2. Create a fresh Drupal 11 installation:

   
   composer create-project drupal/recommended-project my_drupal11_site
   cd my_drupal11_site
   composer require drush/drush
         

3. Configure database connections:
   • Set up the database for your new Drupal 11 site
   • Prepare access to your Drupal 7 database for migration
4. Update settings.php to include the Drupal 7 database connection:

   
   $databases['migrate']['default'] = [
     'database' => 'drupal7_db',
     'username' => 'username',
     'password' => 'password',
     'prefix' => '',
     'host' => 'localhost',
     'port' => '3306',
     'namespace' => 'Drupal\\mysql\\Driver\\Database\\mysql',
     'driver' => 'mysql',
   ];
         

Step 3: Enable Migration Modules

Timeline: 1 day

Enable the core migration modules required for the migration process:

drush en migrate migrate_drupal migrate_drupal_ui -y
  

For more complex migrations, consider additional contributed modules:

composer require drupal/migrate_plus drupal/migrate_tools drupal/migrate_upgrade
drush en migrate_plus migrate_tools migrate_upgrade -y
  

Step 4: Module Compatibility Assessment

Timeline: 1-2 weeks

1. Analyze module compatibility:
   • Install the Upgrade Status module:

     
     composer require drupal/upgrade_status
     drush en upgrade_status -y
               

   • Visit /admin/reports/upgrade-status to check module compatibility
2. Create a migration plan for each module:
   • Identify direct replacements for Drupal 7 modules
   • Find alternative modules for deprecated functionality
   • Plan custom development for unsupported features
3. Install required modules on Drupal 11:

   
   composer require drupal/[module_name]
   drush en [module_name] -y
         

Step 5: Run Migration Assessment

Timeline: 1-2 days

1. Run migration assessment using Drupal UI:
   • Navigate to /upgrade in your Drupal 11 site
   • Select your Drupal 7 database
   • Review the assessment report for potential issues
2. Address identified issues:
   • Resolve content type field incompatibilities
   • Adjust database structure as needed
   • Prepare custom migration scripts for complex content

Step 6: Create Migration Configuration Files

Timeline: 1-3 weeks (depending on complexity)

For complex migrations, create custom migration YAML files to handle specific content types:

1. Create custom migration files for each content type:

   
   # Example: article_migration.yml
   id: article_migration
   label: 'Article migration from Drupal 7'
   migration_group: custom
   source:
     plugin: d7_node
     node_type: article
   destination:
     plugin: entity:node
   process:
     type:
       plugin: default_value
       default_value: article
     title: title
     # Map other fields accordingly
   migration_dependencies:
     required:
       - user_migration
         

2. Create migration files for taxonomy, users, files, and other entities
3. Configure field mappings for each content type

Step 7: Execute Migration

Timeline: 1-2 weeks

1. Run the basic migration using the UI or Drush:

   
   # Using Drush
   drush migrate:import --all
   
   # Or for specific migration
   drush migrate:import article_migration
         

2. Monitor the migration for errors:

   
   drush migrate:status
         

3. Address issues as they arise:

   
   # Reset a specific migration to try again
   drush migrate:reset article_migration
         

4. Validate migrated content by comparing counts and sampling content:

   
   drush sql-query "SELECT type, COUNT(*) FROM node GROUP BY type"
         

Step 8: Theme Development

Timeline: 2-4 weeks

Drupal 11 uses the Twig templating engine, which is significantly different from Drupal 7’s PHPTemplate system:

1. Choose a base theme (e.g., Olivero, Claro, or Bootstrap)
2. Create a custom theme:

   
   # Create theme directory
   mkdir -p themes/custom/your_theme_name
         

3. Set up theme files:
   • Create your_theme_name.info.yml
   • Develop Twig templates
   • Implement CSS and JavaScript
4. Recreate the look and feel of your Drupal 7 site using modern techniques

Step 9: Custom Code Migration

Timeline: 2-4 weeks

1. Use Drupal Rector to assist with code updates:

   
   composer require palantirnet/drupal-rector --dev
         

2. Rewrite custom modules to use Drupal 11’s API:
   • Convert hooks to services and plugins
   • Implement dependency injection
   • Use OOP principles
3. Update custom field types, entities, and other custom code

Step 10: Test and Quality Assurance

Timeline: 2-3 weeks

1. Perform functional testing:
   • Verify all content migrated correctly
   • Test all user workflows
   • Check responsive design and mobile compatibility
2. Run automated tests:

   
   # Run PHPUnit tests
   ./vendor/bin/phpunit
   
   # Check code quality
   composer require drupal/coder --dev
   ./vendor/bin/phpcs --standard=Drupal modules/custom
         

3. Conduct security audits:
   • Use the Security Review module
   • Check for vulnerabilities and best practices
4. Perform load testing to ensure the site handles traffic efficiently

Step 11: Prepare for Launch

Timeline: 1-2 weeks

1. Create a deployment plan:
   • Document all steps needed for the production migration
   • Prepare database migrations
   • Create file transfer procedures
2. Set up the production environment:
   • Configure production server with PHP 8.3+
   • Set up caching and optimization
   • Install SSL certificates
3. Create backup strategies:
   • Full database backups
   • File system backups
   • Configuration exports

Step 12: Launch and Monitor

Timeline: 1 week

1. Perform the production migration:
   • Follow the deployment plan
   • Migrate content and files
   • Configure production settings
2. Conduct final testing:
   • Verify all features work in production
   • Test user login and permissions
   • Check third-party integrations
3. Monitor the site:
   • Set up performance monitoring
   • Configure error logging
   • Implement security monitoring

Step 13: User Training and Documentation

Timeline: 1-2 weeks

1. Prepare user documentation:
   • Create user manuals for content editors
   • Document administrative processes
2. Conduct training sessions:
   • Train content editors on the new interface
   • Provide admin training for site managers
3. Establish support channels for user questions and issues

Common Challenges and Solutions

Challenge 1: Complex Content Structures

Solution:

• Map out all field relationships before migration
• Use custom migration scripts for complex content types
• Consider a phased approach for particularly complex structures

Challenge 2: Module Compatibility

Solution:

• Conduct early module compatibility assessment
• Identify alternative modules for unsupported functionality
• Allocate budget for custom module development if needed

Challenge 3: Theme Redesign

Solution:

• Use the migration as an opportunity to modernize your design
• Leverage Drupal 11’s improved theming system
• Consider hiring a front-end specialist if internal resources are limited

Challenge 4: Custom Code Migration

Solution:

• Utilize tools like Drupal Rector to identify deprecated code
• Rewrite custom modules using modern PHP practices
• Break the migration into manageable components

Benefits of Drupal 11

After completing your migration, you’ll enjoy numerous advantages:

• Enhanced Security: Regular security updates and modern security practices
• Improved Performance: Better caching and optimization
• Modern Interface: Improved admin experience with the new admin theme
• Mobile Compatibility: Responsive design out of the box
• Future-Proofing: Support until at least 2026, with easier upgrades to future versions

Conclusion

Migrating from Drupal 7 to Drupal 11 is a significant undertaking, but with proper planning and execution, it offers substantial benefits for your organization. The process not only ensures continued security and functionality but also provides an opportunity to modernize your digital presence and take advantage of Drupal’s latest features.

Begin your migration planning today to ensure a smooth transition before Drupal 7’s end of life in January 2025. With this guide, you’re well-equipped to navigate the complexities of migration and emerge with a stronger, more capable web platform.

Need help with your Drupal migration? Contact our team of Drupal experts who can assist with every aspect of your migration journey, from planning to execution and post-launch support.