Estructura de PrestaShop 8 y 9: guía de carpetas, archivos y base de datos

PrestaShop no es solo una carpeta llena de archivos. Es una aplicación con dos arquitecturas conviviendo —Symfony y el código legado—, una base de datos relacional, módulos, temas y un sistema de hooks. Saber dónde vive cada pieza te ahorra horas cuando toca mantener, depurar, actualizar o proteger una tienda.

Esta guía está pensada para PrestaShop 8 y 9, las versiones actuales. Si vienes de una instalación estándar, todo lo que verás aquí te resultará familiar.

1. Arquitectura general: Symfony, legado y MVC

En PrestaShop 8 y 9, la aplicación convive con dos mundos. Por un lado está el núcleo moderno, construido sobre Symfony, que gestiona cada vez más partes del back office y de la lógica de negocio. Por otro, sigue presente el código legado que durante años ha dado forma al front office, a los modelos de datos y a los controladores clásicos.

Entender esta convivencia es la clave para no perderte: no todo está en el mismo sitio, y no todo se modifica de la misma forma.

El patrón MVC sigue presente, pero repartido entre ambos mundos: los modelos pueden ser clases ObjectModel legacy o entidades Doctrine; las vistas pueden ser plantillas Smarty del tema o plantillas Twig de Symfony; y los controladores pueden ser clases legacy, controladores de módulo o controladores Symfony.

2. Estructura de carpetas

Esta es la estructura típica de una instalación de PrestaShop. Algunas carpetas solo aparecen en el código fuente o en distribuciones de desarrollo, no en el ZIP de producción.

prestashop/
├── admin/                 # Back office (se renombra al instalar)
├── app/                   # Configuración, kernel y recursos Symfony
├── bin/                   # Consola: bin/console
├── cache/                 # Caché legacy (compatibilidad)
├── classes/               # Clases legacy: ObjectModel, Db, Helper...
├── config/                # Arranque y configuración
├── controllers/           # Controladores legacy (front y admin)
├── docs/                  # Documentación (según distribución)
├── download/              # Productos descargables
├── img/                   # Imágenes de catálogo, CMS, etc.
├── install/               # Instalador (eliminar o bloquear tras instalar)
├── js/                    # JavaScript del núcleo
├── localization/          # Datos de localización
├── mails/                 # Plantillas de correo
├── modules/               # Módulos
├── override/              # Sobrescrituras de clases
├── pdf/                   # Plantillas de PDF
├── src/                   # Núcleo moderno: Core, Adapter, PrestaShopBundle
├── templates/             # Plantillas Twig de los bundles Symfony
├── themes/                # Temas
├── translations/          # Traducciones
├── upload/                # Archivos subidos
├── var/                   # Caché, logs y sesiones
├── vendor/                # Dependencias de Composer
├── webservice/            # Endpoint de la API
├── index.php              # Punto de entrada del front
└── composer.json

En el código fuente también verás tests/, tests-legacy/, tools/ y travis-scripts/. Son carpetas de desarrollo y no forman parte del paquete de producción.

3. admin/: el back office

La carpeta admin/ es la entrada al panel de administración. En una instalación desde ZIP, PrestaShop la renombra automáticamente para dificultar los ataques automatizados; en el código fuente aparece como admin-dev/. Dentro conviven el actualizador, las copias de seguridad generadas desde el panel, las exportaciones, el gestor de archivos, las importaciones y las plantillas de los temas del back office.

• autoupgrade/: espacio de trabajo del módulo de actualización.
• backups/: copias de base de datos generadas desde el back office.
• export/ e import/: archivos de exportación e importación.
• filemanager/: gestor de archivos del panel.
• themes/: plantillas del back office, con los temas default y new-theme.

Es una carpeta sensible. Protégela con autenticación adicional, restricción por IP o reglas de firewall, y no la incluyas en el archivo de rastreo de buscadores. PrestaShop no incluye autenticación en dos pasos de serie; si tu tienda es seria, añádela con un módulo de confianza.

Si sospechas que el panel ha sido comprometido, revisa empleados, perfiles, últimas conexiones y actividad reciente. Tienes una guía más detallada en Intrusiones en PrestaShop: análisis técnico y soluciones.

4. modules/: la funcionalidad

Cada módulo vive en su propia carpeta dentro de modules/: modules/mimodulo/. El nombre debe usar minúsculas y números; mejor evitar guiones bajos porque dan problemas con los dominios de traducción. Si quieres eliminar un módulo, lo correcto es desinstalarlo desde el back office, no borrar la carpeta a mano.

mimodulo/
├── config/                # Rutas y servicios
├── controllers/           # Controladores legacy
│   ├── admin/
│   └── front/
├── override/              # Sobrescrituras del módulo (evitar si se puede)
├── src/                   # Clases modernas y controladores Symfony
├── translations/          # Traducciones
├── upgrade/               # Scripts de actualización
├── vendor/                # Dependencias del módulo
├── views/                 # CSS, JS, imágenes y plantillas
│   ├── css/
│   ├── img/
│   ├── js/
│   └── templates/
├── config.xml             # Metadatos del módulo
├── logo.png               # Logo visible en el back office
└── mimodulo.php           # Clase principal, extiende Module

