Contrôleurs Symfony dans le back-office de PrestaShop 9 : guide pratique

Pendant des années, les écrans de back-office d'un module se faisaient avec ModuleAdminController et HelperForm. Ils fonctionnent toujours, mais PrestaShop migre son propre back-office vers Symfony depuis la 1.7.6, et dans la 9 la plupart des écrans du cœur le sont déjà. Un module moderne devrait suivre le même chemin.

1. La route

# config/routes.yml
mimodulo_configuracion:
  path: /mimodulo/configuracion
  methods: [GET, POST]
  defaults:
    _controller: 'Rekire\MiModulo\Controller\Admin\ConfiguracionController::indexAction'
    _legacy_controller: AdminMiModuloConfiguracion
    _legacy_link: AdminMiModuloConfiguracion

_legacy_controller relie la route à un onglet du menu et à son système de permissions. Sans lui, l'écran fonctionne mais n'apparaît pas en surbrillance dans le menu et les profils ne peuvent pas être restreints.

2. Le contrôleur

namespace Rekire\MiModulo\Controller\Admin;

use PrestaShopBundle\Controller\Admin\PrestaShopAdminController;
use PrestaShopBundle\Security\Attribute\AdminSecurity;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

class ConfiguracionController extends PrestaShopAdminController
{
    #[AdminSecurity("is_granted('read', request.get('_legacy_controller'))")]
    public function indexAction(Request $request): Response
    {
        $form = $this->createForm(ConfiguracionType::class);
        $form->handleRequest($request);
        if ($form->isSubmitted() && $form->isValid()) {
            // enregistrer…
            $this->addFlash('success', 'Enregistré');
        }

        return $this->render('@Modules/mimodulo/views/templates/admin/configuracion.html.twig', [
            'form' => $form->createView(),
        ]);
    }
}

Dans PrestaShop 9, la classe de base recommandée est PrestaShopAdminController et la sécurité se déclare avec des attributs PHP 8. Dans la 8, on utilise FrameworkBundleAdminController et des annotations : si votre module prend en charge les deux versions, vérifiez laquelle est disponible.

3. L'onglet du menu

Déclarez-le dans la propriété $tabs du module ou créez-le à l'installation. Et vérifiez toujours s'il existe déjà avant de le créer : un onglet en double avec la même classe fait que Doctrine renvoie deux résultats là où il en attend un, et l'écran répond par une erreur 500 qui ne dit rien d'utile.

if (!Tab::getIdFromClassName('AdminMiModuloConfiguracion')) {
    $tab = new Tab();
    // …
    $tab->add();
}

4. Jetons et liens

Dans PrestaShop 9, chaque lien du back-office porte un jeton CSRF Symfony (_token). Ne construisez pas les URL à la main : utilisez $this->generateUrl('mimodulo_configuracion') en PHP ou path() en Twig. Une URL copiée depuis une autre session donne « Jeton non valide ».

5. Traductions

En Twig : {{ 'Guardar'|trans({}, 'Modules.Mimodulo.Admin') }}. En PHP : $this->trans('Guardar', [], 'Modules.Mimodulo.Admin'). Le domaine suit le modèle Modules.Nombredelmodulo.Zona.

Ce que vous y gagnez

• Des formulaires avec une vraie validation, pas des vérifications faites à la main.
• Des permissions par profil intégrées.
• Des écrans qui ressemblent à ceux du cœur, et qui continueront à leur ressembler dans la prochaine version.