Migration TYPO3 : Guide complet étape par étape

J'ai participé à suffisamment de migrations TYPO3 pour savoir que la différence entre une transition en douceur et un cauchemar de six mois dépend de la préparation. TYPO3 est un CMS puissant — il existe depuis 1998 et alimente certains sites d'entreprise extrêmement complexes, notamment dans la région DACH. Mais quand vient le moment de migrer, qu'il s'agisse d'une mise à niveau entre les versions majeures de TYPO3 ou d'un passage à une plateforme complètement différente, le processus peut virer au cauchemar très rapidement si vous n'avez pas de plan.

Ceci est la checklist que j'aurais aimé recevoir avant ma première migration TYPO3. Ce n'est pas théorique. Chaque élément ici existe parce que j'ai vu ce qui se passe quand on le saute.

Table des matières

TYPO3 Migration Checklist: A Developer's Step-by-Step Guide

Évaluer votre installation TYPO3 actuelle

Avant de toucher à quoi que ce soit, vous devez comprendre exactement ce avec quoi vous travaillez. Cela semble évident. Ce ne l'est pas. J'ai participé à des projets où l'équipe ne savait même pas quelle version de TYPO3 elle exécutait en production.

Audit des versions et de l'environnement

Commencez ici :

# Vérifier votre version TYPO3
php typo3/sysext/core/bin/typo3 --version

# Ou vérifier via le backend : Help > About TYPO3

Documentez les éléments suivants :

  • Version TYPO3 (majeure et mineure — par exemple, TYPO3 v11.5.38 LTS)
  • Version PHP exécutée sur le serveur
  • Type et version de base de données (MySQL, MariaDB, PostgreSQL)
  • Serveur web (Apache, Nginx)
  • Installation basée sur Composer ou classique — cela a une énorme importance
  • Nombre de sites/domaines dans l'installation (les configurations multi-sites ajoutent de la complexité)
  • Nombre total de pages et d'éléments de contenu dans l'arborescence de pages

Mappage des utilisateurs et permissions

Le système de permissions des groupes et utilisateurs backend de TYPO3 est notoirement granulaire. Exportez vos tables be_users et be_groups et documentez :

  • Combien d'utilisateurs backend existent
  • Quelles permissions personnalisées sont configurées
  • Quels utilisateurs ont un accès administrateur
  • Tous les remplacements TSconfig personnalisés

Si vous migrez vers un CMS différent, vous devrez mapper ces rôles au modèle de permissions du nouveau système. Si vous effectuez une mise à niveau des versions TYPO3, certaines configurations de permissions peuvent avoir besoin de mises à jour.

Complexité des TypoScript et de la configuration

Effectuez un audit rapide de votre configuration TypoScript :

# Comptez vos fichiers TypoScript
find . -name '*.typoscript' -o -name '*.ts' | wc -l

# Vérifiez la présence de setup.txt et constants.txt (format hérité)
find . -name 'setup.txt' -o -name 'constants.txt' | wc -l

Si vous avez des centaines de fichiers TypoScript avec des configurations profondément imbriquées, attendez-vous à ce que la migration prenne plus de temps. J'ai vu des installations TYPO3 avec plus de 10 000 lignes de TypoScript qui ont évolué sur 15 ans. Ce n'est pas un projet de fin de semaine.

Définir votre stratégie de migration

Il existe fondamentalement trois types de migrations TYPO3, et vous devez décider lequel vous faites avant toute autre chose.

Type de migration Quand choisir Complexité Délai typique
Mise à niveau de version TYPO3 (par ex. v10 → v12) Vous voulez rester sur TYPO3 Moyen-Élevé 4-12 semaines
TYPO3 vers CMS headless (par ex. Contentful, Strapi, Sanity) Vous voulez une flexibilité frontale moderne Élevé 8-20 semaines
TYPO3 vers un autre CMS traditionnel (par ex. WordPress, Drupal) Vous voulez un CMS monolithique différent Moyen 6-16 semaines
TYPO3 vers TYPO3 headless (en utilisant EXT:headless) Vous voulez un backend TYPO3 avec un frontend moderne Moyen 6-14 semaines

