Estructura de carpetas de un módulo PrestaShop: guía práctica

Un módulo PrestaShop no es solo un archivo PHP con algunos hooks. Un módulo serio tiene controladores, plantillas, assets, traducciones, scripts de actualización, dependencias Composer y a veces servicios. Una estructura clara facilita depurar, actualizar y dar soporte.

La documentación oficial tiene una guía de estructura de archivos de módulo. Este artículo es la versión práctica.

Carpeta principal

Un módulo vive en /modules/<module_name>/. El archivo principal debe llamarse igual: mymodule/mymodule.php. Gestiona instalación, hooks, configuración y metadatos.

Si este archivo crece demasiado, la lógica debería moverse a clases bajo src/.

controllers/

controllers contiene controladores front y admin. Los front suelen estar en controllers/front, y las pantallas back office en controllers/admin. Un controlador debe leer la petición, llamar servicios, asignar variables y responder.

views/

views contiene plantillas y assets. Separar views/templates/front, views/templates/admin y views/templates/hook facilita debugging e integración con temas.

src/

src es el lugar para clases modernas: servicios, entidades, validadores, clientes API y lógica reutilizable. Mantiene limpio el archivo principal.

translations/

Las traducciones son parte del producto. Labels, errores, emails, textos de ayuda y mensajes del front office deben tener un camino de traducción claro.

upgrade/

upgrade contiene scripts de actualización. Tablas, columnas, hooks, pestañas y configuración deben crearse en instalación o actualización, no comprobarse en cada petición.

vendor/

vendor contiene dependencias Composer. No edites manualmente copias vendor. Si el bug está en un paquete compartido, corrige la fuente del paquete y sincroniza.

config.xml y override/

config.xml debe coincidir con la versión del módulo. override debería ser una última opción, porque cambia comportamiento core.

Regla final

Una buena estructura no hace bueno a un módulo por sí sola, pero una mala estructura hace más caro cada bug futuro. Un módulo claro es más fácil de soportar, traducir y actualizar.

Esqueleto práctico del módulo

Un módulo limpio no tiene que ser complicado, pero debe ser predecible:

modules/
  mymodule/
    mymodule.php
    config.xml
    composer.json
    controllers/
    src/
    views/
    translations/
    upgrade/
    vendor/

No todos los módulos necesitan todas las carpetas. Un módulo pequeño de hook puede ser simple. Un módulo de checkout, pago o SEO casi siempre necesita más estructura.

Qué pertenece al archivo principal

El archivo principal describe el módulo y lo conecta con PrestaShop: metadatos, instalación, desinstalación, hooks y métodos ligeros. No debería contener miles de líneas de lógica, SQL en plantillas o formularios complejos.

controllers/ debe ser ligero

El controlador coordina: valida la petición, llama servicios, asigna variables y responde. Motores de precio, generadores sitemap o migraciones no deberían vivir enteros ahí.

src/ hace mantenible el módulo

src/ contiene clases reutilizables: installers, repositorios, validadores, clientes API, servicios, exportadores e importadores. Si una clase puede entenderse sin Smarty, probablemente pertenece a src/.

views/ no es lógica

Las plantillas renderizan datos. Pueden tener condiciones de presentación, pero no consultas SQL ni reglas de negocio. Separar front, admin y hook ayuda al debug.

upgrade/ es parte del contrato

Un módulo evoluciona: columnas, hooks, pestañas, configuración y migraciones. Eso debe estar en scripts de upgrade, no en auto-reparaciones vagas en cada request.

vendor/ necesita disciplina

Parchear copias vendor manualmente no es mantenible. Un bug en un paquete compartido se corrige en la fuente y se propaga.

override/ como última opción

Los overrides cambian core y complican upgrades. Hooks, controladores, servicios, eventos o lógica propia del módulo suelen ser más seguros.

Conexión con otras guías

Esta guía cubre la carpeta del módulo. Para la plataforma completa, revisa la guía de estructura PrestaShop. Para temas, mira el deep dive /themes/.

Checklist

• Archivo principal legible.
• Controladores que llaman servicios.
• Plantillas sin SQL.
• Assets trazables desde source a runtime.
• Install y upgrade gestionan schema, pestañas, hooks y configuración.
• Traducciones completas.
• Fixes vendor upstream.
• Overrides solo como excepción.

La carpeta aclarada aquí es /modules/<module_name>/.