Migración a PrestaShop 9: Guía completa de actualización

Por qué tratamos PrestaShop 9 como una plataforma diferente, no como una simple subida de versión

Hemos migrado todo nuestro catálogo de más de 140 módulos a PrestaShop 9 y hemos ayudado a tiendas de clientes a pasar por el mismo ejercicio. El resumen sincero: PS 9 es la mayor ruptura desde el salto de 1.6 a 1.7. El número de versión avanza una cifra, pero la plataforma que hay debajo avanza una generación. Planifique en consecuencia. Para conocer lo último que llegó con 9.1, consulte nuestras notas de la versión PrestaShop 9.1.

Última revisión: 24 de mayo de 2026. Los requisitos del servidor se han contrastado con la guía oficial de configuración del servidor de PrestaShop y con las notas de actualización del núcleo de módulos de 9.0. Las capturas de pantalla de esta guía proceden de una tienda real de desarrollo PrestaShop 9.1.0 que mantenemos para pruebas de módulos, no de maquetas.

Lo que realmente notará tras actualizar:

Symfony 6.4 LTS reemplaza a Symfony 4.4

PS 8 funcionaba sobre Symfony 4.4. PS 9 da el salto a 6.4 LTS, con parches de seguridad hasta noviembre de 2027. El efecto práctico: un ciclo de vida de petición más rápido, un contenedor de inyección de dependencias moderno y acceso a los componentes de Symfony que el resto del mundo PHP ha estandarizado. Para nosotros como autores de módulos, es la diferencia entre escribir PHP con sabor a 2018 y escribir PHP con sabor a 2026.

Suelo de PHP 8.1, pero no se quede ahí

PS 9.0 requiere PHP 8.1 como mínimo y admite 8.2, 8.3 y 8.4. PS 9.1 añade 8.5. El mínimo es el suelo de compatibilidad, no la recomendación. En cada nueva instalación de PS 9 que hemos hecho en 2026, hemos apuntado a PHP 8.4 (PS 9.0) o 8.5 (PS 9.1), pero solo después de que todos los módulos instalados pasaran las pruebas con esa versión de PHP en el entorno de pruebas (staging). Leer «PHP 8.1+» como «ponga staging en PHP 8.1» deja rendimiento real sin aprovechar.

Twig se está apoderando del back office (pero no está terminado)

La mayor parte del back office se renderiza ahora a través de Twig, pero la migración no está completa. Los nuevos controladores de administración basados en Symfony usan Twig de forma nativa. Los controladores de administración heredados (legacy) siguen funcionando, pero quedan envueltos por un LegacyController de Symfony que canaliza su salida Smarty hacia la maquetación de Twig. Ese envoltorio es responsable de la mayoría de los informes del tipo «la página de administración de mi módulo se renderiza, pero los botones desaparecieron» que hemos visto durante las migraciones a PS 9. El hecho de que ese envoltorio exista siquiera le indica que la migración aún está en curso.

Hummingbird es la dirección, pero Classic todavía no ha desaparecido

Hummingbird es el tema moderno de front office de PrestaShop. En PS 9.1 es el predeterminado para las instalaciones nuevas. En las tiendas PS 9.0 que se actualizaron, su tema existente se mantiene, y algunas distribuciones de PS 9 todavía incluyen Classic como tema disponible. Así que la pregunta real no es «¿está instalado Classic?», sino «¿están sus plantillas, hooks, recursos y estrategia de tema hijo listos para Hummingbird?». Porque ahí es hacia donde se dirige, independientemente de dónde empiece.

Hummingbird está construido sobre Bootstrap 5.3, se apoya en las propiedades personalizadas de CSS (custom properties) y es notablemente más ligero que Classic. Lo hemos usado como base para nuevos proyectos desde su lanzamiento y es una mejor cimentación para los Core Web Vitals que cualquier cosa que PrestaShop haya ofrecido antes. Combínelo con Performance Revolution y una puntuación moderna de PageSpeed es alcanzable en una tienda real, no solo en una demo.

Renovación de la seguridad

Symfony 6.4 trae un componente de seguridad completamente renovado. El hashing de contraseñas utiliza bcrypt/argon2 a través del MigratingPasswordHasher de Symfony. La protección CSRF es más estricta. La autenticación se enruta a través del bundle de seguridad de Symfony en lugar de la ruta heredada de cookies de PrestaShop. Se han cerrado varios agujeros de inyección SQL y XSS en rutas de código antiguas. Para nosotros, esto significa menos tickets del tipo «por favor, parchee este método concreto» de clientes en auditorías de cumplimiento. Tras la actualización, Security Revolution es la capa a nivel de módulo que usamos para el endurecimiento del back office, la política de 2FA y los cambios de integridad de archivos.

PS 9 no es cosmético. La plataforma que hay debajo de su tienda se ha reconstruido. La recompensa es real (más rápida, más segura, más mantenible), pero solo si la migración se hace de forma metódica. Hemos visto actualizaciones precipitadas a PS 9 dejar tiendas caídas durante días. También hemos visto otras bien preparadas terminar en una tarde. La diferencia está enteramente en la preparación.

Requisitos previos: no toque producción hasta que cada punto esté marcado

La causa más habitual de actualizaciones fallidas en las que nos llaman es «simplemente ejecuté el 1-Click Upgrade y se rompió». Casi siempre, la actualización en sí no falló: fallaron los requisitos previos, horas antes, y nadie los comprobó.

Ponga la tienda en modo mantenimiento antes del trabajo arriesgado

Back Office > Parámetros de la tienda > General > Mantenimiento es donde se desactiva la tienda, se incluye la propia IP en la lista blanca y se escribe el mensaje de mantenimiento. Úselo para los ensayos en staging y para la breve ventana de cambio en vivo, no como sustituto de las pruebas.