Mise à niveau au sein de TYPO3

Si vous restez sur TYPO3, le chemin de mise à niveau officiel nécessite de passer par chaque version LTS. Vous ne pouvez pas passer directement de v8 à v12. Eh bien, vous pouvez essayer. Ne le faites pas.

Le chemin recommandé en 2025 :

  • v8 LTS → v9 LTS → v10 LTS → v11 LTS → v12 LTS → v13 LTS

TYPO3 v13 LTS a été lancé fin 2024 et est la version actuelle avec support à long terme. TYPO3 v12 LTS recevra les mises à jour de sécurité jusqu'en avril 2026 via le programme Extended Long Term Support (ELTS).

Migration loin de TYPO3

Si vous passez à une architecture headless — et honnêtement, cela a beaucoup de sens pour de nombreuses équipes — vous voudrez évaluer vos options de framework frontend. Nous avons effectué un travail approfondi avec Next.js et Astro comme couches frontend associées à des plateformes CMS headless.

La question clé est : votre modèle de contenu justifie-t-il la complexité de TYPO3 ? Si vous exécutez un site marketing avec 200 pages, TYPO3 est probablement excessif. Si vous exécutez un portail d'entreprise multi-langue complexe avec des workflows complexes, le travail de modélisation de contenu lors de la migration sera significatif, quel que soit l'endroit où vous allez.

Audit du contenu et mappage des données

C'est là que les migrations réussissent ou échouent. Le contenu.

Export et analyse de base de données

TYPO3 stocke le contenu principalement dans ces tables :

  • pages — la structure de l'arborescence de pages
  • tt_content — éléments de contenu
  • sys_file et sys_file_reference — ressources médias (FAL)
  • sys_category — catégories
  • tx_news_domain_model_news — si vous utilisez l'extension news

Exportez votre contenu et obtenez des chiffres réels :

-- Compter les pages par type
SELECT doktype, COUNT(*) as count 
FROM pages 
WHERE deleted = 0 
GROUP BY doktype;

-- Compter les éléments de contenu par type
SELECT CType, COUNT(*) as count 
FROM tt_content 
WHERE deleted = 0 AND hidden = 0 
GROUP BY CType 
ORDER BY count DESC;

-- Compter les références de fichiers
SELECT COUNT(*) FROM sys_file WHERE missing = 0;

Mappage des types de contenu

