Sonata Admin 4.x — patterns Kohinos, breaking changes, sécurité

Sonata Admin 4.x apporte plusieurs breaking changes vis-à-vis de la 3.x (suppression de $this->trans(), DatagridMapper rendu final, ProxyQueryInterface raboté, configuration par attributs PHP). Cette page documente les patterns Kohinos pour écrire ou maintenir un Admin sans retomber dans les pièges détectés pendant la migration SF4 → SF7.

Carte des Admins Kohinos

Tous les Admins du projet héritent de App\Admin\KohinosAdmin (lui-même extends AbstractAdmin), ce qui mutualise translator, security, max-per-page et le rendu du bouton create. Liste non exhaustive :

Admin	Entité	Actions custom notables	Rôle requis (typique)
DonAdmin	Don (STI DonAdherent/DonPrestataire)	create?expediteur_type=…, dropdown create	ROLE_TRESORIER / ROLE_SUPER_ADMIN
AdherentAdmin	Adherent	Batch actions, vue show riche	ROLE_ADMIN_ADHERENT_*
PrestataireAdmin	Prestataire	Batch (validation, mise hors-ligne), routes custom	ROLE_ADMIN_PRESTATAIRE_*
SolidoumeParamAdmin	SolidoumeParameter	Batch + route execute	ROLE_SOLIDOUME
SepaMandateAdmin	SepaMandate	Validation trésorier (workflow), révocation	ROLE_TRESORIER
FluxAdmin / FluxEurosAdmin / FluxSsaAdmin	Flux (STI)	Liste filtrée par type, lecture seule sur les écritures financières	ROLE_TRESORIER
OperationAdmin & dérivés	Operation*	Lecture seule (intégrité comptable)	ROLE_TRESORIER
RecurringMlcSubscriptionRequestAdmin, RecurringPurchaseRequestAdmin, RecurringSsaSubscriptionRequestAdmin	Requêtes SEPA récurrentes	Annulation atomique en cascade du mandat	ROLE_TRESORIER
HelloAssoAdmin	Logs / configurations HelloAsso	Audit des webhooks	ROLE_SUPER_ADMIN
GlobalParameterAdmin	GlobalParameter	Paramètres globaux MLC	ROLE_SUPER_ADMIN
AuditLogAdmin, EmailLogAdmin, ConsentAdmin, GdprRequestAdmin	Traces & RGPD	Lecture seule	ROLE_SUPER_ADMIN

Pool unique sonata.admin ; configuration centralisée dans config/packages/sonata_admin.yaml. Le security handler utilisé est app.security.handler.role (rôles fins), pas le handler ACL par défaut.

Breaking changes Sonata 4.x

Pattern de mocks pour les tests

Le constructeur d'AbstractAdmin attend un code, une classe et un baseControllerName — déjà branché par le compiler-pass Sonata. Mocker un Admin sans disableOriginalConstructor() finit en spaghetti.

$admin = $this->getMockBuilder(DonAdmin::class)
    ->disableOriginalConstructor()
    ->onlyMethods(['getTranslator', 'getRequest', 'getModelManager'])
    ->getMock();

$admin->method('getTranslator')->willReturn($translator);
$admin->method('getRequest')->willReturn($request);

• Pourquoi disableOriginalConstructor ? Le constructeur Admin instancie un grand graphe d'objets (route generator, label translator strategy, model manager, datagrid builder…). En test unitaire on n'a aucun de ces composants câblés.
• Quand passer en test d'intégration ? Dès qu'un test touche à DatagridMapper, à configureFormFields qui dépend du subject, ou à un filtre Doctrine. WebTestCase + login simulé + assertion sur la page list/edit rendue.
• Pas de mock du pool Sonata dans les tests métier : les services qui dépendent d'un Admin doivent recevoir l'Admin par injection, pas via le pool global.

Méthodes configure*

