Migration de Craft CMS 2 vers Craft 5 : Guide complet

Prérequis

Ce guide couvre le parcours complet de Craft CMS 2/PHP 5.6 vers Craft CMS 5/PHP 8.3, soit environ huit ans de changements de plateforme. Ce guide de mise à niveau Craft CMS couvre les deux approches principales de migration, les exigences techniques spécifiques et les pièges qui font trébucher la plupart des équipes.

Un point critique d'entrée de jeu : les mises à niveau directes ne sont pas supportées. Craft exige de passer par chaque version majeure (2→3→4→5), bien que plusieurs développeurs choisissent une reconstruction complète étant donné les changements architecturaux impliqués. Ce processus de migration de CMS legacy nécessite une planification minutieuse.

Prérequis

Avant de commencer, confirmez que vous avez :

Accès à l'environnement actuel :

• Accès SSH à votre serveur existant
• Capacité d'exportation de base de données (mysqldump ou similaire)
• Accès à tous les fichiers sources, incluant les plugins personnalisés
• Documentation de toutes les configurations spécifiques au serveur

Environnement cible prêt :

• PHP 8.2 ou supérieur (8.3 recommandé)
• MySQL 8.0.17 (InnoDB) ou PostgreSQL 13 
• Composer 2.0 
• Limite de mémoire PHP de 512 Mo 
• Certificat SSL configuré

Documentation préparée :

• Liste de tous les plugins actifs
• Code source des modules/plugins personnalisés
• Inventaire des fichiers de gabarits
• Documentation du modèle de contenu (sections, champs, types d'entrées)

Sauvegardes vérifiées :

• Sauvegarde complète de la base de données testée pour restauration
• Sauvegarde complète du système de fichiers incluant les assets
• Instantané du contrôle de version si vous utilisez Git

Choisir votre parcours de mise à niveau

Vous avez deux options. Le bon choix dépend de la complexité de votre site et des priorités de votre équipe.

Parcours 1 : Reconstruction complète

La documentation officielle de Craft recommande de traiter les mises à niveau de Craft 2 comme la construction d'un nouveau site. Cette approche de reconstruction complète n'est pas un raccourci. C'est souvent l'approche la plus fiable.

Idéal pour :

• Sites de petite à moyenne taille
• Sites avec des plugins obsolètes ou discontinués
• Projets où vous souhaitez redessiner le modèle de contenu
• Équipes avec peu de temps pour déboguer des problèmes spécifiques aux versions

Délai typique : 20-40 heures pour un site de petite entreprise

Parcours 2 : Mise à niveau séquentielle

Quand vous devez préserver un modèle de données exact ou avez des installations Commerce complexes, vous passez par chaque version : 2→3→4→5. Ce parcours de mise à niveau séquentielle préserve votre architecture existante.

Idéal pour :

• Sites avec un investissement important en plugins personnalisés
• Configurations de commerce électronique complexes
• Cas où le modèle de contenu existant doit rester inchangé
• Sites déjà partiellement mis à jour vers Craft 3

Notre expérience démontre que le Parcours 1 tend à être plus rapide et produit des résultats plus propres pour la plupart des migrations Craft 2. Le Parcours 2 a du sens quand vous avez du code personnalisé significatif qui fonctionne encore et serait coûteux à recréer.

Parcours 1 : Processus de reconstruction complète

Étape 1 : Créer un nouveau projet Craft 5

Sur votre environnement cible, exécutez :

composer create-project craftcms/craft your-project-name

Suivez les instructions de l'installateur pour configurer votre connexion à la base de données et créer un compte administrateur.

Étape 2 : Recréer votre modèle de contenu

Dans le panneau de contrôle Craft 5, reconstruisez vos sections, types d'entrées et champs. C'est votre opportunité d'améliorer l'architecture de contenu.

Examinez attentivement vos champs Craft 2. Certains types de champs ont changé :

• Les blocs Matrix sont maintenant des « types d'entrées » dans Craft 5, un changement architectural significatif
• Certains types de champs tiers peuvent ne pas avoir d'équivalents Craft 5

Documentez le mappage entre les anciens et nouveaux identifiants de champs. Vous en aurez besoin pour la migration de contenu.

Étape 3 : Exporter le contenu de Craft 2

Créez des scripts d'exportation pour extraire le contenu de votre base de données Craft 2. Le format JSON fonctionne bien pour les scripts d'importation :

// Simple export example for Craft 2 entries
$entries = craft()->elements->getCriteria(ElementType::Entry)
    ->section('blog')
    ->find();

$export = [];
foreach ($entries as $entry) {
    $export[] = [
        'title' => $entry->title,
        'slug' => $entry->slug,
        'postDate' => $entry->postDate->format('Y-m-d H:i:s'),
        'fields' => [
            'body' => (string)$entry->body,
            'summary' => $entry->summary,
            // Map all custom fields
        ]
    ];
}

file_put_contents('blog-export.json', json_encode($export, JSON_PRETTY_PRINT));

Étape 4 : Importer le contenu dans Craft 5

Écrivez des scripts d'importation ou utilisez Feed Me (s'il est disponible pour votre structure de contenu) pour intégrer le contenu dans Craft 5 :