Créez une feuille de calcul qui mappe chaque type de contenu TYPO3 (CType) à son équivalent dans le système cible. Les types de contenu TYPO3 courants que vous rencontrerez :

  • text, textmedia, textpic — contenu textuel standard
  • image — galeries d'images
  • table — tableaux de données
  • bullets — listes
  • uploads — listes de fichiers
  • html — HTML brut (toujours amusant lors de la migration)
  • list — contenu de plugin (c'est là que ça devient compliqué)
  • Types de contenu personnalisés à partir d'extensions

Le CType list est le délicat. Il représente le contenu du plugin — listes de news, formulaires, fonctionnalité personnalisée — et chacun nécessite une attention individuelle.

Contenu multilingue

TYPO3 gère les traductions via le mode connecté (où les traductions sont liées à un enregistrement en langue par défaut) ou le mode libre. Vérifiez quelle approche votre site utilise :

-- Vérifier la configuration de traduction
SELECT sys_language_uid, COUNT(*) 
FROM pages 
WHERE deleted = 0 
GROUP BY sys_language_uid;

Si vous avez 8 langues avec des traductions en mode connecté, votre mappage de données de migration vient de devenir 8 fois plus complexe. Planifiez en conséquence.

TYPO3 Migration Checklist: A Developer's Step-by-Step Guide - architecture

Préparation de l'infrastructure technique

Configuration requise du serveur

Si vous effectuez une mise à niveau vers TYPO3 v13, voici les exigences minimales en 2025 :

  • PHP 8.2 ou supérieur (8.3 recommandé)
  • MySQL 8.0+ ou MariaDB 10.4+ ou PostgreSQL 12+
  • Limite de mémoire PHP de 256 Mo minimum (512 Mo recommandé)
  • Composer 2.7+

Environnement de préproduction

Ne — et je ne peux pas assez le souligner — ne lancez jamais une migration directement en production. Mettez en place :

  1. Un environnement de préproduction qui reflète la production
  2. Une copie de base de données séparée
  3. Des configurations PHP et serveur identiques
  4. Accès au stockage de fichiers (ou une copie de fileadmin)
# Cloner votre base de données en préproduction
mysqldump -u root -p production_db | mysql -u root -p staging_db

# Rsync fileadmin
rsync -avz production:/var/www/html/fileadmin/ staging:/var/www/html/fileadmin/

Stratégie de sauvegarde

Avant de commencer tout travail de migration :

  • Dump de base de données complète avec horodatages
  • Sauvegarde complète du système de fichiers incluant fileadmin, typo3conf et tous les répertoires d'extensions personnalisées
  • Documentez vos paramètres LocalConfiguration.php et AdditionalConfiguration.php
  • Exportez vos modèles TypoScript

Stockez ces sauvegardes quelque part complètement à l'écart de l'environnement de migration. Je conserve au moins trois copies.

Inventaire des extensions et intégrations

Les extensions TYPO3 sont probablement la plus grande source de maux de tête lors de la migration. Voici comment les gérer.

Lister toutes les extensions installées

# Installation basée sur Composer
composer show | grep typo3

# Ou vérifier le PackageStates.php
cat typo3conf/PackageStates.php

Catégoriser chaque extension

Pour chaque extension, déterminez :

Catégorie Action requise Exemple
Extension système du noyau Généralement traitée par l'assistant de mise à niveau fluid_styled_content, form
Extension TER maintenue Vérifier la compatibilité avec la version cible news, powermail, solr
Extension TER abandonnée Trouver un remplacement ou une solution personnalisée Diverses
Extension de site personnalisée Nécessite une migration/réécriture manuelle Votre site_package
Extension commerciale Contacter le fournisseur pour le chemin de migration in2publish, diverses

Chemins de migration d'extensions courants

Certaines extensions que je vois dans presque chaque migration TYPO3 :

  • EXT:news (Georg Ringer) — Vérifier la compatibilité des versions ; v11+ fonctionne avec TYPO3 v12/v13
  • EXT:powermail — Extension de formulaire populaire ; les alternatives incluent EXT:form (noyau)
  • EXT:realurl — Obsolète depuis TYPO3 v9 ; remplacé par le routage du noyau
  • EXT:tt_address — Généralement une mise à niveau simple
  • EXT:gridelements ou EXT:flux — Ces extensions de mise en page causent le plus de douleur lors des mises à niveau. Si vous migrez loin de TYPO3, attendez-vous à un travail important pour extraire le contenu des structures de grille.

Plan de préservation SEO

Sauter cette section a coûté à certaines entreprises des millions en trafic organique. Ne soyez pas cette équipe.

Mappage d'URL

  1. Analysez l'ensemble de votre site actuel avec Screaming Frog, Sitebulb ou Ahrefs
  2. Exportez tous les URL (attendez-vous à des milliers pour les grands sites TYPO3)
  3. Créez un document de mappage d'URL 1:1 complet
  4. Identifiez vos 100 meilleures pages par trafic organique (consultez Google Search Console)
  5. Priorisez la précision des redirections pour les pages à fort trafic

Implémentation des redirections

# Exemple de redirections .htaccess
RedirectPermanent /old-typo3-path/page.html /new-path/page
RedirectPermanent /index.php?id=123 /about-us

Pour les redirections à grande échelle, utilisez une solution de gestion des redirections plutôt que de bourrer des milliers de règles dans .htaccess. Si vous passez à une pile moderne, la plupart des frameworks et plateformes d'hébergement (Vercel, Netlify) ont des fichiers de configuration de redirection.

Migration des métadonnées

TYPO3 stocke les métadonnées SEO dans la table pages (depuis que EXT:seo est devenu une extension principale en v9) :

  • seo_title
  • og_title, og_description, og_image
  • twitter_title, twitter_description, twitter_image
  • canonical_link
  • no_index, no_follow

Assurez-vous d'exporter et de mapper tout cela. Perdre vos méta-descriptions sur 500 pages est un désastre évitable.

Phase d'exécution de la migration

Pour les mises à niveau de version TYPO3

Suivez cette séquence pour chaque étape de version :

  1. Mettre à jour les dépendances Composer vers la prochaine version LTS
  2. Exécuter l'Assistant de mise à niveau dans l'outil d'installation (Admin Tools > Upgrade)
  3. Exécuter l'analyseur de base de données pour mettre à jour le schéma
  4. Vérifier le journal de dépréciation pour les problèmes
  5. Mettre à jour les extensions vers des versions compatibles
  6. Corriger TypoScript les dépréciations et les changements radicaux
  7. Tester complètement avant de passer à l'étape de version suivante
# Mettre à jour le noyau TYPO3 via Composer
composer require typo3/cms-core:^13.4 typo3/cms-backend:^13.4 \
  typo3/cms-frontend:^13.4 --with-all-dependencies

# Exécuter les assistants de mise à niveau via CLI
php typo3/sysext/core/bin/typo3 upgrade:run

# Mise à jour du schéma de base de données
php typo3/sysext/core/bin/typo3 database:updateschema

Pour les migrations de plateforme

Si vous migrez vers une architecture CMS headless, la phase d'exécution ressemble à ceci :

  1. Configurer le nouveau CMS et configurer les modèles de contenu
  2. Créer des scripts de migration pour transformer les données TYPO3
  3. Migrer le contenu par lots — commencez par les types de contenu les plus simples
  4. Gérer les ressources médias — télécharger depuis fileadmin et charger vers le nouveau stockage d'assets
  5. Construire le frontend avec votre framework choisi
  6. Implémenter les redirections avant le lancement
  7. Changement DNS et surveillance

Pour la transformation réelle des données, j'écris généralement des scripts Python ou Node.js qui lisent à partir de la base de données TYPO3 et poussent le contenu vers le nouveau CMS via l'API :

import mysql.connector
import requests

# Connexion à la base de données TYPO3
db = mysql.connector.connect(
    host="localhost",
    user="typo3",
    password="password",
    database="typo3_db"
)

cursor = db.cursor(dictionary=True)
cursor.execute("""
    SELECT uid, title, description, slug, 
           seo_title, og_description 
    FROM pages 
    WHERE deleted = 0 AND hidden = 0 
    AND sys_language_uid = 0
    ORDER BY sorting
""")

for page in cursor.fetchall():
    # Transformer et pousser vers le nouveau CMS
    payload = {
        "title": page["title"],
        "slug": page["slug"],
        "seoTitle": page["seo_title"] or page["title"],
        "description": page["og_description"] or page["description"]
    }
    # POST vers votre nouvelle API CMS
    response = requests.post(
        "https://api.new-cms.com/content",
        json=payload,
        headers={"Authorization": "Bearer YOUR_TOKEN"}
    )
    print(f"Migrated page {page['uid']}: {response.status_code}")

Tests et assurance qualité

Checklist de test automatisé

  • Toutes les pages retournent les codes de statut 200
  • Aucun lien interne cassé
  • Toutes les images se chargent correctement
  • Les formulaires se soumettent avec succès
  • La fonctionnalité de recherche fonctionne
  • La commutation multilingue fonctionne
  • Les redirections à partir des anciennes URL fonctionnent correctement
  • Les URL canoniques sont correctes
  • Les sitemaps XML sont valides et accessibles
  • robots.txt est correctement configuré
  • Les certificats SSL sont valides
  • Les temps de chargement des pages sont acceptables (moins de 3 secondes)

Test de régression visuelle

Utilisez des outils comme Percy, BackstopJS ou Playwright pour la comparaison visuelle :

# Exemple BackstopJS
npx backstop init
# Configurer les scénarios dans backstop.json
npx backstop reference  # Capturer le site actuel
npx backstop test       # Comparer après la migration

Points de repère de performance

Mesurez avant et après. Votre migration devrait idéalement améliorer les performances, pas les dégrader.

Métrique Cible pré-migration Cible post-migration
TTFB < 800 ms < 200 ms
LCP < 2.5 s < 1.5 s
CLS < 0.1 < 0.05
FID/INP < 200 ms < 100 ms
PageSpeed Score 50-70 90+

Si vous passez du rendu côté serveur TYPO3 à un frontend statique ou rendu à la périphérie, vous devriez voir des améliorations dramatiques dans ces nombres.

Surveillance post-migration

La migration n'est pas terminée quand vous basculez le DNS. Surveillez ceci pendant au moins 30 jours :

  1. Google Search Console — Regardez les erreurs d'analyse, les problèmes de couverture et les problèmes d'indexation. Attendez-vous à une certaine fluctuation les deux premières semaines.
  2. Analytics — Comparez les modèles de trafic semaine après semaine avec les données de base pré-migration.
  3. Erreurs 404 — Configurez la journalisation des erreurs 404 et ajoutez des redirections pour tous les URL que vous avez manqués.
  4. Core Web Vitals — Surveillez les données utilisateurs réels via CrUX ou votre plateforme analytics.
  5. Journaux du serveur — Regardez les modèles d'erreur inhabituels.

Définissez des alertes pour les baisses de trafic dépassant 20% sur n'importe quelle page qui était auparavant dans vos 50 premières.

Pièges courants des migrations TYPO3

Ce sont les erreurs que j'ai vues (et parfois commises) lors de douzaines de migrations :

1. Ignorer les enregistrements supprimés en douceur. TYPO3 utilise les drapeaux deleted=1 plutôt que de réellement supprimer les enregistrements. Vos scripts de migration doivent les filtrer, sinon vous importerez des milliers d'enregistrements qui ont été supprimés il y a des années.

2. Oublier les espaces de travail. Si le site utilise les espaces de travail TYPO3 pour les flux de travail éditoriaux, vous pourriez avoir du contenu brouillon mélangé à votre export. Filtrez toujours pour t3ver_wsid = 0 pour obtenir uniquement le contenu en direct.

3. Sous-estimer le contenu RTE. La sortie de l'éditeur de texte enrichi de TYPO3 peut contenir des balises personnalisées, des balises <link> avec syntaxe spécifique à TYPO3 et des URI t3://. Vous devez analyser et convertir tout cela.

4. Casser les références de fichiers. La couche d'abstraction de fichiers (FAL) de TYPO3 utilise sys_file_reference pour connecter les fichiers au contenu. Ce n'est pas un simple « champ image sur l'enregistrement de contenu » — c'est une table de relations. Vos scripts de migration doivent suivre ces références.

5. Ne pas tester avec des volumes de contenu réels. Votre script de migration fonctionne très bien avec 10 pages de test. Il échoue catastrophiquement avec 15 000 pages et 50 000 éléments de contenu. Testez toujours à l'échelle.

Si vous planifiez une migration et voulez éviter ces pièges, nous avons guidé plusieurs équipes d'entreprise à travers des migrations TYPO3 — n'hésitez pas à nous contacter et nous pouvons discuter de votre situation spécifique.

FAQ

Combien de temps prend généralement une migration TYPO3 ? Cela dépend beaucoup de la complexité de votre installation. Une mise à niveau simple de TYPO3 v11 à v13 pour un site monolingue avec des extensions standard pourrait prendre 4 à 6 semaines. Une migration de plateforme complète d'un site TYPO3 d'entreprise multilingue avec des extensions personnalisées peut facilement prendre 3 à 6 mois. Seule la phase d'audit du contenu peut prendre 2 à 4 semaines pour les grands sites.

Puis-je ignorer les versions TYPO3 LTS lors d'une mise à niveau ? Techniquement, vous ne devriez pas. La recommandation officielle est de mettre à niveau via chaque version LTS séquentiellement (v8 → v9 → v10 → v11 → v12 → v13) car chaque version inclut des assistants de mise à niveau qui gèrent les migrations de données pour cette étape spécifique. Ignorer les versions signifie que ces migrations de données ne s'exécutent pas et vous vous retrouverez avec des données corrompues ou orphelines. Certaines agences prétendent qu'elles peuvent faire des mises à niveau avec saut de version, mais j'ai vu cela causer des problèmes de données subtils qui font surface des mois plus tard.

Dois-je migrer de TYPO3 vers WordPress ? Cela dépend de vos besoins. WordPress gère bien les sites marketing simples, mais si vous avez choisi TYPO3 à l'origine en raison d'exigences multilingues complexes, de permissions granulaires ou de flux de travail d'entreprise, WordPress pourrait être un pas en arrière. Considérez si un CMS headless associé à un framework frontend moderne pourrait être un meilleur choix. Nous avons écrit sur les approches de développement CMS headless qui ont souvent plus de sens pour les équipes quittant les plateformes CMS d'entreprise.

Que se passe-t-il pour mes classements SEO lors d'une migration TYPO3 ? Attendez-vous à une certaine fluctuation du classement pendant 2 à 6 semaines, même avec des redirections parfaites. Google a besoin de temps pour réanalyser et réindexer votre contenu. Pour minimiser l'impact : implémentez des redirections 301 pour chaque URL, gardez votre structure de contenu aussi proche que possible de l'original, soumettez immédiatement les sitemaps mis à jour et utilisez l'outil Changement d'adresse dans Google Search Console si vous changez de domaine. Les sites qui gèrent correctement les redirections se rétablissent généralement en 4 à 8 semaines.

Comment gère-t-on les extensions TYPO3 qui n'existent pas sur la plateforme cible ? Tout d'abord, déterminez ce que l'extension fait réellement. De nombreuses extensions TYPO3 fournissent des fonctionnalités intégrées aux plateformes modernes (comme les générateurs de formulaires, les outils SEO ou la gestion des redirections). Pour la fonctionnalité personnalisée, vous devrez soit trouver un plugin/service équivalent, soit construire des fonctionnalités personnalisées. Créez une feuille de calcul listant chaque extension, son objectif et la stratégie de remplacement.

Vaut-il la peine de passer à TYPO3 headless au lieu de migrer entièrement ? L'extension TYPO3 headless (EXT:headless) est une option légitime si votre équipe est à l'aise avec le backend TYPO3 mais souhaite un frontend moderne. Elle expose le contenu TYPO3 sous forme d'API JSON, vous permettant de créer votre frontend avec Next.js, Nuxt ou Astro. Cette approche préserve votre structure de contenu existante et vos flux de travail éditoriaux tout en modernisant la couche de présentation. C'est un bon juste milieu, bien qu'il signifie que vous maintenez toujours un backend TYPO3.

Quel est le coût d'une migration TYPO3 en 2025 ? Chiffres approximatifs : une mise à niveau de version TYPO3 pour un site de taille moyenne coûte 15 000 à 50 000 dollars. Une migration de plateforme complète vers une architecture headless va de 40 000 à 150 000 dollars ou plus selon le volume de contenu, le nombre de langues, la fonctionnalité personnalisée et la complexité de l'intégration. Ce ne sont pas de petits nombres, mais comparez-les au coût du maintien d'une installation CMS obsolète et non sécurisée. Vous pouvez consulter notre page de tarification pour plus de détails sur la façon dont nous structurons ces projets.

Dois-je reconstruire mes modèles à partir de zéro ? Pour les mises à niveau de version TYPO3, généralement pas entièrement — mais vous devrez mettre à jour les modèles Fluid pour gérer les ViewHelpers dépréciés et les nouvelles API. Pour les migrations de plateforme, oui, vous construisez un nouveau frontend. La bonne nouvelle est que les frameworks modernes comme Next.js et Astro rendent beaucoup plus rapide la construction de frontends performants que ne l'était l'époque Fluid/TypoScript. Votre conception peut rester la même ; l'implémentation change simplement.