Esta es una pantalla real de una tienda de desarrollo PS9.1. Aquí lo que importa es el flujo de trabajo; no copie ciegamente la IP ni el texto de ejemplo.

Requisitos del servidor

• PHP 8.1+: confírmelo con php -v. Para un entorno de staging de PS 9.1 en 2026, pruebe con PHP 8.4 u 8.5 solo una vez que todos los módulos pasen.
• MySQL 5.7+ o MariaDB 10.2+: confírmelo con mysql --version. Para infraestructura nueva, MySQL 8.0 o MariaDB 10.11 es el objetivo realista.
• Extensiones de PHP: intl, gd, curl, zip, mbstring, openssl, pdo_mysql, fileinfo, dom, json
• Composer 2.x
• memory_limit de al menos 256 MB: súbalo temporalmente a 512 MB para la propia ejecución de la actualización si tiene un catálogo grande
• max_execution_time de 600+ segundos: las bases de datos grandes ejecutan migraciones largas

Comprobación rápida desde la CLI:

# Versión de PHP
php -v

# Extensiones requeridas
php -m | grep -E "(intl|gd|curl|zip|mbstring|openssl|pdo_mysql)"

# Límites de memoria y de ejecución
php -i | grep -E "(memory_limit|max_execution_time)"

# Base de datos
mysql --version

Objetivos prácticos de tiempo de ejecución

Compruebe el tiempo de ejecución real, no el folleto del hosting

En PS 9, Parámetros avanzados > Información muestra exactamente qué está ejecutando la tienda: versión de PHP, versión de la base de datos, límite de memoria, versión de la tienda, tema activo. Haga una captura de esta página antes de empezar. Cuando la actualización se tuerza y esté intercambiando tickets con el hosting a las 2 de la madrugada, tener la referencia previa a la actualización le ahorra horas.

La captura de abajo procede de una tienda de desarrollo PS 9.1.0 que ejecuta PHP 8.5, MySQL 8.0, 512 MB y Hummingbird.

Requisitos de versión de PrestaShop

• Tiene que estar en PS 8.1 o 8.2 antes de poder pasar a 9. No se admiten actualizaciones directas desde 1.7.x o anteriores. Punto.
• ¿Está en PS 1.7.x? Llegue primero a 8.2, estabilice durante una o dos semanas y luego pase a 9.
• ¿Está en PS 1.6.x? Deje de leer la ruta de actualización. Necesita una reconstrucción limpia. Nunca hemos visto que una actualización in situ de 1.6 → 9 tenga éxito; consulte la sección de Instalación Limpia.

Compatibilidad de módulos: la parte que decide si la actualización tiene éxito

Aquí es donde se torcieron la mayoría de las actualizaciones que hemos tenido que diagnosticar. Antes de tocar el botón de actualización, necesita saber qué módulos sobrevivirán a PS 9 y cuáles no. No «probablemente»: saberlo de verdad.

1. Extraiga la lista completa de módulos desde el Gestor de Módulos.
2. Para cada módulo de terceros, contacte con el proveedor y obtenga una respuesta concreta para PS 9. «Funcionaba en PS 8» no es la respuesta que necesita.
3. Para todo lo que no esté confirmado: decida actualizar, reemplazar o eliminar. No arrastre una incógnita.
4. Los módulos de pago primero. Una pasarela de pago sin confirmar tras la actualización significa cero ingresos hasta que la arregle.

No afirme la compatibilidad de un módulo con PS 9 porque la categoría parezca similar o porque un módulo hermano lo admita. Hemos visto módulos que funcionaban bien en 8.2 caerse en seco en 9.0 porque llaman a Tools::displayPrice(), un método que fue eliminado, no marcado como obsoleto. Pruebe, no confíe en la suerte.

Audite los módulos instalados en el Gestor de Módulos real

Back Office > Módulos > Gestor de Módulos le ofrece los nombres de los módulos instalados, las versiones, los proveedores, el estado y las señales de actualización. Construya su hoja de cálculo de migración a partir del estado real de la tienda, no de memoria ni de una vieja copia por FTP.

Los módulos de pago, proceso de compra, envío, ERP y feeds, incluidas herramientas de feeds como Smart Google Merchant Feed Manager, merecen la máxima prioridad porque un fallo ahí detiene los ingresos o el procesamiento de pedidos.

Señales de triaje de módulos que comprobamos de verdad

Compatibilidad del tema

• ¿Está usando Classic? Trátelo como deuda de migración. Confirme si su distribución de PS 9 todavía lo incluye, pero planifique Hummingbird o un tema de PS 9 de terceros igualmente.
• ¿Está usando un tema de pago? Escriba al proveedor antes que nada. Si no hay versión para PS 9 ni un calendario claro, empiece a portarlo ahora.
• ¿Un tema a medida construido sobre Classic? Trabajo de adaptación considerable. La estructura de plantillas ha cambiado lo suficiente como para que «buscar y reemplazar las clases de Bootstrap» no lo lleve hasta el final.
• Para cualquier trabajo a medida en adelante, el camino es un tema hijo de Hummingbird. Edite el padre y perderá sus cambios en la siguiente actualización del tema.

Cuándo hacerlo

• Nunca durante un pico de ventas. Hemos visto cómo se intentaba. No acaba bien.
• Entre semana, a primera hora de la mañana, en la ventana de menor tráfico que tenga.
• Dese al menos 48 horas de monitorización antes de que llegue el siguiente pico.
• Plan de marcha atrás (rollback) listo y probado: se cubre más adelante en esta guía.

Haga una copia de seguridad de todo. Sí, de verdad.

Este es el paso que todo el mundo lee por encima. No lo haga. El número de llamadas de recuperación del tipo «no pensábamos que necesitábamos una copia de seguridad» que hemos recibido es la única razón por la que esta sección es tan directa. Si la actualización falla y no tiene una copia de seguridad, no tiene tienda.