// Craft 5 console command or module for import
use craft\elements\Entry;

$data = json_decode(file_get_contents('blog-export.json'), true);

foreach ($data as $item) {
    $entry = new Entry();
    $entry->sectionId = Craft::$app->sections->getSectionByHandle('blog')->id;
    $entry->typeId = /* your entry type ID */;
    $entry->title = $item['title'];
    $entry->slug = $item['slug'];
    
    $entry->setFieldValues([
        'body' => $item['fields']['body'],
        'summary' => $item['fields']['summary'],
    ]);
    
    Craft::$app->elements->saveElement($entry);
}

Étape 5 : Migrer les assets

Copiez vos fichiers d'assets vers les emplacements de volumes d'assets du nouveau serveur. Mettez à jour les paramètres d'Assets dans Craft 5 pour correspondre à la configuration de vos volumes.

Pour les grandes bibliothèques d'assets, rsync fonctionne bien :

rsync -avz old-server:/path/to/assets/ /new-path/to/assets/

Étape 6 : Reconstruire les gabarits

Les gabarits Twig de Craft 2 ne fonctionneront pas directement dans Craft 5. La migration des gabarits Craft CMS nécessite un remaniement significatif car la syntaxe a changé considérablement :

| Changement | Craft 2 | Craft 5 |

| Macros | Disponibles globalement | Doivent être importées explicitement |

| Pagination | {% paginate %}...{% endpaginate %} | {% paginate %} (sans endpaginate) |

| CSS/JS | {% includeCss %}, {% includeJs %} | {% css %}, {% js %} |

Réécrivez chaque gabarit en testant au fur et à mesure. C'est souvent la plus grande portion du travail de reconstruction.

Parcours 2 : Processus de mise à niveau séquentielle

Étape 1 : Craft 2 → Craft 3

La mise à niveau de Craft 2 vers Craft 3 est la première étape. Créez un nouveau projet Craft 3 et migrez :

• Installez Craft 3 à neuf
• Copiez votre clé de licence et fichiers de configuration
• Exportez et importez votre base de données
• Mettez à jour PHP vers 7.0 (minimum Craft 3)
• Exécutez php craft setup et suivez les instructions
• Adressez les dépréciations de gabarits (Craft 3 utilise Twig 2)

Référence : Documentation de mise à niveau Craft 2 vers 3

Étape 2 : Craft 3 → Craft 4

Avant la mise à niveau :

• Mettez à jour vers la dernière version Craft 3.x
• Mettez à jour PHP vers 8.0.2 
• Corrigez tous les avertissements de dépréciation affichés dans le panneau de contrôle

Ensuite :

composer require craftcms/cms:^4.0.0
php craft up

Référence : Guide de mise à niveau Craft 3 vers 4

Étape 3 : Craft 4 → Craft 5

Craft 5 inclut un utilitaire de mise à niveau. Avant de commencer :

• Mettez à jour vers la dernière version Craft 4.x
• Confirmez que PHP 8.2 est en cours d'exécution
• Gérez le charset et la collation de la base de données

Exécutez la mise à niveau :

composer require craftcms/cms:^5.0.0
php craft up

Vous devrez peut-être gérer la conversion de charset :

php craft db/convert-charset

Référence : Guide de mise à niveau Craft 4 vers 5

Migration de base de données : Spécificités MySQL 8

La migration de base de données Craft CMS vers MySQL 8 Craft CMS nécessite une attention aux paramètres de charset. Craft 5 utilise des paramètres de charset et collation par défaut différents :

| Paramètre | Valeur par défaut Craft 5 |

| Charset | utf8mb4 |

| Collation | utf8mb4_0900_ai_ci |

Si vous mettez à niveau depuis MySQL 5.7, vous devrez gérer cette conversion. La commande php craft db/convert-charset gère la plupart des cas.

Pour un contrôle manuel, vous pouvez temporairement définir le charset dans votre fichier .env :

DB_CHARSET=utf8mb4
DB_COLLATION=utf8mb4_0900_ai_ci

Ensuite, exécutez la conversion et supprimez ces variables d'environnement après avoir confirmé le succès.

