Stratégie de montée vers Symfony 7.4 LTS

Kohinos tourne actuellement sur Symfony 7.2.* et cible explicitement Symfony 7.4 LTS. Cette page documente le chemin d'upgrade : pourquoi 7.4, pré-requis Doctrine/DBAL, étapes versionnées, points d'attention par composant (Security, Sonata Admin, Form, API Platform), procédure de vérification et rollback. La règle cardinale : jamais en période de cycle SEPA/SSA actif, jamais de saut de minor non testé, jamais de DBAL 4.x. La montée est étalée sur plusieurs semaines, minor par minor, en respectant strictement les priorités projet (intégrité financière > souveraineté > sobriété > maintenabilité > performance).

1. Pourquoi 7.4 LTS

Symfony 7.4 est la version LTS du cycle 7.x. Pour une infrastructure monétaire communautaire auto-hébergée, c'est le bon choix : on minimise la fréquence des upgrades intrusives, on capitalise sur du long terme stabilisé, et on s'aligne avec la roadmap PHP 8.4.

• 3 ans de bugfixes + 4 ans de correctifs de sécurité à compter de la sortie de la LTS — couvre largement la prochaine fenêtre de stabilité Kohinos.
• PHP 8.4 stabilisé : property hooks, asymmetric visibility, lazy objects compatibles avec Doctrine ORM 2.x.
• Sobriété : moins de mises à jour majeures imposées dans les 2-3 ans à venir, ce qui colle à la priorité n°3 du projet (low-tech, Raspberry Pi friendly).
• Sécurité : la branche LTS reçoit les CVE patchs en priorité, alignée avec la politique de souveraineté (priorité n°2).
• Écosystème : Sonata Admin 4.x, API Platform 3.x et Doctrine ORM 2.14+ sont compatibles Symfony 7.4.

2. État actuel vs cible

Inventaire des composants critiques pour Kohinos (gestion eMLc, mandats SEPA, redistribution SSA, notifications mailer). Les versions actuelles sont celles déclarées dans composer.json.

3. Pré-requis

• PHP ≥ 8.2 — Kohinos tourne déjà en 8.4 en dev, pré-requis satisfait sans action.
• Doctrine ORM ≥ 2.14, < 3 — la cible reste 2.x pour ce cycle d'upgrade. Le saut ORM 3 est un chantier indépendant qui exigera la réécriture des EntityManager mocks dans les tests.
• DBAL 3.x verrouillé — DBAL 4 modifie Schema::createTable(), supprime getName() sur les plateformes et change la signature des drivers. Cela impacterait directement App\Utils\MigrationFactoryDecorator et les guards de plateforme dans les migrations.
• Composer ≥ 2.6 pour la résolution moderne des conflits transitifs.
• Environnement de test fonctionnel : SECURE_SCHEME=http dans .env.test, SQLite in-memory configurable, app:init-test-database --env=test --purge opérationnel.
• PHPStan baseline propre avant upgrade — sinon les nouvelles erreurs SF 7.4 seront noyées.

4. Plan d'upgrade par étapes

La montée se fait minor par minor, jamais en saut direct 7.2 → 7.4. Chaque palier est validé indépendamment avant le suivant. Aucune étape n'est optionnelle.

