prethiee

Upgrading Drupal 7 to Drupal 9: A Step-by-Step Guide for Code Migration

September 12th, 2024
Migration Upgrade Security Performance Drupal9
Drupal 7, once a staple in the CMS world, has reached its end-of-life, and upgrading to Drupal 9 is crucial for security, performance, and access to modern features. The jump from Drupal 7 to Drupal 9 is substantial, requiring a complete migration of content, configuration, and code due to significant architectural changes in Drupal 8 and 9. This guide will help you understand the steps involved in upgrading Drupal 7 to Drupal 9, focusing specifically on code migration.
 
Before you begin the migration, it’s important to assess your existing Drupal 7 site. Here’s what you should evaluate:
 
Custom Modules and Themes: Identify custom modules and themes, as these will need to be rewritten for Drupal 9.
Contributed Modules: Check which contributed modules you’re using and determine if they are available in Drupal 9 or need alternatives.
Content Types and Fields: Understand your content structure to ensure all configurations are properly migrated.
 
Tools to Help Assess
Upgrade Status Module: Install the Upgrade Status module on your Drupal 7 site to get an overview of what needs upgrading.
 
Step 2: Set Up a New Drupal 9 Environment
 
Since Drupal 7 to Drupal 9 is not a direct upgrade, you will need to set up a fresh installation of Drupal 9.
 
2.1. Install Drupal 9
 
Set up a clean Drupal 9 environment on your server or local machine. You can follow the official documentation to install Drupal 9.
composer create-project drupal/recommended-project my_site_name_dir
2.2. Set Up Modules for Migration
 
Ensure that the following migration-related modules are enabled in your Drupal 9 installation:
 
drush en migrate migrate_drupal migrate_drupal_ui
These modules help in content and configuration migration but won’t migrate custom code, which we'll tackle separately.
 
Step 3: Migrating Content and Configurations
 
Migrating your content, users, taxonomy, and configurations is an important step. Drupal 9 uses the Migrate API to handle this process, which was significantly improved in Drupal 8 and remains consistent in Drupal 9.
 
3.1. Run the Migration UI
You can use the Migrate Drupal UI to migrate the content from your Drupal 7 site.
 
1. Go to `/upgrade` on your Drupal 9 site.
2. Enter the details of your Drupal 7 site (such as the database and file paths).
3. Run the migration.
 
3.2. Handle Custom Configurations
For custom content types, fields, and configurations, you might need to manually re-create them in Drupal 9 or use the Migrate API to map configurations.
 
Step 4: Migrating Custom Code (Modules and Themes)
Custom modules and themes in Drupal 7 require significant reworking to be compatible with Drupal 9 due to changes in the core architecture, particularly with the introduction of Symfony and object-oriented programming in Drupal 8/9.
 
4.1. Rewrite Custom Modules
Drupal 7 modules are written using procedural code, while Drupal 9 requires an object-oriented approach. Here's how you can migrate your custom modules:
 
Module File Structure:
Drupal 7: The `.module` file handled most logic.
Drupal 9: Move to a more structured approach, using `src/` for classes and services.

 
1. Convert Hooks to Plugins/Services: Hooks are less common in Drupal 9, with much of the logic moved to services, event subscribers, or plugins. For example, instead of using `hook_menu()`, you’ll define routes in a `*.routing.yml` file.
 
Example: Replace `hook_block_info()` with a block plugin in Drupal 9.
 
2. Namespace Your Code: Custom modules in Drupal 9 should use proper namespaces.
 
namespace Drupal\my_module\Controller;
use Symfony\Component\HttpFoundation\Response;
class MyController {
   public function content() {
       return new Response('Hello World');
      }
  }
3. Replace Deprecated APIs: Drupal 9 removes many of the APIs that were deprecated in Drupal 8. You’ll need to rewrite these parts of your code. Use the Drupal API change records to check what needs updating. 
 
4. Use Composer: Drupal 9 requires modules and their dependencies to be managed using Composer. Create a `composer.json` file for your module if it has external dependencies.
 
4.2. Update Custom Themes
 
Drupal 7 themes are not compatible with Drupal 9. Here’s how you can update your custom theme:
1. Twig Templates: Replace Drupal 7 `.tpl.php` files with Twig templates. Twig is the new templating engine in Drupal 8/9.
 
<h1>{{ page_title }}</h1>
<div>{{ content }}</div>
 
2. YAML Files: In Drupal 9, themes use YAML files to define settings and libraries. Create a `my_theme.info.yml` file:
 
name: 'My Custom Theme'
type: theme
core_version_requirement: ^9
base theme: classy
libraries:
- my_theme/global-styling
3. Asset Management: Define JavaScript and CSS libraries in `.libraries.yml`. Here’s an example:
 
global-styling:
css:
theme:
css/style.css: {}
 
4.3. Use the Drupal 7 to 9 Upgrade Tools
 
The Drupal Module Upgrader tool can help automate some of the code migration. It scans your Drupal 7 module codebase and provides suggestions for code that needs to be upgraded to Drupal 9.And modules like Upgrade Status, Rector, Drupal check to help remove the deprecated code.
 
composer global require drupal/drupal-module-upgrader
drupal-module-upgrader upgrade /path/to/custom_module
 
Step 5: Testing and Debugging
 
After migrating your custom code, it’s crucial to test the new Drupal 9 site thoroughly.
 
Enable Error Reporting: Set error reporting to full to catch any issues during the development process.
Use Drupal Debugging Tools: Leverage debugging modules like Devel or Webprofiler to track performance and errors.
 
Step 6: Final Touches and Go-Live
 
Once your custom modules, themes, content, and configurations have been migrated and thoroughly tested, you’re ready to deploy your Drupal 9 site. Make sure to:
 
Backup Your Site: Backup both the old Drupal 7 site and the new Drupal 9 site.
Optimize Performance: Enable caching and performance optimization tools on your Drupal 9 site.
Monitor for Issues: After going live, monitor the site for any unexpected issues or bugs.
 
Conclusion
 
Migrating from Drupal 7 to Drupal 9 requires careful planning and execution, especially when dealing with custom code. By following this guide, you can systematically assess, rewrite, and migrate your custom modules and themes, making the transition as smooth as possible. The significant benefits of Drupal 9—such as improved performance, better developer tools, and long-term support—make the effort well worth it for any site.