Base de datos

La base de datos es la parte que no puede reconstruir. Productos, clientes, pedidos, configuraciones, ajustes de módulos: todo vive ahí. Use mysqldump con las opciones adecuadas:

# Funciona en cualquier servidor
mysqldump -u root -p --single-transaction --quick --lock-tables=false prestashop > ~/backup_pre_ps9_$(date +%Y%m%d_%H%M%S).sql

# Base de datos grande (>1 GB): comprima sobre la marcha
mysqldump -u root -p --single-transaction --quick --lock-tables=false prestashop | gzip > ~/backup_pre_ps9_$(date +%Y%m%d_%H%M%S).sql.gz

Tiendas basadas en Docker:

docker exec <your-shop>-db mysqldump -u root -p'YOUR_PASSWORD' --single-transaction --quick prestashop > ~/backup_pre_ps9_$(date +%Y%m%d_%H%M%S).sql

Qué hacen esas opciones y por qué las usamos siempre:

• --single-transaction: instantánea consistente sin bloquear tablas. Esencial para InnoDB en una tienda en vivo.
• --quick: transmite las filas en lugar de almacenarlas en búfer. Sin ella, las tablas grandes de productos o pedidos pueden agotar la memoria del volcado (OOM).
• --lock-tables=false: mantiene la tienda en línea durante el volcado.

Ahora verifique que la copia de seguridad funciona de verdad. Una copia de seguridad que nunca ha restaurado es una esperanza, no una copia de seguridad:

# Restaure en una base de datos desechable y cuente las filas
mysql -u root -p -e "CREATE DATABASE prestashop_backup_test;"
mysql -u root -p prestashop_backup_test < ~/backup_pre_ps9_XXXXXXXX_XXXXXX.sql
mysql -u root -p prestashop_backup_test -e "SELECT COUNT(*) FROM ps_product; SELECT COUNT(*) FROM ps_orders;"
mysql -u root -p -e "DROP DATABASE prestashop_backup_test;"

Archivos

Haga una copia de seguridad de todo el árbol de PrestaShop: PHP, temas, módulos, imágenes subidas:

# Tarball completo
tar -czf ~/prestashop_files_pre_ps9_$(date +%Y%m%d_%H%M%S).tar.gz /var/www/html/

# Omitir cachés y registros (se regeneran de todos modos)
tar -czf ~/prestashop_files_pre_ps9_$(date +%Y%m%d_%H%M%S).tar.gz \
  --exclude='var/cache' \
  --exclude='var/logs' \
  /var/www/html/

Para Docker, el volumen montado:

tar -czf ~/prestashop_files_pre_ps9_$(date +%Y%m%d_%H%M%S).tar.gz /path/to/docker/html/

Guarde las copias de seguridad en dos lugares. El propio servidor, más algún sitio externo: su máquina local, un bucket de S3, un servidor distinto, cualquier sitio que no esté en el mismo disco que la tienda en vivo. Una copia de seguridad en el mismo disco que la actualización acaba de corromper no es una copia de seguridad.

Configuración que necesitará conocer más adelante

Anote todo esto antes de empezar. Cuando la actualización esté a medias y el back office sea inaccesible, no querrá estar adivinando:

• app/config/parameters.php: credenciales de la base de datos, configuración del mailer, clave de cookie
• .htaccess: especialmente cualquier regla de reescritura personalizada que haya añadido
• Ajustes de SMTP / correo electrónico desde el back office
• Claves de API de la pasarela de pago y URL de webhook
• Entradas de tareas cron (ejecute crontab -l y guárdelas)
• Cualquier configuración personalizada del servidor: bloques de Nginx, ajustes del pool de PHP-FPM, reglas de Cloudflare

Haga capturas de las páginas de ajustes críticos del back office mientras todavía funcionan. La referencia visual de «qué aspecto tenía antes» vale su peso en tickets de soporte.

La actualización en sí

Dos caminos legítimos: el módulo oficial 1-Click Upgrade, o una instalación limpia con migración de datos. Cada uno tiene su lugar. Hemos hecho ambos. Ninguno es «el correcto»: depende enteramente de la forma de la tienda que esté actualizando.

Camino 1: 1-Click Upgrade (módulo autoupgrade)

El camino oficial. El módulo autoupgrade se encarga del reemplazo de archivos, la migración de la base de datos y la limpieza posterior a la actualización. A pesar del nombre, no es literalmente un solo clic. Es un clic más una lista de comprobación.

Preparación

1. Instale o actualice el módulo 1-Click Upgrade a la última versión desde el Marketplace.
2. Abra Módulos → 1-Click Upgrade. El módulo muestra su versión actual y los destinos disponibles.
3. Ejecute la lista de comprobación previa a la actualización. Comprueba la compatibilidad del servidor y señala los problemas. No pase por alto las advertencias: arréglelas primero.

Modo mantenimiento activado

Desde el back office: Parámetros de la tienda → General → Mantenimiento → Activar. Incluya su propia IP en la lista blanca. No querrá que un cliente realice un pedido mientras la migración de la base de datos está reescribiendo ps_orders.

Ejecútelo

1. En el módulo 1-Click Upgrade, elija su versión de destino PS 9.x.
2. Elija «Actualización mayor» como canal.
3. Marque estas opciones:
   • Hacer copia de seguridad de archivos y base de datos: sí, aunque ya la haya hecho. Cinturón y tirantes.
   • Desactivar módulos no nativos: sí. Esta es la opción que evita la mayoría de los informes del tipo «el módulo X tiró abajo la actualización a mitad de camino».
   • Regenerar plantillas de correo electrónico: solo si no las ha personalizado.
4. Haga clic en «Actualizar PrestaShop ahora».
5. No cierre la pestaña. No navegue a otro sitio. No actualice (refresque). El módulo se comunica consigo mismo a través de la sesión del navegador; interrumpirlo deja una base de datos migrada a medias que es realmente penosa de recuperar.