flowchart LR
  A["1. Audit deprecations
(SF 7.2 actuel)"] --> B["2. Upgrade composer.json
vers 7.3.*"]
  B --> C["3. Migration micro-version
7.2 → 7.3"]
  C --> D["4. Tests ciblés
(jamais phpunit complet)"]
  D --> E["5. Validation manuelle
Sonata Admin + Form"]
  E --> F["6. Tag git intermédiaire
pre-sf74-upgrade"]
  F --> G["7. Upgrade composer.json
vers 7.4.*"]
  G --> H["8. Migration micro-version
7.3 → 7.4"]
  H --> I["9. Tests ciblés + routes
(financier, SEPA, SSA)"]
  I --> J["10. Merge sur master"]
    

Détail des étapes

1. Audit deprecations : lancer le scan deprecations sur la base actuelle 7.2, traiter toutes les deprecations avant d'incrémenter la version.
2. Upgrade composer.json : passer symfony/* à 7.3.*, garder doctrine/dbal en ^3.6.
3. composer update symfony/* --with-dependencies — relire les changements de composer.lock ligne par ligne.
4. Tests ciblés sur les composants modifiés. Jamais la suite complète.
5. Validation manuelle Sonata Admin : créer/modifier un mandat SEPA, une transaction, un fonds SSA via le BackOffice.
6. Tag intermédiaire git tag pre-sf74-upgrade avant de basculer 7.3 → 7.4.
7. Répéter pour 7.3 → 7.4 avec la même rigueur.

5. Points d'attention par composant

5.1 Security

5.2 Sonata Admin 4.x

Sonata Admin 4 reste compatible Symfony 7.4 mais conserve ses breaking changes 4.x déjà présents. Rappels critiques à ne pas régresser pendant l'upgrade :

// ❌ Sonata Admin 3.x — n'existe plus en 4.x
$this->trans('label.key', [], 'admin');

// ✅ Sonata Admin 4.x
$this->getTranslator()->trans(
    'label.key',
    [],
    $this->getTranslationDomain()
);

• DatagridMapper est final — impossible à mocker. Tests admin → markTestIncomplete() ou integration test sur kernel réel.
• ProxyQueryInterface n'expose plus getRootAlias() ni andWhere() directement : accès via __call sur le QueryBuilder interne.
• Mocks d'admins : getMockBuilder(X::class)->disableOriginalConstructor()->onlyMethods([...]).
• Vérifier les overrides de configureFormFields() — les types de champs Sonata peuvent voir des deprecations renforcées en 7.4.

5.3 Form

• Les types Money custom (MoneyType + transformer BigDecimal) doivent être audités : getData() renvoie selon les versions un string, float ou objet. Jamais comparer en ===.
• Les CollectionType pour mandats SEPA et items SSA peuvent voir leur comportement allow_add/by_reference évoluer.
• Les ChoiceType avec enums PHP 8.1+ : vérifier que choice_value renvoie bien le value du backed enum.
• Les form events (PRE_SUBMIT, POST_SET_DATA) restent stables mais les contraintes d'ordre peuvent changer.

5.4 Doctrine

• Doctrine ORM reste en 2.14+. Pas de migration 2 → 3 dans ce cycle.
• Le mapping type: attribute reste obligatoire — pas d'annotations docblock.
• Vérifier que doctrine/doctrine-bundle reste compatible Symfony 7.4 sans imposer DBAL 4.
• Tester doctrine:schema:validate après chaque upgrade — doit rester sans warning.

5.5 API Platform 3.x

• API Platform 3.x déclare une compatibilité Symfony 6.4 / 7.x — vérifier explicitement la borne supérieure dans composer.json du paquet installé.
• Les ApiResource attributes restent inchangés.
• Les serializers custom (notamment pour SepaMandate avec IBAN masqué) doivent être re-testés.
• Surveiller la doc OpenAPI générée : un changement de structure peut casser un client externe.

6. Procédure de vérification

# 1. Mise à jour des dépendances
composer update symfony/* --with-dependencies

# 2. Vérifier le schéma Doctrine — doit rester clean
php bin/console doctrine:schema:validate

# 3. Analyse statique — pas de nouvelle suppression PHPStan
vendor/bin/phpstan analyze src tests

# 4. Tests ciblés FINANCIER / SEPA / SSA
#    Jamais `vendor/bin/phpunit` complet — bloqué par settings.json
vendor/bin/phpunit --testsuite=sepa
vendor/bin/phpunit --testsuite=ssa
vendor/bin/phpunit tests/Service/Flux/
vendor/bin/phpunit tests/Service/Account/

# 5. Détection des 500 multi-rôles
#    Prérequis : symfony server:start + pip3 install requests
python3 scripts/test-routes.py --only-errors
python3 scripts/test-routes.py --role super_admin --only-errors
python3 scripts/test-routes.py --role tresorier --only-errors

# 6. Lints Symfony
php bin/console lint:yaml config
php bin/console lint:twig templates

# 7. Container — vérifier qu'il compile sans warning
php bin/console cache:clear --env=prod
php bin/console debug:container --deprecations

Critère de passage : tous les points ci-dessus doivent être verts. Une seule régression bloque le palier — on revient au tag git précédent.

7. Rollback

8. Calendrier proposé

Aucune pression calendaire. La règle est d'étaler la montée pour minimiser le risque sur les flux financiers en cours.

Pour aller plus loin