Méthode	Signature	Usage Kohinos
configureFormFields	FormMapper $form	Ajouter les champs en réutilisant les FormTypes Symfony (TextType, EntityType, MoneyType, etc.). Toujours typer explicitement — ne pas passer null comme type de champ, Sonata 4 ne devine plus.
configureListFields	ListMapper $list	Colonnes de la liste + colonne _action avec les actions inline (edit, delete, custom). Toujours fermer la liste par une colonne actions explicite ; les row actions orphelines ne s'affichent pas.
configureDatagridFilters	DatagridMapper $filter	Filtres de la sidebar. Garder les filtres simples — les filtres complexes (multi-jointures) cassent l'ergonomie et le cache Sonata. Préférer une route custom.
configureShowFields	ShowMapper $show	Vue détail. Sur Kohinos, beaucoup d'Admins financiers exposent un show riche (Adhérent, Prestataire) là où la liste reste compacte.
configureRoutes	RouteCollectionInterface $collection	Déclarer les actions custom : $collection->add('execute', $this->getRouterIdParameter().'/execute'). Toujours associer un {id} quand l'action porte sur une instance.
configureBatchActions	array $actions	Ajouter / retirer des actions de masse (validate, archive…). La sécurité doit être doublée côté handler — le bouton est rendu conditionnellement, le handler doit re-vérifier le rôle.
configureActionButtons	array $buttonList, string $action, ?object $object	Override des boutons en haut de page. Cas Kohinos : DonAdmin remplace le bouton create par un dropdown {Don adhérent / Don prestataire}.

Sécurité Admin

Pattern champ hidden survivant au POST

Cas DonAdmin::expediteur_type (cf. commit 530372533) — le type d'expéditeur (adhérent vs prestataire) détermine la sous-classe STI DonAdherent ou DonPrestataire. Doctrine STI exige de choisir la sous-classe dès l'instanciation, donc le formulaire doit transporter cette information de manière fiable entre createNewInstance() et le POST final.

// 1. createNewInstance() — lit la query string ?expediteur_type=...
public function createNewInstance(): object
{
    $expediteurType = $this->resolveExpediteurType();
    return $expediteurType === 'prestataire' ? new DonPrestataire() : new DonAdherent();
}

// 2. configureFormFields() — déclare le champ NON mappé sur l'entité
$formMapper->add('expediteur_type', HiddenType::class, [
    'mapped'   => false,
    'data'     => $this->resolveExpediteurType(),
    'required' => false,
]);

// 3. resolveExpediteurType() — source de vérité centralisée
//    Ordre de résolution :
//      a) query string ?expediteur_type=...  (GET initial)
//      b) payload POST {uniqid}[expediteur_type]  (resubmit Sonata)
//      c) fallback : 'adherent'
private function resolveExpediteurType(): string
{
    $request   = $this->getRequest();
    $fromQuery = (string) $request->query->get('expediteur_type', '');
    if ($fromQuery !== '') { return $fromQuery; }

    foreach ($request->request->all() as $value) {
        if (is_array($value) && isset($value['expediteur_type'])) {
            return (string) $value['expediteur_type'];
        }
    }
    return 'adherent';
}

L'astuce REFERENCE_PLACEHOLDER = '(en cours de création)' du même Admin illustre une autre contrainte : Flux::$reference porte un #[Assert\NotBlank] qui est évalué avant prePersist(). Solution : on pose une valeur sentinelle dans createNewInstance(), le prePersist l'écrase ensuite par la vraie référence dérivée de l'expéditeur.

Translations dans Admin

L'API a changé : $this->trans() n'existe plus. Le pattern Kohinos :

// ❌ Sonata 3.x — NE FONCTIONNE PLUS
$label = $this->trans('admin.don.label');

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

