Migrer un site PHP legacy vers Craft CMS : Guide complet étape par étape

Craft CMS offre une voie d'avenir. Bâti sur PHP 8.2 , Craft apporte une modélisation de contenu flexible, des gabarits Twig propres et de solides outils d'importation qui rendent la migration gérable. Ce guide de migration Craft CMS vous accompagne à travers le processus complet, de l'audit de votre contenu  jusqu'à son importation dans une installation Craft fraîche. Que vous gériez une migration de site web PHP legacy pour la première fois ou que vous planifiiez un effort de modernisation plus important, ce guide couvre chaque étape.

Prérequis

Avant de commencer votre migration, assurez-vous d'avoir les éléments suivants en place :

Environnement de développement

• Configuration de développement local avec PHP 8.2 (DDEV fonctionne bien pour ça)
• Composer 2.0 installé
• MySQL 8.0.17 ou PostgreSQL 13 
• Au moins 256 Mo de mémoire PHP (512 Mo recommandé)

Exigences d'accès

• Accès en lecture à votre base de données legacy
• Accès à votre répertoire de téléversements legacy
• Accès FTP ou SSH à votre hébergement actuel

Connaissances requises

• Compréhension de base de PHP (vous l'avez si vous maintenez un site PHP legacy)
• Familiarité avec les requêtes SQL pour l'extraction de données
• Volonté d'apprendre les bases de Twig (logique similaire au PHP, syntaxe plus propre)

Note importante : Votre environnement d'hébergement PHP 5.2 ne peut pas faire rouler Craft. Prévoyez déployer Craft sur une nouvelle infrastructure qui répond à ces exigences tout en gardant votre site legacy en fonction pendant la migration.

Étape 1 : Auditer votre contenu legacy

Commencez par cataloguer tout ce que votre ancien site contient. Cet inventaire façonne toute votre approche de migration.

Identifiez les types de contenu :

• Articles de blogue, articles ou nouvelles
• Pages statiques (À propos, Contact, Services)
• Fiches produits ou éléments de portfolio
• Contenu généré par les utilisateurs

Cartographiez les relations :

• Catégories ou étiquettes attachées au contenu
• Éléments connexes ou références croisées
• Associations d'auteurs

Inventoriez les médias :

• Où les fichiers se trouvent (habituellement un dossier uploads)
• Patrons de nommage des fichiers
• Si les noms de fichiers doivent être préservés ou normalisés

Documentez les patrons d'URL :

• Structure d'URL actuelle pour chaque type de contenu
• Quelles URLs reçoivent du trafic (vérifiez les analytiques)
• URLs canoniques à préserver pour le SEO

Créez un tableur qui suit chaque type de contenu, sa table de base de données (si applicable), le nombre de champs et le nombre d'enregistrements. Ceci devient votre liste de vérification de migration.

Étape 2 : Concevoir votre modèle de contenu Craft

Cette étape détermine si votre migration réussit ou devient un fouillis frustrant. Nous avons appris que passer plus de temps ici économise beaucoup de retravail plus tard. Une modélisation de contenu Craft CMS appropriée est essentielle pour une migration réussie.

Sections vs Types d'entrées :

Dans Craft, une Section est un conteneur pour du contenu connexe. Les Types d'entrées définissent les dispositions de champs au sein d'une Section. Comprendre les sections et types d'entrées de Craft CMS est fondamental pour ce processus.

Par exemple :

• Une Section « Blogue » pourrait avoir un seul Type d'entrée
• Une Section « Nouvelles » pourrait avoir des Types d'entrées pour « Communiqué de presse » et « Mise à jour de l'entreprise » avec des champs différents

Planification des champs :

Associez vos champs de données legacy aux types de champs Craft :

• Colonnes texte → Champs Texte brut ou Texte enrichi
• Contenu HTML → Champs Redactor ou CKEditor
• Dates → Champs Date
• Clés étrangères → Champs de relations Entrées
• Chemins d'images → Champs Ressources

Décisions sur la structure d'URL :

Craft vous permet de définir des patrons d'URL par Section. Décidez maintenant si vous allez :

• Reproduire exactement votre structure d'URL legacy
• Adopter un patron d'URL plus propre et rediriger les anciennes URLs

Créez vos Sections, Types d'entrées et Champs dans Craft avant d'importer du contenu. Testez en créant manuellement une ou deux entrées pour vérifier que votre modèle capture toutes les données nécessaires.

Étape 3 : Exporter vos données legacy

Vous devez sortir vos données de l'ancien système dans un format que Craft peut consommer. Feed Me, le plugiciel d'importation de Craft, accepte JSON, CSV et XML. Une exportation de base de données legacy en format JSON fonctionne bien pour la plupart des scénarios.

Pour le contenu piloté par base de données :

Créez un script PHP qui interroge votre base de données legacy et produit du JSON :

// legacy-export.php
$pdo = new PDO('mysql:host=localhost;dbname=legacy_db', 'user', 'pass');

$articles = $pdo->query("
    SELECT id, title, body, author, created_at, category_id 
    FROM articles 
    ORDER BY created_at
")->fetchAll(PDO::FETCH_ASSOC);

// Clean and transform data
foreach ($articles as &$article) {
    // Convert legacy date format
    $article['postDate'] = date('Y-m-d H:i:s', strtotime($article['created_at']));
    
    // Strip problematic HTML if needed
    $article['body'] = strip_tags($article['body'], '<p><a><strong><em><ul><li>');
}

header('Content-Type: application/json');
echo json_encode($articles, JSON_PRETTY_PRINT);

Pour le contenu basé sur des fichiers :

Si votre site legacy stocke le contenu dans des fichiers PHP, vous devrez les analyser :

// For sites with content in PHP arrays or includes
$content = [];
foreach (glob('pages/*.php') as $file) {
    include $file;
    $content[] = [
        'title' => $page_title,
        'body' => $page_content,
        'slug' => basename($file, '.php')
    ];
}

echo json_encode($content, JSON_PRETTY_PRINT);

Sauvegardez vos fichiers d'exportation ou hébergez-les à des URLs accessibles pour que Feed Me puisse les consommer.

Étape 4 : Configurer Feed Me et votre importation

Le plugiciel Feed Me pour Craft CMS est l'outil recommandé pour les importations de contenu. Installez Feed Me depuis le Plugin Store de Craft (c'est gratuit et maintenu officiellement) :

composer require craftcms/feed-me
php craft plugin/install feed-me

Créez un nouveau flux dans le panneau de contrôle sous Feed Me → Feeds → New Feed :

• Feed URL : Pointez vers votre fichier ou URL d'exportation JSON
• Feed Type : Sélectionnez JSON (ou CSV/XML selon votre exportation)
• Primary Element : Habituellement le tableau racine dans votre JSON
• Element Type : Entries (pour la plupart des migrations de contenu)
• Target Section : Sélectionnez la Section créée à l'Étape 2

Mappage des champs :

Feed Me présente une interface de mappage visuelle. Pour chaque champ Craft, sélectionnez la clé correspondante de vos données legacy :

Craft Field          Legacy JSON Key
-----------          ---------------
Title                title
Post Date            postDate
Body (Rich Text)     body
Author               author

Gestion des relations :

Si votre contenu legacy a des catégories ou étiquettes, vous avez deux options :

• Importer les catégories d'abord comme flux séparé, puis mapper les catégories d'articles en faisant correspondre par nom ou ID legacy
• Laisser Feed Me créer les catégories à la volée pendant l'importation des articles (plus simple mais moins de contrôle)

Gestion des doublons :

Feed Me peut mettre à jour les entrées existantes plutôt que créer des doublons. Définissez votre identifiant unique (habituellement l'ID legacy ou le slug) dans la section Duplication Handling.

Étape 5 : Migrer vos ressources

Les fichiers médias nécessitent un traitement séparé. La migration des ressources Craft CMS dépend de votre configuration d'hébergement.

Option A : Transfert manuel

• Téléchargez votre dossier uploads legacy
• Créez un Volume de ressources dans Craft pointant vers web/uploads (ou similaire)
• Téléversez les fichiers via FTP ou rsync vers votre nouveau serveur
• Pendant l'importation de contenu, mappez les noms de fichiers aux Ressources Craft correspondantes

Option B : Importation de ressources via Feed Me

Feed Me peut importer des ressources depuis des URLs. Incluez les URLs complètes des images dans votre exportation JSON :

{
  "title": "Article Title",
  "featuredImage": "https://legacy-site.com/uploads/image.jpg"
}

Feed Me téléchargera et créera automatiquement les entrées de Ressources lorsque vous mapperez le champ.

Option C : Script de migration personnalisé

Pour les grandes bibliothèques de médias avec une organisation complexe, une commande console personnalisée vous donne un contrôle total :

// modules/console/controllers/MigrateController.php
namespace modules\console\controllers;

use craft\console\Controller;
use craft\elements\Asset;
use craft\helpers\Assets as AssetsHelper;

class MigrateController extends Controller
{
    public function actionAssets()
    {
        $legacyFiles = glob('/path/to/legacy/uploads/*');
        $volume = \Craft::$app->volumes->getVolumeByHandle('uploads');
        
        foreach ($legacyFiles as $file) {
            $asset = new Asset();
            $asset->tempFilePath = $file;
            $asset->filename = basename($file);
            $asset->volumeId = $volume->id;
            
            \Craft::$app->elements->saveElement($asset);
            $this->stdout("Imported: " . basename($file) . "\n");
        }
    }
}

Étape 6 : Convertir vos gabarits

Vos gabarits PHP legacy doivent devenir des gabarits Twig. La conversion de gabarits PHP vers Twig suit des patrons de logique similaires, mais la syntaxe est plus propre.

Sortie de base :

// Legacy PHP
 echo htmlspecialchars($article['title']); ?>

// Craft Twig
{{ entry.title }}

Notez que Twig échappe automatiquement les sorties par défaut, donc vous n'avez pas besoin des appels htmlspecialchars.

Boucles :

// Legacy PHP
 foreach ($articles as $article): ?>
    <h2> echo $article['title']; ?></h2>
 endforeach; ?>

// Craft Twig
{% for entry in craft.entries.section('articles').all() %}
    <h2>{{ entry.title }}</h2>
{% endfor %}

Conditions :

// Legacy PHP
 if (!empty($article['image'])): ?>
    <img src=" echo $article['image']; ?>">
 endif; ?>

// Craft Twig
{% if entry.featuredImage|length %}
    <img src="{{ entry.featuredImage.one().url }}">
{% endif %}

Inclusion de partiels :

// Legacy PHP
 include 'header.php'; ?>

// Craft Twig
{% include '_partials/header' %}

Travaillez vos gabarits page par page. La structure de gabarits Craft ressemble typiquement à :

templates/
  _layouts/
    base.twig
  _partials/
    header.twig
    footer.twig
  articles/
    _entry.twig (article unique)
    index.twig (liste d'articles)
  index.twig (page d'accueil)

Étape 7 : Configurer les redirections

Préserver votre structure d'URL protège la valeur SEO et évite les liens brisés. Des redirections d'URL appropriées pour la migration SEO sont critiques. Craft offre plusieurs approches de redirection.

Pour les redirections simples :

Le plugiciel Retour (par nystudio107) fournit une interface de panneau de contrôle pour gérer les redirections avec support des caractères génériques et suivi des 404. Le plugiciel Retour pour les redirections est la solution la plus populaire dans l'écosystème Craft.

Pour les redirections basées sur des patrons :

Si votre structure d'URL a changé de façon prévisible, utilisez les routes de Craft ou des redirections au niveau du serveur :

# nginx example
location ~ ^/articles/(\d )$ {
    return 301 /blog/$1;
}

Pour les redirections complexes :

Créez une carte de redirections pendant votre exportation de contenu qui associe les anciennes URLs aux nouvelles :

// During export, generate redirect pairs
$redirects = [];
foreach ($articles as $article) {
    $redirects[] = [
        'old' => '/articles/' . $article['id'],
        'new' => '/blog/' . $article['slug']
    ];
}
file_put_contents('redirects.json', json_encode($redirects));

Importez cette carte dans Retour ou votre configuration serveur.

Erreurs courantes à éviter

Notre expérience montre que certains pièges font trébucher presque chaque projet de migration :

Sauter l'audit de contenu. Se lancer directement dans l'importation mène à découvrir des champs manquants en pleine migration. L'audit prévient cela.

Ignorer l'encodage des caractères. Les bases de données legacy utilisent souvent l'encodage latin1. Craft attend de l'UTF-8. Passez vos données par une conversion d'encodage pendant l'exportation :

$article['body'] = mb_convert_encoding($article['body'], 'UTF-8', 'ISO-8859-1');

Ne pas nettoyer le HTML legacy. Les anciens éditeurs WYSIWYG produisaient du balisage désordonné. Nettoyez-le avant l'importation, pas après :

// Remove inline styles, empty tags, proprietary tags
$article['body'] = preg_replace('/style="[^"]*"/', '', $article['body']);

Importer sans tester d'abord. Exécutez les importations Feed Me sur un sous-ensemble de contenu d'abord (ajoutez une clause LIMIT à votre requête d'exportation). Vérifiez les résultats avant d'importer tout.

Oublier les brouillons et le contenu non publié. Décidez dès le départ si vous migrez les brouillons. Sinon, filtrez-les pendant l'exportation.

Sous-estimer l'organisation des médias. Un dossier uploads legacy avec 10 000 fichiers sans structure devient un problème dans Craft. Considérez organiser en sous-dossiers pendant la migration.

Tests et vérification

Avant de lancer votre site migré, vérifiez la migration en profondeur.

Vérification du contenu :

• Comparez les nombres d'enregistrements entre legacy et Craft
• Vérifiez ponctuellement 10-20 entrées à travers différents types de contenu
• Vérifiez que le contenu texte enrichi s'affiche correctement
• Vérifiez que les images s'affichent et sont liées correctement

Vérification des relations :

• Confirmez que les catégories et étiquettes sont attachées correctement
• Testez les connexions d'entrées reliées
• Vérifiez les assignations d'auteurs

Vérification des URLs :

• Testez les redirections des anciennes URLs vers les nouvelles
• Vérifiez qu'aucune 404 n'apparaît pour les pages importantes
• Exécutez un crawler (Screaming Frog ou similaire) pour trouver les liens internes brisés

Vérification des gabarits :

• Comparez visuellement les pages rendues avec le site legacy
• Testez le comportement responsive si les gabarits ont changé
• Vérifiez les formulaires, la recherche et les fonctionnalités interactives

Vérification de la performance :

• Exécutez un test de performance (Lighthouse, WebPageTest)
• Vérifiez que la mise en cache fonctionne comme prévu
• Vérifiez que les transformations de ressources se génèrent correctement

Créez une liste de vérification des pages et fonctionnalités critiques. Faites tester le site par quelqu'un qui ne connaît pas la migration.

Conclusion

Migrer un site PHP legacy vers Craft CMS implique une planification soignée, une extraction de données méthodique et un mappage de champs patient. Quand vous migrez de PHP vers Craft CMS, le plugiciel Feed Me gère bien la plupart des scénarios d'importation, bien que les migrations complexes puissent bénéficier de commandes console personnalisées qui vous donnent un contrôle total sur le processus.

L'effort en vaut la peine avec un système de gestion de contenu que votre équipe appréciera vraiment utiliser, bâti sur les standards PHP actuels avec des années de support devant vous.

Nous recommandons d'approcher ces migrations par phases, en exécutant des importations tests tôt et souvent. Bien définir le modèle de contenu avant d'importer économise beaucoup de retravail.

Si vous planifiez une migration d'un site PHP vieillissant vers Craft CMS, nous pouvons vous aider à évaluer l'ampleur du projet et bâtir un plan de migration qui tient compte de vos structures de données spécifiques et exigences d'URL. Nos services de migration de sites web couvrent tout, de l'audit initial au lancement final. Contactez-nous pour discuter de votre projet.