Controladores Symfony en el back office de PrestaShop 9: guía práctica

Durante años, las pantallas de back office de un módulo se hacían con ModuleAdminController y HelperForm. Siguen funcionando, pero PrestaShop lleva desde la 1.7.6 migrando su propio back office a Symfony, y en la 9 la mayoría de pantallas del núcleo ya lo son. Un módulo moderno debería seguir el mismo camino.

1. La ruta

# 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 une la ruta con una pestaña del menú y con su sistema de permisos. Sin él, la pantalla funciona pero no aparece iluminada en el menú y los perfiles no se pueden restringir.

2. El controlador

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()) {
            // guardar…
            $this->addFlash('success', 'Guardado');
        }

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

En PrestaShop 9 la clase base recomendada es PrestaShopAdminController y la seguridad se declara con atributos de PHP 8. En la 8 se usa FrameworkBundleAdminController y anotaciones: si tu módulo soporta las dos versiones, comprueba cuál está disponible.

3. La pestaña del menú

Declárala en la propiedad $tabs del módulo o créala en la instalación. Y comprueba siempre si ya existe antes de crearla: una pestaña duplicada con la misma clase hace que Doctrine devuelva dos resultados donde espera uno, y la pantalla responde con un error 500 que no dice nada útil.

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

4. Tokens y enlaces

En PrestaShop 9 cada enlace del back office lleva un token CSRF de Symfony (_token). No construyas URLs a mano: usa $this->generateUrl('mimodulo_configuracion') en PHP o path() en Twig. Una URL copiada de otra sesión da «Token no válido».

5. Traducciones

En Twig: {{ 'Guardar'|trans({}, 'Modules.Mimodulo.Admin') }}. En PHP: $this->trans('Guardar', [], 'Modules.Mimodulo.Admin'). El dominio sigue el patrón Modules.Nombredelmodulo.Zona.

Qué ganas

• Formularios con validación de verdad, no comprobaciones a mano.
• Permisos por perfil integrados.
• Pantallas que se ven igual que las del núcleo, y que seguirán viéndose igual en la próxima versión.