Drupal 7 to Drupal 11 Migration: Complete Technical Guide

Unlike previous Drupal upgrades, moving from version 7 to 11 involves migrating to an entirely different architectural foundation. Working with clients through these migrations, we've learned that success depends on thorough preparation and understanding the technical complexities involved.

This guide provides the practical roadmap you need to execute a successful Drupal 7 to 11 migration, from initial assessment through post-launch optimization.

Understanding the Migration Landscape

Why This Isn't Just an Upgrade

The transition from Drupal 7 to 11 represents a fundamental architectural shift. Drupal 8 introduced Symfony components, object-oriented programming, and Twig templating—changes that make direct upgrades impossible. Instead, you're performing a migration that involves:

• Rebuilding your site structure on Drupal 11
• Migrating content and configuration data
• Rewriting custom modules and themes
• Updating integrations and workflows

Technical Benefits of Drupal 11

Drupal 11 introduces several compelling technical improvements:

Performance Enhancements: Built on Symfony 7 and PHP 8.3, Drupal 11 delivers faster execution and better memory management. The new caching system provides significant performance gains for high-traffic sites.

Security Improvements: Regular security updates, improved authentication systems, and better protection against common vulnerabilities make Drupal 11 significantly more secure than legacy versions.

Editorial Experience: The new Claro admin theme and CKEditor 5 provide a more intuitive content editing experience, reducing training time for editorial teams.

Development Experience: Single Directory Components, improved APIs, and better debugging tools make development more efficient and maintainable.

Pre-Migration Assessment and Planning

Technical Requirements Audit

Before beginning your migration, verify your infrastructure meets Drupal 11's requirements:

Server Requirements:

• PHP 8.3 with zlib extension
• MySQL 8.0 or MariaDB 10.6
• Apache 2.4.7 (IIS no longer supported)
• Composer 2.7.7
• Drush 13

Content and Code Inventory:

Create a comprehensive inventory of your current site including:

• All content types and custom fields
• User roles and permissions
• Contributed and custom modules
• Theme customizations
• Third-party integrations
• Custom database tables or structures

Module Compatibility Assessment

Our team recommends using the Upgrade Status module to evaluate your current site's migration readiness:

drush en upgrade_status
drush upgrade_status:analyze

This analysis reveals which modules have Drupal 11 equivalents and identifies custom code requiring updates. Based on client projects, expect approximately 70-80% of contributed modules to have direct equivalents or suitable alternatives.

Content Strategy and Cleanup

Migration projects provide an excellent opportunity to clean up your content architecture. We help clients identify:

• Outdated content types that can be consolidated
• Unused fields and taxonomies
• Orphaned files and media
• Redundant user accounts and roles

This cleanup reduces migration complexity and improves your new site's performance.

Setting Up Your Migration Environment

Environment Preparation

Start by creating a dedicated migration environment that mirrors your production setup:

# Create new Drupal 11 site
composer create-project drupal/recommended-project drupal11_migration
cd drupal11_migration

# Install required migration modules
composer require drupal/migrate_plus drupal/migrate_tools
drush en migrate migrate_drupal migrate_drupal_ui migrate_plus migrate_tools

Database Access Configuration

Ensure your Drupal 11 environment can access your Drupal 7 database. This typically involves:

• Creating a read-only database user for the D7 database
• Configuring network access between environments
• Testing connectivity before proceeding

# Test database connection
drush sql-query --database=migrate "SELECT COUNT(*) FROM users" --legacy-db-url=mysql://user:pass@host/d7db

Executing the Migration

Core Content Migration

The migration process involves several distinct phases. Our approach typically follows this sequence:

Phase 1: Structure Migration

# Migrate users and roles first
drush migrate:import upgrade_d7_user_role
drush migrate:import upgrade_d7_user

# Migrate taxonomy
drush migrate:import upgrade_d7_taxonomy_vocabulary
drush migrate:import upgrade_d7_taxonomy_term

# Migrate content types and fields
drush migrate:import upgrade_d7_node_type
drush migrate:import upgrade_d7_field

Phase 2: Content Migration

# Migrate nodes by content type
drush migrate:import upgrade_d7_node:article
drush migrate:import upgrade_d7_node:page
drush migrate:import upgrade_d7_node:custom_type

# Migrate comments and other content
drush migrate:import upgrade_d7_comment
drush migrate:import upgrade_d7_menu_links

Phase 3: Files and Media

# Migrate files and media
drush migrate:import upgrade_d7_file
drush migrate:import upgrade_d7_file_entity

Handling Complex Migrations

For sites with complex data structures, you may need custom migration plugins. Here's an example of a custom migration configuration:

# Custom migration for complex field data
id: custom_field_migration
label: Custom Field Migration
migration_group: migrate_drupal_7
source:
  plugin: d7_database
  query:
    - SELECT nid, field_custom_data_value, field_custom_data_format
    - FROM field_data_field_custom_data
    - WHERE bundle = 'custom_content_type'
process:
  nid: nid
  field_processed_data:
    plugin: callback
    callable: custom_data_processor
    source: field_custom_data_value
destination:
  plugin: entity:node
  default_bundle: custom_content_type

Managing Migration State

Monitor your migration progress using these essential commands:

# Check migration status
drush migrate:status --group=migrate_drupal_7

# View detailed migration information
drush migrate:messages upgrade_d7_node

# Rollback specific migration if needed
drush migrate:rollback upgrade_d7_node

# Reset migration status
drush migrate:reset-status upgrade_d7_node

Custom Code Migration

Module Development Updates

Custom modules require significant updates for Drupal 11 compatibility. Key changes include:

Hook System Updates: Many hooks have been replaced with event subscribers or services.

// Drupal 7 approach
function mymodule_node_insert($node) {
  // Custom logic
}

// Drupal 11 approach
class MyModuleEventSubscriber implements EventSubscriberInterface {
  public function onNodeInsert(EntityInsertEvent $event) {
    // Custom logic
  }
}

Database API Changes: Direct database queries must be updated to use the new database API.

// Drupal 7
$result = db_query("SELECT nid FROM {node} WHERE type = :type", array(':type' => 'article'));

// Drupal 11
$query = \Drupal::database()->select('node_field_data', 'n');
$query->fields('n', ['nid']);
$query->condition('n.type', 'article');
$result = $query->execute();

Theme Migration

Drupal 7 themes are incompatible with Drupal 11 and must be rebuilt using Twig templates. Our team typically approaches theme migration by:

• Analyzing existing template files and identifying key components
• Creating new Twig templates that match the desired design
• Implementing responsive design improvements
• Optimizing for performance and accessibility

{# Drupal 11 Twig template example #}

  {% if display_submitted %}