Un módulo de PrestaShop deja de funcionar tras una actualización

Cuatro familias de causas, no una

Un módulo de PrestaShop deja de funcionar después de una actualización y el síntoma varía: un bloque desaparece del front-office, una página de administración devuelve un error o se cae el sitio entero. Detrás de esos síntomas casi siempre hay una de estas cuatro causas: un hook perdido, un override en conflicto, una dependencia retirada del núcleo o una caché que se ha quedado incoherente.

Identificar primero la familia correcta ahorra horas.

Causa 1: el hook ya no está registrado

Síntoma: el módulo está activo, su configuración intacta, pero su contenido ya no aparece.

Los nombres de los hooks han ido cambiando con las versiones. Los antiguos, como hookHeader, pasaron a ser hookDisplayHeader, y algunos puntos de enganche han desaparecido. Un módulo antiguo se sigue instalando, pero ya no se muestra.

Compruebe el estado real en la base de datos:

SELECT h.name AS hook, m.name AS module, hm.position
FROM ps_hook_module hm
JOIN ps_hook h ON h.id_hook = hm.id_hook
JOIN ps_module m ON m.id_module = hm.id_module
WHERE m.name = 'nom_du_module';

Si falta el hook esperado, vuelva a registrarlo desde la pestaña Posiciones del back-office, o reinstalando el módulo, después de comprobar que su desinstalación no borra sus datos.

Mire también ps_hook_module_exceptions: una excepción añadida para ocultar un bloque en una página concreta acaba a veces ocultándolo en todas.

Existe el caso contrario: un módulo que se vuelve a registrar solo en un hook después de cada actualización, porque su método de instalación se ejecuta de nuevo. Entonces hay que corregir el módulo, no la base de datos.

Causa 2: un override en conflicto

Síntoma: error fatal que menciona una clase ya declarada, o comportamiento incoherente de alguna funcionalidad del núcleo.

PrestaShop solo admite un override por clase. Dos módulos que sobrecargan Cart o Product chocan, y el segundo gana en silencio.

El archivo que hay que conocer es var/cache/prod/class_index.php. Contiene la tabla de correspondencia entre cada clase y el archivo que la implementa. Mientras no se regenere, un override añadido o retirado no se tiene en cuenta, lo que produce errores fatales incomprensibles.

El reflejo tras cualquier cambio en override/:

rm -f var/cache/prod/class_index.php
rm -rf var/cache/prod/*

Para comprobar si la culpa es de un override, renombre temporalmente la carpeta override/ como override_off/ y recargue. Si el sitio vuelve, ya ha aislado la familia de causas.

Causa 3: una dependencia retirada del núcleo

Es la causa dominante desde PrestaShop 9 y la más brutal: error fatal inmediato por una clase que no se encuentra.

PrestaShop 9 ha retirado varias bibliotecas históricas:

• Swift Mailer, sustituido por Symfony Mailer;
• Guzzle, sustituido por Symfony HTTP Client;
• League Tactician, sustituido por Symfony Messenger;
• sensio/framework-extra-bundle, eliminado, de modo que las anotaciones de ruta y de plantilla dejan de funcionar.

Cualquier módulo que declare use GuzzleHttp\Client; o use League\Tactician\...; produce un error fatal nada más cargarse.

Localice los módulos afectados antes incluso de migrar:

grep -rl "GuzzleHttp\|League\\\\Tactician\|Swift_Mailer" modules/

Además, FrameworkBundleAdminController queda obsoleto en favor de PrestaShopAdminController, y los controladores de administración deben declararse ahora como servicios con inyección de dependencias. Un módulo cuyo controlador de back-office devuelve un error 500 tras pasar a la 9 casi siempre responde a este punto.

Por último, la autenticación del back-office se ha trasladado por completo a Symfony: los módulos de inicio de sesión único o de doble autenticación que se apoyaban en la cookie histórica dejan de funcionar.

Causa 4: una caché que se ha quedado incoherente

Síntoma: comportamiento errático, que cambia de una página a otra o desaparece en navegación privada.

Después de cualquier actualización, purgue en este orden:

rm -rf var/cache/prod/* var/cache/dev/*

Después, en Parámetros avanzados > Rendimiento, desactive temporalmente las opciones de combinación y compresión de archivos, vacíe la caché de Smarty y recargue. Esas opciones agrupan los archivos JavaScript y rompen con frecuencia los módulos que cargan sus scripts de forma asíncrona.

Revise también los permisos de var/: una caché que no se puede reescribir produce síntomas aleatorios muy difíciles de interpretar.

El método de puesta en servicio

1. Activar el modo debug, creando config/defines_custom.inc.php con define('_PS_MODE_DEV_', true); en lugar de modificar el archivo del núcleo. Así su ajuste sobrevivirá a la próxima actualización.
2. Leer los logs de var/logs/ y el registro de errores de PHP del alojamiento. El nombre de la clase que falta o del servicio que no se encuentra señala al módulo culpable.
3. Desactivar el módulo sospechoso en la base de datos, sin pasar por el back-office, que puede estar inaccesible:

UPDATE ps_module SET active = 0 WHERE name = 'nom_du_module';

4. Vaciar la caché, comprobar que el sitio vuelve y luego arreglarlo bien: actualizar el módulo con su editor o corregir el código.
5. Desactivar el modo debug antes de volver a abrir al público.

Evitar el próximo episodio

La regla que más tiempo ahorra: no actualizar nunca directamente en producción. Un entorno de preproducción, un plan de pruebas escrito que cubra el proceso de compra, los pagos, los correos y los transportistas, y un inventario de módulos al día bastan para convertir una avería en un no acontecimiento.

Para los módulos desarrollados a medida, nuestras reglas de desarrollo de un módulo a medida detallan qué hace que un módulo resista las actualizaciones.

¿Un módulo tiene bloqueada su tienda?

Volvemos a poner en servicio los módulos rotos y corregimos el código cuando el editor ya no da soporte. Consulte el desarrollo de módulos PrestaShop.