Symfony UX 3.0.0 : plan d'action en 5 étapes pour migrer sans régression

Source originale : Symfony UX 3.0.0 Released — Symfony Blog, avril 2026

Symfony UX 3.0.0 est sorti le 13 avril 2026 sous la plume de Fabien Potencier. Il s'agit d'une nouvelle version majeure qui suit le processus de release habituel de Symfony : suppression de toutes les fonctionnalités dépréciées du cycle 2.x et élévation des prérequis minimaux à PHP 8.4 et Symfony 7.4.

Bonne nouvelle : si votre application tourne sans notice de dépréciation sur Symfony UX 2.x, la migration devrait être relativement indolore. Mais « relativement » ne veut pas dire « sans préparation ». Voici un plan d'action concret en 5 étapes.

Ce qui disparaît dans cette version majeure

Quatre packages ont été retirés de l'écosystème Symfony UX car ils n'offraient qu'une fine couche PHP autour de bibliothèques JavaScript tierces, sans véritable valeur ajoutée côté intégration :

Pour chaque package concerné, le fichier UPGRADE-3.0.md du dépôt officiel détaille les étapes de migration.

Plan d'action en 5 étapes

Étape 1 — Passer le détecteur de dépréciations avant toute chose

Avant même de toucher à votre composer.json, activez le mode strict des dépréciations et parcourez votre application entière :

# Lancer les tests avec le bridge de dépréciations Symfony
ARGV="" SYMFONY_DEPRECATIONS_HELPER=strict php bin/phpunit

Chaque notice non résolue est un obstacle potentiel à la migration. Traitez-les une par une. C'est le filet de sécurité le plus efficace avant d'entamer la montée de version.

Étape 2 — Mettre à jour votre environnement Docker et CI/CD

Symfony UX 3.0 exige PHP 8.4 au minimum. Cela implique de mettre à jour :

• Votre image Docker de base (FROM php:8.4-fpm-alpine par exemple)
• La matrice de versions dans votre pipeline CI (GitHub Actions, GitLab CI…)
• Les éventuelles directives platform dans votre composer.json

"config": {
  "platform": {
    "php": "8.4"
  }
}

Vérifiez également la compatibilité de toutes vos dépendances tierces avec PHP 8.4 via composer outdated et les changelogs associés.

Étape 3 — Remplacer les packages JS redondants

C'est l'étape la plus visible côté front-end. Pour chaque package supprimé que vous utilisez :

Swup et Typed.js — installation directe via importmap :

php bin/console importmap:require swup
php bin/console importmap:require typed.js

Puis créez un contrôleur Stimulus minimal pour encapsuler le comportement de Typed :

// assets/controllers/typed_controller.js
import { Controller } from '@hotwired/stimulus';
import Typed from 'typed.js';

export default class extends Controller {
  static values = { strings: Array, speed: { type: Number, default: 50 } }

  connect() {
    this.typed = new Typed(this.element, {
      strings: this.stringsValue,
      typeSpeed: this.speedValue,
    });
  }

  disconnect() {
    this.typed.destroy();
  }
}

LazyImage — remplacez simplement vos appels au composant par l'attribut HTML natif :

<!-- Avant -->
<twig:UX:LazyImage src="image.jpg" />

<!-- Après -->
<img src="image.jpg" loading="lazy" alt="..." />

Cette approche native est aujourd'hui supportée par tous les navigateurs modernes et supprime une dépendance inutile.

Étape 4 — Vérifier la disponibilité de PHP 8.4 sur votre hébergement

Si vous hébergez vous-même (serveur dédié, VPS), la mise à jour PHP est sous votre contrôle. Sur un hébergement mutualisé ou une offre cloud managée, c'est une autre histoire.

Points de contrôle :

• PHP 8.4 disponible sur l'interface d'administration de votre hébergeur ?
• Extensions requises toujours présentes (intl, mbstring, opcache…) ?
• Date de disponibilité si la version n'est pas encore en production chez votre provider ?

Si PHP 8.4 n'est pas encore disponible, bloquez la migration Symfony UX 3.0 dans votre composer.json le temps que l'hébergeur se mette à jour, et continuez sur la branche 2.x.

Étape 5 — En profiter pour réduire la dette technique front-end

Cette migration est une opportunité pour faire le ménage dans votre stack JavaScript. Quelques quick-wins :

• Auditer vos dépendances npm : npm audit et suppression des packages inutilisés
• Consolider vos contrôleurs Stimulus : regrouper les comportements similaires
• Évaluer UX Toolkit : le nouveau système de composants réutilisables de Symfony UX mérite une exploration, notamment pour remplacer des patterns maison comme TogglePassword
• Mettre à jour Asset Mapper si vous n'utilisez pas encore ce système introduit avec Symfony 6.3

Conclusion

Symfony UX 3.0.0 est une version majeure raisonnée : elle fait le ménage, élève les standards (PHP 8.4, Symfony 7.4) et pousse les développeurs vers des solutions natives ou plus maintenables. La suppression des quatre packages ne doit pas être vécue comme une contrainte, mais comme une incitation à écrire moins de code de glue et à mieux exploiter les capacités modernes du navigateur et de Stimulus.

Suivez les 5 étapes dans l'ordre — dépréciations, environnement, JS, hébergement, dette technique — et votre migration se passera sans mauvaise surprise.