Migrer vers Sulu 3.0.11 : méthode et vérifications
Préparez une migration vers Sulu 3.0.11 : PHPCR, Doctrine, templates, administration, validation des contenus et retour arrière.
Une migration Sulu ne se résume pas à remplacer un numéro dans Composer. Le code peut démarrer alors que les aperçus, les langues ou les contenus publiés ne correspondent plus à ce qui est attendu. Pour la préparer correctement, il faut séparer les dépendances, la structure de stockage, les données éditoriales et la validation fonctionnelle.
Versions vérifiées le . La dernière version stable vérifiée est Sulu 3.0.11, publiée le 29 octobre 2026. Le skeleton 3.0.11 déclare PHP 8.2 ou supérieur dans la branche 8.x et Symfony 7.4. La cible de cet article est Sulu 3.0.11 ; elle n’impose pas de migrer simultanément vers Symfony 8.
Références de version : release Sulu 3.0.11 et dépendances du skeleton 3.0.11. Vérifiez à nouveau la dernière version lorsque vous planifiez votre propre intervention.
Identifier le chemin qui concerne votre projet
| Version de départ | Travail principal |
|---|---|
| Sulu 3.0.x | Lire les notes intermédiaires, mettre à jour les dépendances, appliquer les migrations requises et tester. |
| Sulu 2.6 | Préparer la version 2.6, adapter le projet à 3.0 puis convertir le contenu PHPCR. |
| Une branche antérieure à 2.6 | Prévoir d’abord les mises à niveau intermédiaires documentées, avant le passage majeur. |
Commencez par un état mesuré, dans l’environnement PHP utilisé par l’application :
composer show sulu/sulu
composer show symfony/framework-bundle
composer check-platform-reqs
composer prohibits sulu/sulu 3.0.11
La dernière commande aide à identifier une contrainte bloquante ; elle ne propose pas à elle seule une solution compatible. Relevez aussi les bundles tiers, les services remplacés, les champs personnalisés et la chaîne de compilation de l’administration. Un Composer qui résout les dépendances ne garantit pas la compatibilité de ces extensions.
Préparer une restauration, puis une répétition
Avant de modifier les données, restaurez une sauvegarde dans un environnement isolé. La sauvegarde doit couvrir la base relationnelle, le stockage PHPCR lorsqu’il existe, les fichiers de médias et les éléments nécessaires au fonctionnement du projet. Un dump SQL n’inclut pas forcément un dépôt Jackrabbit ni des médias placés dans un stockage objet.
Gardez la version précédente de l’application et les réglages utiles à sa restauration. Pendant la répétition, neutralisez les emails et les tâches susceptibles d’agir sur de vrais services. Constituez un état de référence : URL publiques, pages et langues importantes, contenu de quelques brouillons, médias et rôles représentatifs. Comparez les objets fonctionnels ; le nombre de lignes SQL peut changer avec le modèle de stockage.
Depuis Sulu 2.6 : traiter le changement de stockage
Sulu 3 remplace le stockage de contenu PHPCR par des entités Doctrine et des champs JSON. Les dimensions distinguent notamment les langues, les états de publication et les versions. Une page française publiée et son brouillon ne se valident donc pas par une seule ouverture de la page. L’annonce de Sulu 3.0 explique cette évolution.
Dans votre copie de travail encore en 2.6, appliquez les migrations PHPCR et suivez les étapes préparatoires du guide de passage à 3.0. Le nettoyage PHPCR et le traitement de l’ancien ArticleBundle sont des opérations distinctes à lire selon les composants installés. Ne les remplacez pas par une réinitialisation de la base.
php bin/adminconsole phpcr:migrations:migrate
Après adaptation du code et création du schéma cible, le bundle sulu/phpcr-migration-bundle convertit les contenus. Sa configuration doit désigner le bon dépôt PHPCR source et la bonne connexion cible. Installez une version compatible avec votre projet, enregistrez le bundle et vérifiez les options disponibles avant l’exécution :
php bin/adminconsole help sulu:phpcr-migration:migrate
php bin/adminconsole sulu:phpcr-migration:migrate
Ce bloc s’exécute uniquement dans l’environnement préparé, après les étapes précédentes. Relancer l’import peut écraser les contenus déjà migrés : évitez toute édition dans la cible tant que le transfert est en cours. Le README du bundle de migration décrit la configuration et les limites du mode de simulation selon la version installée. Une simulation ne remplace pas une restauration ni un import réellement testé.
Adapter les points de raccordement du projet
Le template XML reste le contrat entre le CMS et Twig. Dans Sulu 3, utilisez le contrôleur de contenu et une vue sans suffixe de fichier :
<!-- Extrait à placer dans un template complet -->
<view>pages/default</view>
<controller>Sulu\Content\UserInterface\Controller\Website\ContentController::indexAction</controller>
La vue HTML correspond à templates/pages/default.html.twig. Vérifiez aussi les contrôleurs que vous avez étendus, pas seulement les chaînes dans les XML. La documentation du rendu Twig donne le contrat du contrôleur actuel.
Contrôlez les champs d’URL, les fonctions Twig de chargement et les services personnalisés dans le guide de version. Pour un lien de page, par exemple, l’usage de sulu_page_load doit indiquer les propriétés nécessaires. Les anciens services PHPCR ne doivent pas rester injectés dans du code conçu pour le nouveau stockage.
Depuis Sulu 3.0.x : mettre à jour sans refaire l’import PHPCR
Un projet déjà converti en 3.0 n’a normalement pas à réimporter le contenu de la version 2.6. Sur une branche et une copie de base, après vérification des contraintes compatibles, une mise à jour ciblée peut commencer ainsi :
composer require sulu/sulu:3.0.11 --with-all-dependencies --no-scripts
composer validate
composer check-platform-reqs
php bin/adminconsole doctrine:migrations:status
--with-all-dependencies peut faire évoluer d’autres paquets : relisez le diff de composer.lock. L’option --no-scripts reporte les scripts Composer, elle ne les rend pas inutiles. Après lecture des notes intermédiaires et préparation des migrations adaptées à votre moteur SQL, exécutez les migrations et les étapes de déploiement prévues par votre projet. Les options sont détaillées dans la référence Composer.
La version 3.0.11 corrige notamment des cas liés à la copie de langues, aux routes et à la restauration depuis la corbeille. Ajoutez ces parcours à votre validation lorsqu’ils sont utilisés. Les notes 3.0.6 à 3.0.10 contiennent aussi des adaptations de schéma, d’administration, de permissions et de références ; sauter directement au dernier numéro ne dispense pas de leur lecture.
Recompiler l’administration comme une dépendance du projet
Le PHP et le JavaScript de l’administration doivent rester compatibles. Comparez assets/admin/package.json avec les chemins et versions attendus par Sulu, puis utilisez la version de Node prévue par cette chaîne de build. Lorsque le manifeste a été adapté et le lockfile mis à jour volontairement, reconstruisez depuis le bon dossier :
cd assets/admin
npm ci
npm run build
Conservez le lockfile. Vérifiez ensuite la médiathèque, l’éditeur et les champs personnalisés dans le navigateur. Le build réussi ne prouve pas qu’un plugin CKEditor d’une ancienne génération est compatible avec le nouveau cœur.
Valider la bascule avec des parcours précis
- Ouvrir les anciennes URL importantes et contrôler les redirections ; vérifier les images, téléchargements, balises canoniques et sitemap.
- Créer puis modifier une page, enregistrer un brouillon, prévisualiser et publier ; vérifier le résultat public et l’invalidation du cache.
- Contrôler chaque langue et les contenus qui ne sont pas encore publiés ; vérifier que la publication ne change pas leur auteur ou leur date sans raison.
- Essayer des comptes aux droits différents, l’authentification et les extensions utilisées, y compris une connexion MCP si elle fait partie du projet.
Pendant la bascule, bloquez temporairement les écritures dans l’ancien site ou définissez un mécanisme de reprise du delta. Déployez le même artefact que celui validé, puis surveillez erreurs, réponses HTTP et parcours éditoriaux. Un retour arrière après de nouvelles écritures demande une stratégie de données ; remettre seulement l’ancienne image PHP ne suffit pas toujours.
Cette procédure est un cadre de préparation, pas une migration exécutée sur votre site en lisant cet article. Les versions et références ont été vérifiées ; les commandes qui modifient ou convertissent les données doivent être répétées sur votre copie avant la production. Pour revoir les bases du couple XML/Twig, consultez le tutoriel Débuter avec Sulu.