Los módulos se conectan al núcleo mediante hooks. Algunos ejemplos habituales son hookDisplayHeader (añadir CSS o JavaScript), hookDisplayHome (contenido en la home), hookActionProductUpdate (reaccionar a cambios de producto) o hookDisplayFooter. Si un módulo necesita mostrar algo en una página, lo normal es que lo haga desde un hook, no modificando el tema.

Un módulo es también una puerta de entrada. Instala solo desde fuentes fiables, revisa el proveedor y mantén las actualizaciones al día. Si quieres ver un ejemplo práctico de módulo propio, tenemos una guía sobre cómo crear pop-ups en PrestaShop 8 y 9.

5. themes/: la capa visual

Todo lo que ve el cliente —plantillas, CSS, JavaScript, imágenes— vive en themes/<tema>/. El tema por defecto de PrestaShop 8 es Classic; a partir de ahí puedes instalar temas comerciales o crear un tema hijo.

themes/mitema/
├── _dev/                  # Fuentes SCSS, JS e imágenes de desarrollo
├── assets/                # CSS, JS e imágenes compiladas
│   ├── css/
│   ├── img/
│   └── js/
├── config/
│   └── theme.yml          # Configuración del tema
├── modules/               # Plantillas propias para módulos concretos
├── plugins/               # Plugins Smarty personalizados
├── templates/             # Plantillas del tema
│   ├── _partials/
│   ├── catalog/
│   ├── checkout/
│   ├── cms/
│   ├── customer/
│   ├── layouts/
│   ├── index.tpl
│   ├── page.tpl
│   └── wrapper.tpl
└── preview.png            # Miniatura para el back office

El front clásico usa plantillas Smarty (.tpl); la parte Symfony y el back office usan Twig. Si tu tema es moderno, revisa su documentación porque puede mezclar ambas capas.

La recomendación es crear un tema hijo y sobrescribir solo las plantillas necesarias. Así puedes actualizar el tema padre sin perder cambios. No edites directamente el tema Classic ni un tema comercial: la siguiente actualización borrará tus ajustes.

Si necesitas un diseño a medida, en Solusen trabajamos con diseño de tiendas virtuales con PrestaShop y conocemos bien esta estructura.

6. override/: personalizar sin tocar el núcleo

La carpeta override/ permite sustituir clases del núcleo sin modificar los archivos originales. Es una herramienta potente, pero también una de las principales fuentes de problemas cuando se abusa de ella.

override/
├── classes/
│   └── Cart.php
├── controllers/
│   ├── admin/
│   └── front/
└── modules/

El archivo de sobrescritura debe replicar la ruta y el nombre de la clase original. Por ejemplo, para modificar Cart se crea override/classes/Cart.php con una clase que extiende CartCore:

class Cart extends CartCore
{
    public function add()
    {
        // Lógica propia antes o después
        return parent::add();
    }
}

Si aun así necesitas una, documenta qué modifica, por qué y en qué versión. Después de crear o cambiar una sobrescritura, limpia la caché y comprueba que la clase se carga. Un error típico es Class not found por una ruta incorrecta o por una caché antigua.

7. app/, src/, templates/ y vendor/

Esta es la parte moderna de PrestaShop. Si vienes del PrestaShop clásico, aquí es donde más cambios vas a notar.

• app/: contiene AppKernel.php, la configuración de Symfony (config/) y recursos. El archivo app/config/parameters.php guarda credenciales de base de datos y el prefijo de tablas; es sensible y no se edita a la ligera.
• src/: contiene el núcleo moderno, con Core, Adapter y PrestaShopBundle. Las entidades Doctrine suelen estar en src/PrestaShopBundle/Entity/.
• templates/: plantillas Twig de los bundles Symfony.
• vendor/: dependencias instaladas por Composer. No se modifica nunca; si necesitas un cambio, se hace en el código propio o se actualiza la dependencia.

La consola de Symfony está en bin/console. Algunos comandos útiles en un entorno de pruebas:

php bin/console cache:clear
php bin/console debug:router
php bin/console list

No ejecutes estos comandos en producción sin ventana de mantenimiento y copia de seguridad. Y no edites vendor/ para “parchear” algo: la siguiente actualización lo sobrescribirá.

8. var/, cache/ y config/

La carpeta var/ contiene caché, logs y sesiones. Es escribible por el servidor web y es la que más se toca de forma indirecta: cuando cambias una plantilla, un módulo o una configuración, PrestaShop necesita regenerar la caché.

• var/cache/: caché de Symfony y de la aplicación. No la borres a mano si puedes usar el back office o la consola.
• var/logs/ o app/logs/ según la versión: logs de la aplicación. También revisa los logs de PHP y del servidor web.
• cache/: carpeta heredada de versiones anteriores. Se mantiene por compatibilidad, pero la caché real está en var/.
• config/: archivos de arranque, definiciones y autoload. No se edita salvo necesidad justificada.

Para limpiar la caché, lo más seguro es usar el back office: Parámetros avanzados → Rendimiento → Vaciar caché. También puedes usar php bin/console cache:clear en un entorno controlado. Si borras carpetas a mano, puedes dejar permisos o archivos en un estado inconsistente.

