Drupal 11 Migration: Step-by-Step Guide für den Upgrade von Drupal 10

Steven Schulz

15. Januar 2025

Drupal 11 Migration: Step-by-Step Guide für den Upgrade von Drupal 10

Drupal 11 wurde im Juli 2024 veröffentlicht und bringt signifikante Verbesserungen in Performance, Security und Developer Experience. Dieser Guide führt Sie durch den kompletten Migrationsprozess von Drupal 10 zu Drupal 11.

Warum auf Drupal 11 upgraden?

Vorteile von Drupal 11

PHP 8.3 Support: Bis zu 40% Performance-Verbesserung
Symfony 7: Neueste Framework-Features und Security Updates
CKEditor 5 Only: Moderne, performante Content-Editing-Experience
Improved Developer Experience: Bessere APIs, neue Hooks
Starshot Initiative: Vorbereitung für Drupal CMS
Extended Support: Sicherheitsupdates bis November 2026

End-of-Life Termine

Drupal 10: Sicherheitsupdates bis Juni 2026
Drupal 9: Support endete im November 2023
Drupal 7: Extended Support bis Januar 2025

System-Requirements Drupal 11

Server-Anforderungen

PHP: 8.3 oder höher
Database:
  - MySQL: 8.0+ / MariaDB 10.6+
  - PostgreSQL: 16+
  - SQLite: 3.45+
Webserver:
  - Apache 2.4+ mit mod_rewrite
  - Nginx 1.19+
Memory: Minimum 256MB, empfohlen 512MB+

PHP Extensions

# Erforderliche Extensions
php-xml
php-gd
php-mbstring
php-curl
php-json
php-zip
php-opcache (empfohlen)
php-apcu (empfohlen)

Pre-Migration Checklist

1. Backup erstellen

# Datenbank Backup
drush sql:dump --gzip > backup-$(date +%Y%m%d-%H%M%S).sql.gz

# Files Backup
tar -czf files-backup-$(date +%Y%m%d-%H%M%S).tar.gz web/sites/default/files

# Code Backup
tar -czf code-backup-$(date +%Y%m%d-%H%M%S).tar.gz \
  --exclude='web/sites/default/files' \
  --exclude='vendor' \
  --exclude='node_modules' \
  .

2. Kompatibilität prüfen

# Drupal Upgrade Status Module installieren
composer require drupal/upgrade_status
drush en upgrade_status -y

# Kompatibilitätsbericht erstellen
drush upgrade_status:analyze

# Report exportieren
drush upgrade_status:export > upgrade-status-report.txt

3. Custom Code analysieren

# PHPStan für static analysis
composer require --dev phpstan/phpstan
vendor/bin/phpstan analyse web/modules/custom

# Drupal Check für Deprecations
composer require --dev mglaman/drupal-check
vendor/bin/drupal-check web/modules/custom

Migration Schritt-für-Schritt

Schritt 1: PHP 8.3 Upgrade

Ubuntu/Debian:

# PHP 8.3 Repository hinzufügen
sudo add-apt-repository ppa:ondrej/php
sudo apt update

# PHP 8.3 installieren
sudo apt install php8.3 php8.3-cli php8.3-fpm php8.3-mysql \
  php8.3-xml php8.3-gd php8.3-mbstring php8.3-curl \
  php8.3-zip php8.3-opcache php8.3-apcu

# Apache Modul wechseln
sudo a2dismod php8.1
sudo a2enmod php8.3
sudo systemctl restart apache2

# Oder für Nginx/PHP-FPM
sudo systemctl restart php8.3-fpm

Überprüfung:

php -v
# Sollte zeigen: PHP 8.3.x

drush status
# Überprüfen Sie die PHP-Version in der Ausgabe

Schritt 2: Composer Updates

composer.json anpassen:

{
  "require": {
    "php": ">=8.3",
    "drupal/core-composer-scaffold": "^11.0",
    "drupal/core-project-message": "^11.0",
    "drupal/core-recommended": "^11.0"
  },
  "config": {
    "platform": {
      "php": "8.3"
    }
  }
}

Dependencies updaten:

# Composer selbst updaten
composer self-update