Les équipes avec lesquelles nous travaillons rapportent que les problèmes de collation se manifestent souvent comme des problèmes de tri, particulièrement avec du contenu non anglais. Testez minutieusement avec des échantillons de contenu réels.

Erreurs courantes à éviter

1. Sauter des versions majeures

Vous ne pouvez pas passer directement de Craft 3 à Craft 5. Les scripts de migration de Craft dépendent du schéma de la version précédente. Tenter de sauter corrompra votre base de données.

2. Ignorer la compatibilité des plugins

La compatibilité des plugins Craft CMS est critique. Vérifiez chaque plugin pour le support Craft 5 avant la mise à niveau. Plusieurs plugins Craft 2 n'ont jamais été mis à jour au-delà de Craft 3. Construisez un tableau de correspondance entre les plugins actuels et leurs équivalents ou alternatives Craft 5.

3. Sous-estimer le travail sur les gabarits

Les changements de syntaxe Twig entre les versions sont étendus. Prévoyez du temps significatif pour la réécriture des gabarits, souvent plus que la migration du CMS elle-même.

4. Tester seulement avec du contenu échantillon

Le contenu réel révèle les cas limites. Testez avec un dump complet de base de données, pas avec une poignée d'entrées échantillons.

5. Oublier la limite de l'écosystème Composer

Les versions de Craft antérieures à 3.6 peuvent avoir de la difficulté à mettre à jour les dépendances après février 2025 en raison de changements dans l'écosystème Composer. Si vous êtes sur une version Craft 3 plus ancienne, mettez à jour vers la dernière 3.x d'abord.

6. Présumer la parité MariaDB

La documentation Craft 5 ne recommande plus MariaDB pour les sites volumineux ou à fort trafic en raison de la « parité divergente avec MySQL ». Si vous utilisez MariaDB, vérifiez la compatibilité ou planifiez de passer à MySQL 8.

Tests et vérification

Avant la mise en ligne

1. Vérification du contenu

• Comparez le nombre d'entrées entre l'ancien et le nouveau site
• Vérifiez ponctuellement 10-20 entrées dans différentes sections
• Vérifiez que toutes les données des champs personnalisés ont migré correctement

2. Vérification des assets

• Confirmez que toutes les images et fichiers sont accessibles
• Vérifiez que les transformations d'images se génèrent correctement
• Testez les téléchargements de PDF et documents

3. Tests des gabarits

• Testez chaque type de gabarit unique
• Vérifiez que la pagination fonctionne sur les pages de liste
• Vérifiez que les formulaires se soumettent correctement
• Testez la fonctionnalité de recherche

4. Base de référence de performance

• Exécutez des tests de charge avec des patrons de trafic réalistes
• Vérifiez la performance des requêtes de base de données dans la barre d'outils de débogage Craft
• Vérifiez que la mise en cache est configurée et fonctionne

5. Acceptation utilisateur

• Demandez aux éditeurs de contenu de tester leurs flux de travail
• Vérifiez que les permissions fonctionnent comme prévu
• Testez tout ajout personnalisé au panneau de contrôle

Surveillance post-lancement

Gardez l'ancien site accessible (même hors ligne) pendant au moins 30 jours. Les problèmes se manifestent souvent quand de vrais utilisateurs interagissent avec le nouveau système.

Surveillez :

• Les erreurs 404 provenant d'URLs modifiées
• Les liens internes brisés
• Les images manquantes dans le contenu plus ancien
• Les problèmes d'indexation de recherche

Conclusion

Migrer de Craft 2/PHP 5.6 vers Craft 5/PHP 8.3 nécessite une planification significative, mais le retour sur investissement est substantiel : meilleure sécurité, performance améliorée (PHP 8.3 roule 5-42% plus vite selon la charge de travail) et accès à des années d'améliorations de la plateforme. Quand vous mettez à niveau Craft CMS, vous mettez aussi à niveau PHP 5.6 vers 8.3 pour ces gains de performance.

Pour la plupart des sites Craft 2, une reconstruction complète offre le chemin le plus propre vers l'avant. Les mises à niveau séquentielles restent viables quand vous avez du code personnalisé complexe ou des configurations Commerce qui justifient les étapes supplémentaires.

Nous recommandons de commencer par un audit approfondi de vos plugins et gabarits actuels. Ces deux domaines déterminent quel parcours a du sens pour votre projet et combien de travail vous attend. Si vous avez besoin de services de migration Craft CMS et voulez éviter les pièges courants, nous pouvons vous aider à évaluer votre configuration actuelle et choisir la bonne approche pour votre échéancier et budget.