Permisos habituales: directorios 755, archivos 644, y escritura solo donde sea necesaria (var/, img/, upload/, download/). Evita 777 y propietarios incorrectos.

9. La base de datos

PrestaShop usa MySQL o MariaDB. El prefijo por defecto es ps_, aunque se puede cambiar durante la instalación. Ese prefijo se guarda en la configuración (app/config/parameters.php en PrestaShop 8 y 9). Si lo cambias después, tienes que actualizar la configuración y revisar módulos y copias de seguridad.

Dos convenciones importantes:

• Tablas _lang: guardan los campos traducibles. Por ejemplo, product contiene datos comunes y product_lang contiene el nombre y la descripción por idioma (id_lang).
• Tablas _shop: asocian una entidad a una tienda concreta en multitienda. Por ejemplo, product_shop guarda la relación producto-tienda. No todas las tablas tienen variante _shop.

Una consulta de lectura habitual para revisar catálogo y stock sería:

SELECT p.id_product, pl.name, p.price, sa.quantity
FROM ps_product p
JOIN ps_product_lang pl
  ON pl.id_product = p.id_product
 AND pl.id_lang = 1
LEFT JOIN ps_stock_available sa
  ON sa.id_product = p.id_product
LIMIT 20;

Cambia el prefijo ps_ y el id_lang si tu tienda usa otro. Esta consulta es solo de lectura. Para modificar datos, usa las clases de PrestaShop, un módulo o los scripts de actualización; no edites tablas a mano salvo que sea una operación de auditoría controlada.

Si necesitas leer el catálogo para exportarlo, tenemos una guía práctica sobre exportar productos de PrestaShop a Meta con un feed PHP.

10. Flujo de una petición

Cuando un cliente entra en la tienda, PrestaShop no carga todas las carpetas a la vez. Sigue un recorrido concreto. Entenderlo ayuda a depurar errores y a saber en qué capa buscar.

Petición del navegador
        ↓
index.php
        ↓
config/config.inc.php
        ↓
Dispatcher legacy / Symfony Kernel
        ↓
Controlador (legacy, módulo o Symfony)
        ↓
Hooks de módulos
        ↓
Plantilla Smarty / Twig
        ↓
Respuesta HTML

• Front office: entra por index.php, se carga el bootstrap y se resuelve la ruta. Si es una página legacy, la gestiona un controlador de controllers/front/ o de un módulo. Si es moderna, la gestiona Symfony.
• Back office: entra por la carpeta admin/ y se resuelve con controladores legacy o Symfony, con sus plantillas Twig correspondientes.
• Hooks: los módulos se enganchan en puntos concretos del flujo. Ahí es donde suele estar la funcionalidad añadida: cabecera, home, ficha de producto, carrito, checkout, footer o eventos de negocio.

Para depurar, activa el modo debug solo en pruebas, revisa el log de la aplicación y el de PHP, y localiza primero el controlador y la plantilla que están respondiendo. Si el error aparece al instalar o actualizar un módulo, el problema suele estar en el propio módulo o en la caché, no en el núcleo.

11. Dónde tocar cada cosa

Esta tabla resume la decisión más importante: qué carpeta usar según lo que quieras cambiar.

12. Buenas prácticas y errores comunes

La estructura de PrestaShop está pensada para extenderse, no para modificarse a lo bruto. Estas son las reglas que evitan la mayoría de los problemas:

• Usa un tema hijo para los cambios visuales y un módulo propio para la lógica de negocio.
• Prefiere hooks y servicios antes que sobrescrituras de clases.
• No edites vendor/, classes/, controllers/, src/ ni config/ del núcleo.
• Haz copia de seguridad de archivos y base de datos antes de cualquier cambio importante.
• Prueba en staging y verifica el proceso de compra después de cada actualización.
• Mantén actualizados el núcleo, los módulos, el tema y PHP.
• Renombra y protege la carpeta de administración; elimina o bloquea install/.
• Limpia la caché después de tocar plantillas, módulos o configuración.
• Revisa los logs antes de desactivar módulos a ciegas.
• Documenta cada sobrescritura y cada módulo propio: quién lo hizo, para qué y en qué versión.

La seguridad también forma parte de la estructura. Una carpeta de administración expuesta, un módulo abandonado o un install/ accesible pueden arruinar el mejor diseño. Si sospechas de una intrusión, revisa nuestra guía sobre los ataques más habituales en PrestaShop y el servicio de recuperación de páginas hackeadas.

13. Preguntas frecuentes sobre la estructura de PrestaShop

14. Conclusión

Conocer la estructura de PrestaShop no es un ejercicio académico. Es lo que te permite saber dónde tocar sin romper nada, por qué un módulo no se ve, qué tabla guarda cada dato y cómo actuar cuando la tienda se comporta de forma extraña. La regla de oro es sencilla: extiende antes de modificar, prueba antes de publicar y haz copia antes de tocar.

Si tu tienda PrestaShop necesita mantenimiento, una revisión de seguridad o una migración, podemos ayudarte.