# Drupal Core auf 11 upgraden
composer require 'drupal/core-recommended:^11.0' \
  'drupal/core-composer-scaffold:^11.0' \
  'drupal/core-project-message:^11.0' \
  --update-with-all-dependencies

# Alle contrib modules updaten
composer update "drupal/*" --with-all-dependencies

Schritt 3: Database Updates

# Site in Maintenance Mode
drush state:set system.maintenance_mode 1 --input-format=integer

# Cache leeren
drush cr

# Database Updates durchführen
drush updatedb -y

# Entity Updates
drush entity:updates -y

# Configuration Import (falls vorhanden)
drush config:import -y

# Cache erneut leeren
drush cr

# Maintenance Mode deaktivieren
drush state:set system.maintenance_mode 0 --input-format=integer

Schritt 4: CKEditor 5 Migration

Drupal 11 unterstützt nur noch CKEditor 5. CKEditor 4 wurde entfernt.

Automatische Migration:

# CKEditor 5 Migration durchführen
drush ckeditor5:upgrade

# Oder manuell über UI:
# /admin/config/content/formats

Custom Plugins migrieren:

// CKEditor 4 (alt)
CKEDITOR.plugins.add('customPlugin', {
  init: function(editor) {
    // ...
  }
});

// CKEditor 5 (neu)
import { Plugin } from '@ckeditor/ckeditor5-core';

export default class CustomPlugin extends Plugin {
  static get pluginName() {
    return 'CustomPlugin';
  }

  init() {
    // ...
  }
}

Schritt 5: Deprecated Code ersetzen

Häufige Deprecations in Drupal 10 → 11:

// ALT (Deprecated)
\Drupal::entityManager()
\Drupal::service('entity.manager')

// NEU
\Drupal::entityTypeManager()
\Drupal::service('entity_type.manager')

// ALT
drupal_set_message()

// NEU
\Drupal::messenger()->addMessage()

// ALT
file_unmanaged_copy()

// NEU
\Drupal::service('file_system')->copy()

// ALT
db_select()

// NEU
\Drupal::database()->select()

Template Updates:

