Modulo PrestaShop che non funziona più dopo un aggiornamento

Quattro famiglie di cause, non una

Un modulo PrestaShop non funziona più dopo un aggiornamento, e il sintomo cambia di volta in volta: un blocco è sparito dal front office, una pagina di amministrazione restituisce un errore, oppure l'intero sito va giù. Dietro questi sintomi si trova quasi sempre una di queste quattro cause: un hook perso, un override in conflitto, una dipendenza rimossa dal core o una cache rimasta incoerente.

Individuare subito la famiglia giusta fa risparmiare ore.

Causa 1: l'hook non è più registrato

Sintomo: il modulo è attivo, la sua configurazione è intatta, ma il contenuto non compare più.

I nomi degli hook sono cambiati nel corso delle versioni. I vecchi nomi come hookHeader sono diventati hookDisplayHeader, e alcuni punti di aggancio sono spariti. Un modulo datato continua a installarsi, ma non si mostra più.

Controlli lo stato reale nel database:

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';

Se l'hook atteso non c'è, lo registri di nuovo dalla scheda Posizioni del back office, oppure reinstallando il modulo — dopo aver verificato che la disinstallazione non ne cancelli i dati.

Guardi anche ps_hook_module_exceptions: un'eccezione aggiunta per nascondere un blocco su una pagina precisa finisce a volte per nasconderlo ovunque.

Esiste anche il caso opposto: un modulo che si registra da solo su un hook dopo ogni aggiornamento, perché il suo metodo di installazione viene rieseguito. Lì va corretto il modulo, non il database.

Causa 2: un override in conflitto

Sintomo: errore fatale che segnala una classe già dichiarata, oppure comportamento incoerente di una funzione del core.

PrestaShop ammette un solo override per classe. Due moduli che sovrascrivono Cart o Product entrano in collisione, e il secondo vince in silenzio.

Il file da conoscere è var/cache/prod/class_index.php. Contiene la tabella di corrispondenza fra ogni classe e il file che la implementa. Finché non viene rigenerato, un override aggiunto o rimosso non viene preso in considerazione, e ne derivano errori fatali incomprensibili.

Il riflesso da avere dopo ogni modifica in override/:

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

Per capire se la colpa è di un override, rinomini temporaneamente la cartella override/ in override_off/ e ricarichi. Se il sito torna, ha isolato la famiglia di cause.

Causa 3: una dipendenza rimossa dal core

È la causa dominante da PrestaShop 9 in poi, ed è la più brutale: errore fatale immediato su una classe introvabile.

PrestaShop 9 ha rimosso diverse librerie storiche:

• Swift Mailer sostituito da Symfony Mailer;
• Guzzle sostituito da Symfony HTTP Client;
• League Tactician sostituito da Symfony Messenger;
• sensio/framework-extra-bundle eliminato, quindi le annotazioni di rotta e di template non funzionano più.

Qualsiasi modulo che dichiara use GuzzleHttp\Client; o use League\Tactician\...; produce un errore fatale già al caricamento.

Individui i moduli coinvolti prima ancora di migrare:

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

Inoltre FrameworkBundleAdminController è deprecato a favore di PrestaShopAdminController, e i controller di amministrazione vanno ormai dichiarati come servizi con dependency injection. Un modulo il cui controller di back office restituisce un errore 500 dopo il passaggio alla 9 rientra quasi sempre in questo caso.

Infine, l'autenticazione del back office è interamente portata su Symfony: i moduli di single sign-on o di autenticazione a due fattori che si appoggiavano al vecchio cookie smettono di funzionare.

Causa 4: una cache rimasta incoerente

Sintomo: comportamento erratico, che cambia da una pagina all'altra o sparisce in navigazione anonima.

Dopo ogni aggiornamento svuoti in quest'ordine:

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

Poi, in Parametri avanzati > Prestazioni, disattivi temporaneamente le opzioni di unione e compressione dei file, svuoti la cache Smarty e ricarichi. Quelle opzioni raggruppano i file JavaScript e mandano regolarmente in crisi i moduli che caricano i propri script in modo asincrono.

Controlli anche i permessi su var/: una cache che non può essere riscritta produce sintomi casuali difficilissimi da interpretare.

Il metodo per rimettere in servizio

1. Attivare la modalità debug, creando config/defines_custom.inc.php con define('_PS_MODE_DEV_', true); invece di modificare il file del core. In questo modo l'impostazione sopravvive al prossimo aggiornamento.
2. Leggere i log in var/logs/ e nel registro errori PHP dell'hosting. Il nome della classe mancante o del servizio introvabile indica il modulo colpevole.
3. Disattivare il modulo sospetto nel database, senza passare dal back office, che potrebbe essere irraggiungibile:

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

4. Svuotare la cache, verificare che il sito torni, poi risolvere per bene: aggiornamento del modulo presso il suo editore, oppure correzione del codice.
5. Disattivare la modalità debug prima di riaprire al pubblico.

Evitare il prossimo episodio

La regola che fa risparmiare più tempo: non aggiornare mai direttamente in produzione. Un ambiente di staging, un collaudo scritto che copra il checkout, i pagamenti, le email e i corrieri, e un inventario aggiornato dei moduli bastano a trasformare un guasto in un non evento.

Per i moduli sviluppati su commissione, le nostre regole per sviluppare un modulo su misura spiegano che cosa rende un modulo resistente agli aggiornamenti.

Un modulo blocca il suo negozio?

Rimettiamo in funzione i moduli rotti e correggiamo il codice quando l'editore non segue più. Veda lo sviluppo di moduli PrestaShop.