• Le translation domain par défaut d'un Admin Kohinos est messages (et non SonataAdminBundle) — c'est ce que renvoie getTranslationDomain(), qui reste la source canonique.
• Fichiers de traduction : translations/messages.fr.yaml pour les libellés métier, translations/SonataAdminBundle.fr.xliff pour les libellés natifs Sonata (boutons, en-têtes).
• Dans les templates Twig d'Admin, utiliser {{ 'key'|trans({}, admin.translationDomain) }} plutôt que de coder le domaine en dur.

Anti-patterns à bannir

Tester un Admin

Trois niveaux selon ce qu'on veut vérifier :

Niveau	Quoi tester	Outils
Unitaire	Méthodes pures, helpers (resolveExpediteurType, formatage, createNewInstance sans subject)	PHPUnit + mocks (constructor disabled), mock du Request et RequestStack
Intégration	configureFormFields/configureDatagridFilters, validation des forms, hooks prePersist/preUpdate	KernelTestCase + container réel + EntityManager SQLite in-memory
Fonctionnel	Routes Admin (list, create, edit, custom action), sécurité, redirections, batch	WebTestCase + loginUser() + assertions sur le HTML rendu

# Suite ciblée — toujours filtrer, jamais lancer toute la suite
vendor/bin/phpunit tests/Admin/DonAdminTest.php
vendor/bin/phpunit tests/Admin/SolidoumeParamAdminTest.php
vendor/bin/phpunit --filter resolveExpediteurType

# Routes Admin multi-rôles (smoke test)
python3 scripts/test-routes.py --role super_admin --only-errors
python3 scripts/test-routes.py --role tresorier --only-errors

Filet de couverture global (SonataAdminCoverageTest)

tests/Functional/Admin/SonataAdminCoverageTest.php énumère tous les admins du pool Sonata (sonata.admin.pool, ~46 admins hors enfants) et vérifie en super_admin que chaque route list et create répond HTTP 200 (~90 routes). Tout admin cassé après un refactor (template absent, service mal câblé, query invalide, référence vers une entité supprimée) fait échouer le test avec l'URL et le code HTTP fautifs.

• Admins CMS (news, document, faq, page) : masqués en 403 par VoterSecurityHandler quand USE_WORDPRESS != 'false' — le test force le front natif via GlobalParameterFixture::enableCmsAdmins().
• Redirections internes : une seule redirection sous /admin/ est suivie (ex. classification category : list → tree), jamais vers /login (ça masquerait un 403).
• Références supprimées (purge RGPD, soft-delete) : les listes utilisent le template null-safe list_many_to_one_safe.html.twig + la fonction Twig kohinos_entity_exists() (App\Twig\EntityExistsExtension, déclarée manuellement dans services.yaml car src/Twig est exclu de l'autoregistration). Les lignes cassées affichent « (supprimé) » au lieu de provoquer une 500.
• Subject dans les templates de boutons : utiliser admin.hasSubject — admin.subject is defined passe le check Twig mais getSubject() lève une LogicException en contexte liste (Sonata 4).

Pour les tests fins par admin (exports, hooks, sécurité), hériter de tests/Admin/AbstractAdminTestCase.php : implémenter adminServiceId(), utiliser $this->admin et $this->actAs(['ROLE_TRESORIER']) pour poser un token en mémoire.

Checklist de revue d'un Admin

1. Aucune occurrence de $this->trans( — uniquement $this->getTranslator()->trans().
2. Chaque configureFormFields a des types explicites (pas de second argument null).
3. Chaque action custom déclarée dans configureRoutes() a une vérification de rôle dans son handler.
4. Chaque HiddenType sensible est mapped => false et restauré explicitement en prePersist/preUpdate.
5. Aucun appel direct à getRootAlias()/andWhere() contre ProxyQueryInterface.
6. Pas de mock de DatagridMapper dans les tests (il est final).
7. Pas de logique financière inline — délégation à un service domaine.
8. CHANGELOG technique + utilisateur mis à jour si l'Admin expose une nouvelle action visible.

Pour aller plus loin