{# ALT #}
{{ drupal_entity('node', node.id) }}

{# NEU #}
{{ drupal_entity('node', node.id(), check_access=true) }}

Schritt 6: Module Compatibility

Deprecated Module ersetzen:

Drupal 10 Module	Drupal 11 Alternative
CKEditor	CKEditor 5 (Core)
RDF	Entfernt, nutze JSON-LD
HAL	JSON:API (Core)
QuickEdit	In-Place Editing
Aggregator	Custom RSS Solution

Module-Status prüfen:

# Installierte Module auflisten
drush pm:list --type=module --status=enabled

# Contrib module auf Drupal 11 Kompatibilität prüfen
drush upgrade_status:analyze

Schritt 7: Configuration Updates

# Config Export (vor Migration)
drush config:export

# Nach Migration: Config Diff überprüfen
drush config:status

# Einzelne Configs importieren
drush config:import --partial --source=/path/to/config

# Oder kompletter Import
drush config:import -y

Schritt 8: Performance Optimization

OPcache konfigurieren (php.ini):

[opcache]
opcache.enable=1
opcache.memory_consumption=256
opcache.interned_strings_buffer=16
opcache.max_accelerated_files=10000
opcache.revalidate_freq=2
opcache.fast_shutdown=1

APCu für besseres Caching:

# APCu installieren
sudo apt install php8.3-apcu

# In settings.php
$settings['cache']['default'] = 'cache.backend.apcu';

Database Tuning:

-- MySQL Query Cache (für MySQL 5.7)
SET GLOBAL query_cache_size = 268435456;
SET GLOBAL query_cache_type = ON;

-- MariaDB Thread Pool
SET GLOBAL thread_pool_size = 8;

Testing nach Migration

1. Automated Testing

# PHPUnit Tests
vendor/bin/phpunit -c web/core web/modules/custom

# Functional Tests
drush test-run --class '\Drupal\Tests\custom_module\Functional\CustomTest'

# JavaScript Tests (Nightwatch)
yarn test:nightwatch

2. Manual Testing Checklist

3. Performance Testing

# Apache Bench
ab -n 1000 -c 10 https://your-site.com/

# Lighthouse
npx lighthouse https://your-site.com/ --view

# Core Web Vitals mit Drush
drush core:requirements

Häufige Probleme & Lösungen

Problem 1: “Composer memory limit exceeded”

# Lösung
COMPOSER_MEMORY_LIMIT=-1 composer update

Problem 2: “Database updates failed”

# Backup wiederherstellen
gunzip < backup.sql.gz | drush sql:cli

# Updates einzeln durchführen
drush updatedb --entity-updates
drush updatedb --post-updates

Problem 3: “CKEditor 5 Migration failed”

# Manuell zurücksetzen
drush config:delete editor.editor.basic_html
drush config:delete filter.format.basic_html

# Neu konfigurieren über UI
# /admin/config/content/formats

Problem 4: “White Screen of Death (WSOD)“

# Error Logging aktivieren
# In settings.php:
$config['system.logging']['error_level'] = 'verbose';

# Logs prüfen
tail -f /var/log/apache2/error.log

# Oder
drush watchdog:show --tail

Rollback-Strategie

Falls die Migration fehlschlägt:

# 1. Code zurücksetzen
git checkout tags/drupal-10-backup

# 2. Composer Dependencies zurücksetzen
composer install

# 3. Datenbank wiederherstellen
gunzip < backup.sql.gz | drush sql:cli

# 4. Files wiederherstellen
tar -xzf files-backup.tar.gz -C web/sites/default/

# 5. Cache leeren
drush cr

# 6. Wartungsmodus deaktivieren
drush state:set system.maintenance_mode 0 --input-format=integer

Best Practices

1. Staging Environment

# Zuerst auf Staging testen
# Niemals direkt auf Production upgraden!

# Staging-to-Production Workflow:
1. Staging: Drupal 11 Migration
2. Testing: 2-4 Wochen
3. Production: Migration mit identischen Steps

2. Incremental Updates

# Nicht direkt von Drupal 9 → 11
# Sondern: 9 → 10 → 11

# Check Current Version
drush status

# Update Path:
Drupal 9.5.x → Drupal 10.0.x → Drupal 10.3.x → Drupal 11.0.x

3. Continuous Integration

# .gitlab-ci.yml
test_drupal_11:
  image: php:8.3-apache
  script:
    - composer install
    - vendor/bin/phpunit
    - vendor/bin/phpstan analyse
  only:
    - merge_requests

Performance Benchmarks

Durchschnittliche Verbesserungen Drupal 10 → 11:

Metric	Drupal 10	Drupal 11	Verbesserung
TTFB	450ms	320ms	-29%
Memory Usage	180MB	145MB	-19%
Cache Build	8.2s	6.1s	-26%
Page Load	1.8s	1.3s	-28%

Kosten-Kalkulation

Entwicklungsaufwand (geschätzt):

Small Site (< 50 Pages): 8-16 Stunden
Medium Site (50-500 Pages): 24-40 Stunden
Large Site (500+ Pages): 60-120 Stunden
Enterprise Site: 150-300 Stunden

Zusätzliche Faktoren:

Custom Module Migration: +20-50%
API Integrationen: +15-30%
Complex Migrations: +30-60%

Fazit

Die Migration von Drupal 10 auf Drupal 11 ist weniger komplex als frühere Major-Upgrades, dank des modernisierten Update-Prozesses. Mit sorgfältiger Planung, gründlichem Testing und diesem Step-by-Step Guide gelingt die Migration effizient und sicher.

Die Performance-Vorteile und erweiterten Features von Drupal 11 rechtfertigen den Migrationsaufwand, besonders für Websites mit hohem Traffic oder komplexen Anforderungen.

Weiterführende Ressourcen

Benötigen Sie professionelle Unterstützung bei Ihrer Drupal 11 Migration? Mit über 20 Jahren Erfahrung und zahlreichen erfolgreichen Drupal-Migrationen helfe ich Ihnen gerne. Kontakt: mail@stevenschulz.net oder 04037420859

← Zurück zum Blog