Desde 5 minutos (tienda pequeña, pocos módulos) hasta más de 30 minutos (catálogo grande, muchos módulos). El registro de progreso muestra cada paso. Si se queda atascado en el mismo paso durante más de 10 minutos, revise los registros de errores de PHP en otra pestaña, pero no mate el navegador.

Cuando termine

# Vaciar cachés: cada vez, sin excepciones
rm -rf var/cache/*

# Vía CLI (preferido)
php bin/console cache:clear --env=prod
php bin/console cache:warmup --env=prod

# Permisos: la actualización suele ejecutarse como un usuario distinto
chown -R www-data:www-data /var/www/html/var/
chown -R www-data:www-data /var/www/html/themes/
chmod -R 755 /var/www/html/var/

Reactive los módulos de forma metódica

Si dejó que el actualizador desactivara los módulos no nativos (lo hizo, ¿verdad?), no los reactive todos de golpe. Actívelos de uno en uno:

1. Active el módulo.
2. Compruebe el front office y el back office en busca de errores.
3. Si funciona, el siguiente. Si rompe algo, desactívelo y anote exactamente qué se rompió.

Esto es lento. También es la única manera de saber qué módulo causó el problema cuando algo se rompe. Mirar una tienda rota con 30 módulos activados e intentar adivinar cuál es el culpable es una forma de perder una tarde entera.

Camino 2: Instalación limpia con migración de datos

A veces el movimiento más limpio es empezar de cero. Instale PS 9 nuevo en un directorio o servidor distinto y migre sus datos a él. Más trabajo por adelantado, pero acaba con una tienda que no arrastra años de deuda acumulada.

Cuándo es acertada una instalación limpia

• Está en PS 1.6.x. La actualización in situ no se admite. No lo intente.
• La tienda actual tiene años de overrides acumulados, módulos eliminados a medias y tablas huérfanas en la base de datos. El tipo de tienda en la que cada desarrollador que la mira dice «yo empezaría de cero».
• Va a cambiar de tema de todos modos.
• La base de datos está hinchada con carritos abandonados, registros antiguos y datos muertos.
• Ya ha intentado actualizaciones in situ antes y han fallado.

El proceso

1. Instale PS 9 nuevo en un directorio o servidor de staging.
2. Configure el tema (Hummingbird, o un tema de terceros compatible con PS 9).
3. Instale los módulos: solo versiones compatibles con PS 9.
4. Migre los datos, vía importación CSV o SQL directo.
5. Reconfigure pagos, envíos, impuestos y correo electrónico.
6. Pruebe todo en la nueva instalación mientras la tienda antigua sigue en vivo.
7. Cambie el DNS o intercambie el document root cuando esté satisfecho.

Importación CSV

La importación integrada de PrestaShop (Parámetros avanzados → Importar) gestiona categorías, productos con combinaciones y stock, clientes, direcciones, fabricantes y proveedores. Exporte desde la tienda antigua, limpie los CSV e impórtelos en la nueva. Tedioso para catálogos grandes, pero el resultado es limpio.

Migración SQL directa

Para conjuntos de datos más grandes, el SQL directo es más rápido, pero solo si conoce de verdad el esquema de PrestaShop:

# Exporte las tablas que necesita de la base de datos antigua
mysqldump -u root -p old_prestashop \
  ps_product ps_product_lang ps_product_shop \
  ps_category ps_category_lang ps_category_shop \
  ps_customer ps_address \
  ps_image ps_image_lang ps_image_shop \
  ps_stock_available \
  > ~/migration_data.sql

# Después revise y ajuste para los cambios de esquema entre versiones
# Los nombres de columna, las estructuras de tabla y las claves foráneas difieren entre versiones mayores

La migración SQL asume que puede leer y parchear el esquema de PrestaShop con confianza. Si no puede, use la importación CSV o contrate a alguien que sí pueda. Hemos limpiado suficientes migraciones SQL chapuceras como para saber que el tiempo ahorrado no compensa el riesgo cuando las claves foráneas discrepan en silencio.

¿Qué camino?

Para la mayoría de las tiendas PS 8.x con módulos razonablemente mantenidos, la actualización automática es lo acertado. La instalación limpia es la respuesta cuando viene de una versión muy antigua o cuando quiere aprovechar la reconstrucción como oportunidad para limpiar la casa.

Qué se rompe en PS 9 (la perspectiva del desarrollador)

Si mantiene módulos o tiene código a medida, esta sección es la que hay que leer con atención. El resto es operaciones; aquí es donde vive la ruptura real del código.

Las plantillas de administración de Smarty están siendo reemplazadas

La mayor ruptura individual. En PS 8, los controladores de administración heredados renderizaban plantillas Smarty directamente. En PS 9, los nuevos controladores de Symfony usan Twig de forma nativa, y los controladores heredados quedan envueltos por LegacyController, que canaliza su salida Smarty hacia la maquetación de Twig. La migración no está completa (el envoltorio existe porque los controladores heredados todavía renderizan Smarty internamente), pero el marco que los rodea es Twig, y eso es lo que rompe las plantillas de módulos que asumían un control total de la página por parte de Smarty.

Lo que nos encontramos al migrar nuestros propios controladores de administración:

• Los módulos con AdminController + Smarty siguen funcionando, pero se renderizan dentro de la nueva maquetación de Twig a través de la capa de compatibilidad. La mayoría de los informes del tipo «la página carga, pero falta el formulario» se remontan a esto.
• Los overrides de plantillas de administración en override/controllers/admin/templates/ a menudo no funcionan como se espera. El envoltorio no siempre los recoge.
• Las variables Smarty asignadas en initContent() pueden desaparecer: LegacyController envuelve el render de forma distinta, y la variable content de Smarty necesita reasignarse explícitamente en algunos casos.
• display() en AdminController ya no se invoca. El envoltorio lo omite. Si personalizó display(), ese código está muerto en PS 9.

Los overrides son cada vez menos viables

PrestaShop lleva desalentando los overrides desde la 1.7. PS 9 aprieta más las tuercas:

• Los overrides de clase todavía funcionan técnicamente para las clases heredadas de estilo ObjectModel, pero la superficie se está reduciendo a medida que más núcleo pasa a servicios de Symfony.
• Los overrides de controlador son poco fiables: la capa de enrutamiento de Symfony no siempre los carga.
• Los overrides de plantillas en override/ para páginas de administración están obsoletos.
• Las alternativas admitidas son los hooks, los decoradores de servicios de Symfony y los suscriptores de eventos. Hemos estado reemplazando cada override de nuestra propiedad por uno de estos.

Si un módulo depende mucho de los overrides, es lo más probable de su entorno técnico que se rompa durante la actualización a PS 9. Compruebe siempre el directorio override/ de cada módulo instalado antes de apretar el gatillo.

Cambios en los hooks

• Varios hooks de administración heredados se eliminan o renombran a medida que esas páginas de administración migran a Symfony.
• Existen nuevos hooks para las páginas de administración basadas en Symfony, que se cubren en nuestra guía de hooks.
• La mayoría de los hooks de front office siguen funcionando, pero Hummingbird cambia o elimina algunas suposiciones sobre el marcado. Los módulos que inyectan contenido en los resultados de búsqueda, las páginas de detalle de pedido, los modales, los bloques de producto o el proceso de compra: vuelva a probarlos todos.
• El orden de ejecución de los hooks puede variar en casos límite. Si su módulo depende de ejecutarse antes o después de otro módulo en el mismo hook, verifíquelo.

Cambios en los controladores de administración heredados

Varios patrones que funcionaban en PS 8 se comportan de forma distinta en PS 9:

• $this->l() se ha eliminado de los controladores de administración. Use $this->module->l('string', 'ControllerClassName') en su lugar.
• Tools::displayPrice() se ha eliminado. Use Context::getContext()->getCurrentLocale()->formatPrice($amount, $currencyIsoCode). Lo envolvimos en nuestro paquete prestashop-compat para tener que arreglarlo una sola vez en más de 140 módulos.
• $this->meta_title, $this->fields_list y $this->bulk_actions deben asignarse ahora después de parent::__construct(). La referencia al módulo no está disponible antes de esa llamada.
• Deje de codificar de forma fija el directorio del back office. Las tiendas lo renombran, los tokens cambian, y las rutas de Symfony deberían generarse en lugar de ensamblarse como cadenas de texto.

Auditar un módulo para verificar que está listo para PS 9

Para cada módulo instalado, en orden de comprobaciones más rápidas primero:

1. Declaración de compatibilidad del proveedor. Busque una afirmación explícita sobre PS 9: versión, no categoría.
2. Overrides. Mire dentro de modules/yourmodule/override/. Cualquier cosa ahí es una bandera amarilla.
3. Llamadas a funciones eliminadas. Busque en el PHP del módulo las más evidentes:
   • Tools::displayPrice(
   • $this->l( en cualquier archivo de controlador de administración
   • Clases AdminController que personalizan display()
   • Rutas del directorio de administración codificadas de forma fija
4. ps_versions_compliancy en el archivo PHP principal del módulo: ¿incluye realmente el límite superior la versión 9.x?

# Ejecute desde dentro del directorio del módulo

# ¿Hay overrides?
find override/ -type f 2>/dev/null && echo "WARNING: module uses overrides"

# Llamadas a funciones eliminadas
grep -rn "Tools::displayPrice" *.php controllers/ classes/ 2>/dev/null
grep -rn '$this->l(' controllers/admin/ 2>/dev/null

# Compatibilidad declarada
grep -A2 "ps_versions_compliancy" *.php

Trate las actualizaciones de módulos disponibles como trabajo de migración

La pantalla de actualizaciones de módulos muestra qué módulos ya necesitan atención antes de la actualización del núcleo. Actualícelos primero en staging y luego ejecute las pruebas de proceso de compra, pago, envío y pedidos antes de tocar el entorno en vivo.

Evite un clic en «actualizar todo» en vivo durante la migración. Las actualizaciones de módulos pertenecen a la misma matriz de pruebas controlada que la propia actualización de PrestaShop.

Migración del tema: Hummingbird es la dirección

PS 9.1 convierte a Hummingbird en el tema predeterminado para las instalaciones nuevas de PS 9.1. Las tiendas PS 9.0 conservan lo que tenían. Algunas distribuciones de PS 9 todavía incluyen Classic como opción. Así que planifique a partir del estado real de la tienda, no de una única suposición universal.

Empiece en Tema y Logo

En una tienda real de desarrollo PS 9.1, Diseño > Tema y Logo muestra Hummingbird como actual, Classic todavía disponible y nuestro tema hijo de Hummingbird instalado. Por eso el único consejo seguro es «audite primero la tienda actual y luego decida». Hemos visto planes de migración construidos sobre suposiciones de tiendas con solo Hummingbird venirse abajo porque Classic seguía activo.

Si mantiene plantillas a medida, trabaje en un tema hijo de Hummingbird. No edite el padre.

Qué tiene de diferente Hummingbird

• Bootstrap 5.3 en lugar de Bootstrap 4. Los nombres de clase, el sistema de rejilla y las clases de utilidad han cambiado. Portar un tema no es buscar y reemplazar.
• Propiedades personalizadas de CSS para la tematización. Colores, espaciado, tipografía: todo son variables, no parciales de SCSS.
• Menos JavaScript. Características nativas del navegador en lugar de plugins de jQuery siempre que es posible. Páginas más ligeras.
• Sistema de compilación moderno. Webpack con tree shaking. Bundles más pequeños.
• Mobile-first. El móvil es la maquetación base, el escritorio es la mejora. Classic era lo contrario. El modelo mental es distinto.

Si todavía está en Classic

1. Cambie a Hummingbird. Lo más sencillo. Cree un tema hijo para sus personalizaciones.
2. Compre un tema compatible con PS 9. Muchos proveedores han lanzado versiones para PS 9.
3. Porte sus personalizaciones de Classic a un tema hijo de Hummingbird. El que más trabajo lleva, el mejor resultado a largo plazo.

Construir un tema hijo de Hummingbird

Un tema hijo le permite personalizar Hummingbird sin tocar el padre, de modo que sus cambios sobreviven a las actualizaciones del tema:

mkdir -p themes/my-child-theme/assets/css
mkdir -p themes/my-child-theme/templates

themes/my-child-theme/config/theme.yml:

parent: hummingbird
name: my-child-theme
display_name: My Custom Theme
version: 1.0.0
author:
  name: Your Name

Coloque los estilos personalizados en themes/my-child-theme/assets/css/custom.css. Hummingbird carga custom.css desde el tema hijo con la prioridad más baja, de modo que sus reglas sobrescriben al padre.

Para sobrescribir una plantilla, cópiela de themes/hummingbird/templates/ a la misma ruta relativa dentro de su tema hijo. Copie únicamente los archivos que necesite cambiar; todo lo demás recae automáticamente en el padre.

Si compró su tema

Escriba al proveedor antes de hacer cualquier otra cosa. Las preguntas que importan:

• ¿Hay una versión compatible con PS 9?
• ¿Está basado en Hummingbird o es independiente?
• ¿Su licencia actual cubre la versión para PS 9?
• ¿Cuál es la ruta de migración desde la versión actual?

Si el proveedor no puede darle una versión para PS 9 ni una fecha, empiece a planificar su cambio a Hummingbird ahora. Esperar seis meses para descubrir que la respuesta sigue siendo «no» es una posición todavía peor en la que estar.

Lista de comprobación posterior a la actualización

La actualización terminó, el back office carga, puede iniciar sesión. No lo publique aún. Cada función crítica necesita verificarse antes de retirar la página de mantenimiento.

Front office

Back office

Pasarelas de pago

Esto merece su propio párrafo porque es la parte que decide si los ingresos se reanudan. Para cada método de pago:

1. Realice un pedido de prueba real (o de sandbox si la pasarela tiene uno).
2. Verifique que el pago se captura en el panel de la pasarela.
3. Verifique que el estado del pedido se actualiza correctamente en PrestaShop.
4. Pruebe los reembolsos si su flujo de trabajo los usa.
5. Compruebe las URL de webhook / IPN: la actualización puede cambiar la estructura de URL y se perderá las llamadas de retorno (callbacks) en silencio.

Envío

• Verifique que los transportistas muestran las tarifas correctas por zona.
• Pruebe los umbrales de envío gratuito.
• Para la consulta de tarifas en tiempo real vía API del transportista, confirme que la integración sigue autenticándose.
• Introducción de números de seguimiento, correos de notificación, impresión de etiquetas: todo ello.

Tareas cron

Cada tarea programada: abandono de carrito, sincronización de stock, generación de feeds, sitemap, tipos de cambio de moneda, scripts personalizados. PS 9 puede renombrar las URL de cron:

# Inspeccione las tareas actuales
crontab -l

# Acceda a cada URL de cron y confirme un 200
curl -s -o /dev/null -w "%{http_code}" "https://yourshop.com/modules/yourmodule/cron.php?token=XXXXX"

SEO

• Las URL amigables siguen resolviéndose.
• El sitemap se genera correctamente.
• robots.txt intacto.
• Las páginas de aterrizaje clave para el posicionamiento siguen existiendo en las mismas URL.
• Si algo se movió, configure redirecciones 301 el mismo día. Search Console no concede periodos de gracia.

Problemas habituales de la actualización

Pantalla en blanco

El más común. Página en blanco, sin error.

1. Active el modo de depuración en config/defines.inc.php:

   define('_PS_MODE_DEV_', true);

2. Recargue. El error real debería aparecer ahora.
3. Si sigue en blanco, el error se está tragando antes de la salida. Revise los registros:

   # Apache
   tail -50 /var/log/apache2/error.log
   
   # Nginx + PHP-FPM
   tail -50 /var/log/php-fpm/error.log
   
   # El propio registro de PrestaShop
   tail -50 /var/www/html/var/logs/prod.log

4. Los sospechosos habituales:
   • Memoria de PHP agotada: suba memory_limit a 512M.
   • Extensión de PHP ausente: instálela, reinicie PHP-FPM/Apache.
   • Permisos de archivo: chown -R www-data:www-data /var/www/html/var/.

Vuelva a desactivar el modo de depuración en cuanto haya encontrado el problema. Las páginas de depuración de PS 9 exponen las credenciales de la base de datos. Eso no es un simulacro.

Error 500 Internal Server Error

Normalmente .htaccess o la configuración de PHP tras la actualización.

# Omita .htaccess para aislar el problema
mv /var/www/html/.htaccess /var/www/html/.htaccess.bak

# Si la tienda carga, regenérelo desde el back office:
# Parámetros de la tienda → Tráfico y SEO → Generar archivo .htaccess

Confirme también:

• El mod_rewrite de Apache está activado: a2enmod rewrite && systemctl restart apache2
• El vhost permite AllowOverride All
• El PHP web es realmente 8.1+. La CLI suele ser más reciente que el pool web; confirme ambos.

Conflictos de módulos

El back office carga parcialmente, hay errores en secciones concretas, errores JS en la consola. La solución es el método de aislamiento:

1. Desactive todos los módulos no nativos. Si el back office también está roto, hágalo vía SQL:

   UPDATE ps_module SET active = 0 WHERE name NOT IN (
     'ps_banner','ps_contactinfo','ps_emailsubscription','ps_featuredproducts',
     'ps_imageslider','ps_linklist','ps_mainmenu','ps_searchbar',
     'ps_sharebuttons','ps_socialfollow','ps_wirepayment','ps_checkpayment'
   );

2. Vacíe la caché: rm -rf var/cache/*
3. Confirme que la tienda funciona solo con los módulos nativos.
4. Active los módulos de uno en uno, vaciando la caché entre cada uno.
5. El que la rompa es el que hay que actualizar, reemplazar o escalar al proveedor.

Traducciones ausentes

Algunas cadenas desaparecen o se renderizan como claves en crudo del tipo Modules.YourModule.SomeString.

• Exporte/importe su paquete de idioma desde Internacional → Traducciones.
• Para las traducciones de módulos, reinstalar el módulo lo soluciona, pero reinstalar puede restablecer la configuración, así que haga primero una copia de seguridad de la configuración.
• PS 9 se apoya con más fuerza en el sistema de traducción de Symfony. Los archivos de estilo antiguo en modules/yourmodule/translations/ a veces necesitan convertirse al nuevo formato.

Caché

La caché obsoleta está detrás de una sorprendente cantidad de informes del tipo «la actualización está rota» que en realidad no son actualizaciones rotas. Ante la duda, vacíelo todo:

# Borre y reconstruya
rm -rf var/cache/*
php bin/console cache:clear --env=prod --no-warmup
php bin/console cache:warmup --env=prod --no-optional-warmers

# Propiedad
chown -R www-data:www-data var/

# Y vacíe la caché de su navegador: el CSS/JS antiguo le perseguirá si no

Las imágenes no se muestran

• Regenere las miniaturas: Diseño → Configuración de imágenes → Regenerar miniaturas.
• Confirme que los permisos de img/ son correctos.
• Si usa una CDN, púrguela.
• Verifique que el formato de URL de la imagen coincide con lo que espera su tema: Hummingbird y Classic no se ponen de acuerdo en todas las rutas.

Inicio de sesión de administración roto

PS 9 cambió el hasher de contraseñas por el MigratingPasswordHasher de Symfony (bcrypt/argon2). En la mayoría de los casos las contraseñas existentes funcionan: el hasher migra automáticamente en el primer inicio de sesión. Si se queda bloqueado fuera:

# Restablecer la contraseña de administración: PS 9 requiere el hasher de contraseñas de Symfony
# NO use MD5 en crudo ni un UPDATE de SQL directo sobre el campo de contraseña

# En su lugar, use la CLI de PrestaShop (si está disponible):
php bin/console prestashop:user:change-password --email=admin@yourshop.com

# O cree un script PHP temporal para restablecer la contraseña correctamente
# (¡elimine este archivo inmediatamente después de usarlo!)

Nunca deje scripts de restablecimiento de contraseña en su servidor. Créelos, úselos, elimínelos: todo en una misma sesión. Un script de restablecimiento olvidado es una vulnerabilidad de seguridad.

Hacerlo usted mismo o contratar a alguien

Sea sincero sobre dónde se sitúa en la escala técnica. Una actualización fallida puede costar más en ingresos perdidos y confianza del cliente que lo que habría costado todo el trabajo en horas de desarrollo.

Probablemente puede hacerlo usted mismo si

• Va de PS 8.2 a 9.x: un salto de una versión.
• Menos de 10 módulos de terceros, todos confirmados como compatibles con PS 9.
• Tema estándar: Classic a Hummingbird, o un tema de pago que ya tenga versión para PS 9.
• Se siente cómodo en la línea de comandos y con las operaciones de base de datos.
• Tiene un entorno de staging operativo para probar primero.
• Sin overrides personalizados ni modificaciones del núcleo.

Contrate a alguien si

• Viene de PS 1.6.x o de una 1.7.x temprana.
• Tiene una tienda con muchos módulos, especialmente con overrides.
• Tema a medida que necesita portarse.
• Modificaciones del núcleo a medida o archivos de override en cualquier sitio.
• La línea de comandos y las operaciones de base de datos no son su trabajo diario.
• Los ingresos diarios son lo bastante significativos como para que un día de inactividad sea dinero de verdad.
• Ya lo intentó en staging y se quedó atascado.

Qué buscar en un desarrollador

• Experiencia específica en PrestaShop. No «PHP» ni «comercio electrónico». Un desarrollador de PHP genérico pasará horas facturables aprendiendo cosas que un especialista en PS ya sabe.
• Trabajo reciente en PS 9. Pida tiendas que hayan actualizado de verdad a 9.x. Symfony 6.4 tiene sus propias trampas; querrá a alguien que ya se las haya encontrado.
• Un plan por escrito. Auditoría → actualización en staging → pruebas → actualización en producción → monitorización. No «ya me las apañaré».
• Soporte posterior a la actualización. Los casos límite afloran 1-2 semanas después, cuando un flujo de trabajo antes silencioso por fin se ejecuta. Asegúrese de que esa ventana esté cubierta.

Costes aproximados (mercado 2025-2026)

• Actualización simple: PS 8.x a 9.x, pocos módulos, tema estándar: 500-1500 EUR.
• Actualización media: PS 1.7.x a 9.x, portado de tema a medida, cantidad moderada de módulos: 2000-5000 EUR.
• Actualización compleja: PS 1.6.x a 9.x, módulos a medida, reconstrucción completa: 5000-15000+ EUR.

Si alguien le cotiza 200 EUR por una actualización de PS 1.6 a PS 9, o no entiende el alcance o piensa cortar esquinas que pagará más tarde en otra moneda. Una actualización de versión mayor no es de un clic y listo.

Plan de marcha atrás (rollback)

Hizo copias de seguridad. Aquí tiene cómo usarlas cuando la actualización falla lo bastante mal como para que seguir hacia adelante no sea lo acertado.

Marcha atrás desde la actualización automática

Si usó 1-Click Upgrade y dejó que hiciera su propia copia de seguridad:

1. Módulos → 1-Click Upgrade.
2. Haga clic en Rollback y seleccione la copia de seguridad previa a la actualización.
3. El módulo restaura los archivos y la base de datos.

Si el back office es completamente inaccesible, lo hará a mano:

Marcha atrás manual de la base de datos

# Eliminar y volver a crear
mysql -u root -p -e "DROP DATABASE prestashop; CREATE DATABASE prestashop;"

# Restaurar
mysql -u root -p prestashop < ~/backup_pre_ps9_XXXXXXXX_XXXXXX.sql

# Docker
docker exec -i <your-shop>-db mysql -u root -p'PASSWORD' -e "DROP DATABASE prestashop; CREATE DATABASE prestashop;"
docker exec -i <your-shop>-db mysql -u root -p'PASSWORD' prestashop < ~/backup_pre_ps9_XXXXXXXX_XXXXXX.sql

Marcha atrás manual de los archivos

# Eliminar los archivos actualizados
rm -rf /var/www/html/*

# Restaurar desde la copia de seguridad
tar -xzf ~/prestashop_files_pre_ps9_XXXXXXXX_XXXXXX.tar.gz -C /

# Permisos
chown -R www-data:www-data /var/www/html/

# Caché
rm -rf /var/www/html/var/cache/*

Verifique la marcha atrás

1. El front office carga.
2. El inicio de sesión del back office funciona.
3. Los pedidos recientes se ven intactos.
4. Realice un pedido de prueba real a través del proceso de compra.
5. Desactive el modo mantenimiento una vez que esté satisfecho.

Tras una marcha atrás, no reintente la actualización de inmediato. Diagnostique primero. Lea los registros de la actualización, identifique el paso exacto que falló, reprodúzcalo en staging y arregle ahí la causa raíz. Reintentar en producción con los mismos requisitos previos es como las marchas atrás se convierten en daños permanentes.

Sin copia de seguridad: el caso de emergencia

Pasa. No a menudo, pero pasa. Las opciones cuando no hay copia de seguridad:

• Copias de seguridad del proveedor de hosting. Muchos hostings guardan instantáneas diarias durante 7-30 días. Abra un ticket de inmediato: expiran.
• Registros binarios de MySQL. Si los binlogs están activados, es posible la recuperación a un punto en el tiempo. Necesita un DBA competente.
• La propia copia de seguridad del módulo autoupgrade. Busque en /admin/autoupgrade/backup/. A menudo se olvida porque el back office está roto.
• Hacia adelante, no hacia atrás. Si la recuperación realmente no es posible, céntrese en arreglar la tienda actualizada en lugar de restaurar la antigua. A veces ese es el único camino.

La ruta de actualización, en resumen

1. Auditar: requisitos del servidor, cada módulo, compatibilidad del tema.
2. Copia de seguridad: base de datos vía mysqldump, archivos vía tar, configuración anotada.
3. Staging: ejecute la actualización completa primero en un entorno de staging. No «iré directo a producción».
4. Programar: ventana de bajo tráfico con un margen real para las cosas que se torcerán.
5. Actualizar: modo mantenimiento activado, ejecútelo, vacíe las cachés.
6. Probar: front office, back office, proceso de compra, pagos, envíos, correos. Cada uno.
7. Monitorizar: registros de errores durante 48 horas seguidas tras pasar a producción.
8. Limpiar: modo de depuración desactivado, archivos temporales eliminados, documentación actualizada para la siguiente persona.

PS 9 es genuinamente mejor que lo que vino antes. Symfony 6.4, base de PHP 8.1+, back office en Twig, la dirección de AdminAPI, Hummingbird como objetivo del front office: es la plataforma sobre la que llevábamos años queriendo lanzar módulos. La pega es que llegar hasta ahí desde una tienda PS 8 o PS 1.7 del mundo real requiere preparación. Sáltese la preparación y acabará escribiendo la sección de marcha atrás. Haga la preparación y la actualización en sí es la parte fácil.

Lecturas relacionadas

• Compatibilidad con PrestaShop 9 en nuestros módulos: estado módulo a módulo, útil para planificar el riesgo de terceros.
• PrestaShop 9.1, Hummingbird y proceso de compra multitransportista: contexto actual de PS 9.1 para los comerciantes.
• Paquete PrestaShop Compatibility: cómo nuestra capa de compatibilidad compartida gestiona las diferencias de versión en más de 140 módulos.
• Guía de resolución de problemas de PrestaShop: pasos de recuperación para pantallas en blanco, errores 500 y módulos rotos.
• Guía de rendimiento de PrestaShop y Performance Revolution: qué hacer después de la actualización cuando esté ajustando los Core Web Vitals.
• Ajuste de rendimiento en tiendas PrestaShop reales: limpieza de base de datos, caché y caché de página completa tras la migración.
• Guía de hooks y overrides: qué usar en lugar de los overrides que PS 9 hace más difíciles de mantener.
• Guía de la API de Webservice: para verificar los permisos de ERP e integraciones tras la actualización.
• Temas hijos de PrestaShop: el patrón a prueba de actualizaciones para las personalizaciones de Hummingbird.

Preguntas relacionadas

• El módulo muestra "This module requires PHP X.Y", ¿puedo instalarlo igualmente?
• ¿Cómo activo el modo debug en PrestaShop?
• He roto accidentalmente mi archivo .htaccess. ¿Cómo lo arreglo?
• La traducción del módulo no funciona, el texto sigue en inglés.
• Override no funciona, mi plantilla personalizada se ignora.
• Configurar redirecciones 301 en PrestaShop después de una migración