Migrazione a PrestaShop 9: Guida completa all'aggiornamento

Perché trattiamo PrestaShop 9 come una piattaforma diversa, non come un semplice aggiornamento di versione

Abbiamo migrato a PrestaShop 9 il nostro intero catalogo di 159 moduli e abbiamo aiutato i negozi dei clienti ad affrontare lo stesso percorso. Il riassunto onesto: PS 9 è la rottura più grande dai tempi del passaggio da 1.6 a 1.7. Il numero di versione sale di uno, ma la piattaforma sottostante avanza di una generazione. Pianifica di conseguenza. Per le ultime novità di ciò che è arrivato con la 9.1, consulta le nostre note di rilascio di PrestaShop 9.1.

Ultima revisione: 24 maggio 2026. I requisiti del server sono stati verificati a fronte della guida ufficiale di PrestaShop sulla configurazione del server e delle note sugli aggiornamenti core dei moduli per la 9.0. Le schermate in questa guida provengono da un vero negozio di sviluppo PrestaShop 9.1.0 che gestiamo per testare i moduli, non da mockup.

Le cose che percepirai davvero dopo l'aggiornamento:

Symfony 6.4 LTS sostituisce Symfony 4.4

PS 8 girava su Symfony 4.4. PS 9 fa il salto alla 6.4 LTS, con patch di sicurezza fino a novembre 2027. L'effetto pratico: ciclo di vita delle richieste più veloce, container DI moderno e accesso ai componenti Symfony su cui si è standardizzato il resto del mondo PHP. Per noi, in quanto autori di moduli, è la differenza tra scrivere PHP in stile 2018 e scrivere PHP in stile 2026.

PHP 8.1 come soglia minima, ma non si fermi lì

PS 9.0 richiede PHP 8.1 come minimo e supporta 8.2, 8.3, 8.4. PS 9.1 aggiunge 8.5. Il minimo è la soglia di compatibilità, non la raccomandazione. In ogni installazione PS 9 nuova che abbiamo realizzato nel 2026, abbiamo puntato a PHP 8.4 (PS 9.0) o 8.5 (PS 9.1), ma solo dopo che ogni modulo installato ha superato i test su quella versione di PHP in staging. Leggere "PHP 8.1+" come "imposta lo staging su PHP 8.1" lascia sul tavolo prestazioni reali.

Twig sta prendendo il sopravvento nell'amministrazione (ma non è finita)

La maggior parte del back office viene ora resa tramite Twig, ma la migrazione non è completa. I nuovi controller di amministrazione basati su Symfony usano Twig in modo nativo. I controller di amministrazione legacy continuano a funzionare, ma sono avvolti da un LegacyController Symfony che convoglia il loro output Smarty nel layout Twig. Quel wrapper è responsabile della maggior parte delle segnalazioni del tipo "la pagina di amministrazione del mio modulo viene resa ma i pulsanti sono spariti" che abbiamo visto durante le migrazioni a PS 9. Il fatto stesso che il wrapper esista ti dice che la migrazione è ancora in corso.

Hummingbird è la direzione, ma Classic non è ancora sparito

Hummingbird è il tema front-office moderno di PrestaShop. Su PS 9.1 è quello predefinito per le installazioni nuove. Sui negozi PS 9.0 che hanno fatto l'upgrade, il tema esistente rimane al suo posto, e alcune distribuzioni di PS 9 includono ancora Classic come tema disponibile. Quindi la vera domanda non è "Classic è installato?". È "i tuoi template, hook, asset e la strategia per il tema figlio sono pronti per Hummingbird?". Perché è lì che sei diretto, indipendentemente dal punto di partenza.

Hummingbird è costruito su Bootstrap 5.3, fa leva sulle proprietà personalizzate CSS ed è significativamente più leggero di Classic. Lo usiamo come base per le nuove realizzazioni da quando è uscito ed è una fondazione migliore per i Core Web Vitals rispetto a qualsiasi cosa PrestaShop abbia mai offerto prima. Abbinalo a Performance Revolution e un punteggio PageSpeed moderno è raggiungibile su un negozio reale, non solo su una demo.

Revisione completa della sicurezza

Symfony 6.4 porta un componente di sicurezza completamente rinnovato. L'hashing delle password usa bcrypt/argon2 tramite il MigratingPasswordHasher di Symfony. La protezione CSRF è più stringente. L'autenticazione passa attraverso il security bundle di Symfony anziché il percorso cookie legacy di PrestaShop. Diverse falle di SQL injection e XSS in vecchi percorsi di codice sono state chiuse. Per noi, questo significa meno ticket del tipo "per favore correggete questo singolo metodo" da parte dei clienti durante gli audit di conformità. Dopo l'aggiornamento, Security Revolution è il modulo che usiamo per l'irrobustimento dell'amministrazione, la policy 2FA e le modifiche all'integrità dei file.

PS 9 non è cosmetico. La piattaforma sotto il tuo negozio è stata ricostruita. La ricompensa è reale (più veloce, più sicura, più manutenibile) ma solo se la migrazione viene eseguita con metodo. Abbiamo visto aggiornamenti a PS 9 affrettati lasciare i negozi fuori uso per giorni. Ne abbiamo visti anche di ben preparati conclusi in un pomeriggio. La differenza sta interamente nella preparazione.

Prerequisiti: non tocchi il sito live finché ogni casella non è spuntata

La singola causa più frequente di aggiornamenti falliti per cui veniamo chiamati è "ho semplicemente lanciato 1-Click Upgrade e si è rotto tutto". Quasi sempre l'aggiornamento in sé non è fallito. Sono falliti i prerequisiti, ore prima, e nessuno li aveva verificati.

Metta il negozio in modalità manutenzione prima del lavoro rischioso

Back Office > Parametri del negozio > Generale > Manutenzione è il punto in cui disabiliti il negozio, inserisci in whitelist il tuo IP e scrivi il messaggio di manutenzione. Usala per le prove di staging e per la breve finestra di passaggio in live, non come sostituto dei test.

Questa è una vera schermata di un negozio di sviluppo PS9.1. Qui ciò che conta è il flusso di lavoro; non copiare l'IP o il testo di esempio alla cieca.

Requisiti del server

• PHP 8.1+: conferma con php -v. Per un ambiente di staging PS 9.1 nel 2026, testa su PHP 8.4 o 8.5 solo una volta che ogni modulo ha superato i controlli.
• MySQL 5.7+ o MariaDB 10.2+: conferma con mysql --version. Per una nuova infrastruttura, MySQL 8.0 o MariaDB 10.11 è l'obiettivo realistico.
• Estensioni PHP: intl, gd, curl, zip, mbstring, openssl, pdo_mysql, fileinfo, dom, json
• Composer 2.x
• memory_limit di almeno 256 MB: aumentalo temporaneamente a 512 MB per l'esecuzione dell'aggiornamento stesso se hai un catalogo di grandi dimensioni
• max_execution_time di 600+ secondi: i database di grandi dimensioni eseguono migrazioni lunghe

Verifica rapida da CLI:

# Versione di PHP
php -v

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

# Limiti di memoria ed esecuzione
php -i | grep -E "(memory_limit|max_execution_time)"

# Database
mysql --version

Obiettivi pratici per l'ambiente di runtime

Controlli l'ambiente di runtime reale, non la brochure dell'hosting

Su PS 9, Parametri avanzati > Informazioni mostra esattamente cosa sta eseguendo il negozio: versione PHP, versione del database, limite di memoria, versione del negozio, tema attivo. Fai uno screenshot di questa pagina prima di iniziare. Quando l'aggiornamento va storto e tu stai scambiando ticket con l'hosting alle 2 di notte, avere la situazione di riferimento pre-aggiornamento ti farà risparmiare ore.

Lo screenshot qui sotto proviene da un negozio di sviluppo PS 9.1.0 che esegue PHP 8.5, MySQL 8.0, 512 MB, Hummingbird.

Requisiti di versione di PrestaShop

• Devi trovarti su PS 8.1 o 8.2 prima di poter passare alla 9. Gli aggiornamenti diretti da 1.7.x o versioni precedenti non sono supportati. Punto.
• Sei su PS 1.7.x? Arriva prima alla 8.2, stabilizzala per una o due settimane, poi passa alla 9.
• Sei su PS 1.6.x? Smetti di leggere il percorso di aggiornamento. Ti serve una ricostruzione pulita. Non abbiamo mai visto riuscire un aggiornamento in loco da 1.6 a 9, vedi la sezione Installazione pulita.

Compatibilità dei moduli: la parte che decide se l'aggiornamento riesce

È qui che è andata storta la maggior parte degli aggiornamenti che abbiamo dovuto recuperare. Prima di toccare il pulsante di aggiornamento, devi sapere quali moduli sopravvivranno a PS 9 e quali no. Non "probabilmente", saperlo davvero.

1. Estrai l'elenco completo dei moduli dalla Gestione moduli.
2. Per ogni modulo di terze parti, contatta il fornitore e ottieni una risposta specifica per PS 9. "Funzionava su PS 8" non è la risposta che ti serve.
3. Per tutto ciò che non è confermato: decidi se aggiornare, sostituire o rimuovere. Non portarti dietro un'incognita.
4. Prima i moduli di pagamento. Un gateway di pagamento non confermato dopo l'aggiornamento significa zero ricavi finché non viene risolto.

Non dichiarare la compatibilità PS 9 di un modulo solo perché la categoria sembra simile o perché un modulo affine lo supporta. Abbiamo visto moduli che giravano bene su 8.2 andare in crash netto su 9.0 perché richiamano Tools::displayPrice(), un metodo che è stato rimosso, non deprecato. Testa, non sperare.

Faccia l'audit dei moduli installati nella vera Gestione moduli

Back Office > Moduli > Gestione moduli ti fornisce nomi, versioni, fornitori, stato e segnali di aggiornamento dei moduli installati. Costruisci il foglio di calcolo della migrazione a partire dallo stato reale del negozio, non dalla memoria o da una vecchia copia FTP.

I moduli di pagamento, checkout, spedizione, ERP e feed, inclusi strumenti per i feed come Smart Google Merchant Feed Manager, meritano la massima priorità perché un guasto in quell'area blocca i ricavi o l'elaborazione degli ordini.

Segnali di triage dei moduli che controlliamo davvero

Compatibilità del tema

• Stai usando Classic? Consideralo un debito di migrazione. Verifica se la tua distribuzione PS 9 lo include ancora, ma pianifica comunque Hummingbird o un tema PS 9 di terze parti.
• Stai usando un tema acquistato? Scrivi al fornitore prima di ogni altra cosa. Nessuna versione PS 9, nessuna tempistica chiara, inizia a portarlo ora.
• Tema personalizzato costruito su Classic? Rilavorazione significativa. La struttura dei template è cambiata abbastanza da rendere insufficiente un "cerca e sostituisci le classi Bootstrap".
• Per qualsiasi lavoro personalizzato d'ora in poi, la strada è un tema figlio di Hummingbird. Se modifichi il tema padre, perderai le tue modifiche al successivo aggiornamento del tema.

Quando farlo

• Mai durante un picco di vendite. Lo abbiamo visto tentare. Non finisce bene.
• Metà settimana, prima mattina, la finestra a più basso traffico che hai.
• Concediti almeno 48 ore di monitoraggio prima che arrivi il picco successivo.
• Piano di rollback pronto e testato: trattato più avanti in questa guida.

Faccia il backup di tutto. Sì, davvero.

Questo è il passaggio che tutti sorvolano. Non farlo. Il numero di chiamate di recupero del tipo "non pensavamo ci servisse un backup" che abbiamo ricevuto è l'unico motivo per cui questa sezione è così schietta. Se l'aggiornamento fallisce e tu non hai un backup, non hai un negozio.

Database

Il database è la parte che non puoi ricostruire. Prodotti, clienti, ordini, configurazioni, impostazioni dei moduli, tutto risiede lì. Usa mysqldump con i flag giusti:

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

# Database di grandi dimensioni (>1 GB): comprimi al volo
mysqldump -u root -p --single-transaction --quick --lock-tables=false prestashop | gzip > ~/backup_pre_ps9_$(date +%Y%m%d_%H%M%S).sql.gz

Negozi basati su 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

Cosa fanno quei flag, e perché li usiamo ogni volta:

• --single-transaction: snapshot coerente senza bloccare le tabelle. Essenziale per InnoDB su un negozio live.
• --quick: trasmette le righe in streaming anziché bufferizzarle. Senza, tabelle di prodotti o ordini di grandi dimensioni possono mandare in OOM il dump.
• --lock-tables=false: mantiene il negozio online durante il dump.

Ora verifica che il backup funzioni davvero. Un backup che non hai mai ripristinato è una speranza, non un backup:

# Ripristina in un database usa e getta e conta le righe
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;"

File

Fai il backup dell'intero albero di PrestaShop, PHP, temi, moduli, immagini caricate:

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

# Salta cache e log (vengono comunque rigenerati)
tar -czf ~/prestashop_files_pre_ps9_$(date +%Y%m%d_%H%M%S).tar.gz \
  --exclude='var/cache' \
  --exclude='var/logs' \
  /var/www/html/

Per Docker, il volume montato:

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

Conserva i backup in due posti. Il server stesso più un luogo esterno, la tua macchina locale, un bucket S3, un altro server, ovunque ma non sullo stesso disco del negozio live. Un backup sullo stesso disco che l'aggiornamento ha appena corrotto non è un backup.

Configurazioni che Le serviranno sapere in seguito

Annotale prima di iniziare. Quando l'aggiornamento è a metà e il back office è irraggiungibile, non vorrai tirare a indovinare:

• app/config/parameters.php: credenziali del database, configurazione del mailer, chiave dei cookie
• .htaccess: soprattutto le eventuali regole di rewrite personalizzate che hai aggiunto
• Impostazioni SMTP / email dal back office
• Chiavi API e URL dei webhook dei gateway di pagamento
• Voci dei cron job (esegui crontab -l e salvale)
• Qualsiasi configurazione di server personalizzata, blocchi Nginx, impostazioni del pool PHP-FPM, regole Cloudflare

Fai uno screenshot delle pagine di impostazioni critiche del back office mentre funzionano ancora. Un riferimento visivo di "com'era prima" vale tanto oro quanto pesa in termini di ticket di assistenza.

L'aggiornamento vero e proprio

Due percorsi legittimi: il modulo ufficiale 1-Click Upgrade, oppure un'installazione pulita con migrazione dei dati. Ciascuno ha il suo posto. Li abbiamo fatti entrambi. Nessuno dei due è "quello giusto", dipende interamente dalla forma del negozio che stai aggiornando.

Percorso 1: 1-Click Upgrade (modulo autoupgrade)

Il percorso ufficiale. Il modulo autoupgrade gestisce la sostituzione dei file, la migrazione del database e la pulizia post-aggiornamento. Nonostante il nome, non è letteralmente un solo clic. È un clic più una checklist.

Preparazione

1. Installa o aggiorna il modulo 1-Click Upgrade all'ultima versione dal Marketplace.
2. Apri Moduli → 1-Click Upgrade. Il modulo mostra la versione attuale e le destinazioni disponibili.
3. Esegui la checklist pre-aggiornamento. Verifica la compatibilità del server e segnala i problemi. Non saltare gli avvisi, risolvili prima.

Modalità manutenzione attiva

Dal back office: Parametri del negozio → Generale → Manutenzione → Abilita. Inserisci il tuo IP in whitelist. Non vorrai che un cliente piazzi un ordine mentre la migrazione del database sta riscrivendo ps_orders.

Lo esegua

1. Nel modulo 1-Click Upgrade, scegli la versione PS 9.x di destinazione.
2. Scegli "Aggiornamento maggiore" come canale.
3. Spunta queste opzioni:
   • Esegui il backup di file e database: sì, anche se lo hai già fatto. Cintura e bretelle.
   • Disattiva i moduli non nativi: sì. Questa è l'opzione che previene la maggior parte delle segnalazioni del tipo "il modulo X ha mandato in crash l'aggiornamento a metà strada".
   • Rigenera i template email: solo se non li hai personalizzati.
4. Fai clic su "Aggiorna PrestaShop ora".
5. Non chiudere la scheda. Non navigare altrove. Non aggiornare la pagina. Il modulo dialoga con se stesso tramite la sessione del browser. Interromperlo lascia un database migrato a metà che è davvero penoso da recuperare.

Da 5 minuti (negozio piccolo, pochi moduli) a oltre 30 minuti (catalogo ampio, molti moduli). Il log di avanzamento mostra ogni passaggio. Se resta fermo sullo stesso passaggio per più di 10 minuti, controlla i log degli errori PHP in un'altra scheda, ma non chiudere il browser con la forza.

Dopo che si è completato

# Svuota le cache: ogni volta, senza eccezioni
rm -rf var/cache/*

# Tramite CLI (preferibile)
php bin/console cache:clear --env=prod
php bin/console cache:warmup --env=prod

# Permessi: l'aggiornamento gira spesso con un utente diverso
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/

Riabiliti i moduli con metodo

Se hai lasciato che l'upgrader disattivasse i moduli non nativi (lo hai fatto, vero?), non abilitarli tutti in blocco. Abilitali uno alla volta:

1. Abilita il modulo.
2. Controlla front office e back office in cerca di errori.
3. Se funziona, passa al successivo. Se rompe qualcosa, disabilitalo e annota esattamente cosa si è rotto.

È lento. È anche l'unico modo per sapere quale modulo ha causato il problema quando qualcosa si rompe. Guardare un negozio rotto con 30 moduli abilitati e provare a indovinare quale sia il colpevole è un ottimo modo per perdere un intero pomeriggio.

Percorso 2: Installazione pulita con migrazione dei dati

A volte la mossa più pulita è ripartire da zero. Installa PS 9 ex novo in una nuova directory o su un nuovo server e migraci i tuoi dati. Più lavoro all'inizio, ma alla fine ottieni un negozio che non si porta dietro anni di debito accumulato.

Quando l'installazione pulita è la scelta giusta

• Sei su PS 1.6.x. L'aggiornamento in loco non è supportato. Non provarci.
• Il negozio attuale ha anni di override accumulati, moduli rimossi a metà e tabelle orfane nel database. Il tipo di negozio in cui ogni sviluppatore che lo guarda dice "io ripartirei da zero".
• Stai comunque cambiando tema.
• Il database è gonfio di carrelli abbandonati, vecchi log, dati morti.
• Hai già tentato aggiornamenti in loco in passato ed è andato male.

Il processo

1. Installa PS 9 ex novo in una nuova directory o su un server di staging.
2. Configura il tema (Hummingbird, o un tema di terze parti compatibile con PS 9).
3. Installa i moduli: solo versioni compatibili con PS 9.
4. Migra i dati, tramite importazione CSV o SQL diretto.
5. Riconfigura pagamenti, spedizioni, tasse, email.
6. Testa tutto sulla nuova installazione mentre il vecchio negozio resta live.
7. Cambia il DNS o sostituisci la document root quando sei soddisfatto.

Importazione CSV

L'importazione integrata di PrestaShop (Parametri avanzati → Importa) gestisce categorie, prodotti con combinazioni e giacenze, clienti, indirizzi, produttori, fornitori. Esporta dal vecchio negozio, pulisci i CSV, importali nel nuovo. Tedioso per i cataloghi di grandi dimensioni, ma il risultato è pulito.

Migrazione SQL diretta

Per dataset più grandi, l'SQL diretto è più veloce, ma solo se conosci davvero lo schema di PrestaShop:

# Esporta dal vecchio database le tabelle che ti servono
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

# Poi rivedi e adatta per le modifiche di schema tra le versioni
# Nomi delle colonne, strutture delle tabelle e chiavi esterne differiscono tra le versioni maggiori

La migrazione SQL presuppone che tu sappia leggere e correggere lo schema di PrestaShop con sicurezza. Se non ci riesci, usa l'importazione CSV o assumi qualcuno che ne sia capace. Abbiamo ripulito abbastanza migrazioni SQL fallite da sapere che il tempo risparmiato non vale il rischio quando le chiavi esterne sono silenziosamente in disaccordo.

Quale percorso?

Per la maggior parte dei negozi PS 8.x con moduli ragionevolmente mantenuti, l'aggiornamento automatico è la scelta giusta. L'installazione pulita è la risposta quando provieni da una versione molto vecchia o quando vuoi cogliere la ricostruzione come occasione per fare pulizia.

Cosa si rompe in PS 9 (il punto di vista dello sviluppatore)

Se mantieni moduli o hai codice personalizzato, questa è la sezione da leggere con attenzione. Il resto è operatività; qui è dove vive la vera rottura del codice.

I template di amministrazione Smarty vengono sostituiti

La singola rottura più grande. Su PS 8, i controller di amministrazione legacy rendevano i template Smarty direttamente. Su PS 9, i nuovi controller Symfony usano Twig in modo nativo, e i controller legacy sono avvolti dal LegacyController che convoglia il loro output Smarty nel layout Twig. La migrazione non è completa (il wrapper esiste perché i controller legacy rendono ancora Smarty internamente), ma la cornice circostante è Twig, ed è quello che rompe i template dei moduli che presupponevano il pieno controllo Smarty della pagina.

Cosa abbiamo riscontrato migrando i nostri controller di amministrazione:

• AdminController + moduli Smarty funzionano ancora, ma vengono resi all'interno del nuovo layout Twig tramite il livello di compatibilità. La maggior parte delle segnalazioni del tipo "la pagina si carica ma il form manca" risale a questo.
• Gli override dei template di amministrazione in override/controllers/admin/templates/ spesso non funzionano come ci si aspetta. Il wrapper non sempre li raccoglie.
• Le variabili Smarty assegnate in initContent() possono sparire, LegacyController avvolge il render in modo diverso, e in alcuni casi la variabile Smarty content va riassegnata esplicitamente.
• display() su AdminController non viene più chiamato. Il wrapper lo aggira. Se hai personalizzato display(), quel codice è morto su PS 9.

Gli override sono sempre meno praticabili

PrestaShop scoraggia gli override dalla 1.7. PS 9 stringe ulteriormente la vite:

• Gli override di classe funzionano ancora tecnicamente per le classi legacy in stile ObjectModel, ma la superficie si restringe man mano che altro core passa ai servizi Symfony.
• Gli override dei controller sono inaffidabili: il livello di routing di Symfony non sempre li carica.
• Gli override dei template in override/ per le pagine di amministrazione sono deprecati.
• Le alternative supportate sono hook, service decorator Symfony ed event subscriber. Stiamo sostituendo ogni override che possediamo con una di queste.

Se un modulo si appoggia pesantemente agli override, è la cosa nel tuo stack che con più probabilità si romperà durante l'aggiornamento a PS 9. Controlla sempre la directory override/ di ogni modulo installato prima di premere il grilletto.

Modifiche agli hook

• Diversi hook di amministrazione legacy vengono rimossi o rinominati man mano che quelle pagine di amministrazione migrano a Symfony.
• Esistono nuovi hook per le pagine di amministrazione basate su Symfony, trattati nella nostra guida agli hook.
• La maggior parte degli hook front-office funziona ancora, ma Hummingbird cambia o rimuove alcune assunzioni sul markup. I moduli che iniettano contenuto nei risultati di ricerca, nelle pagine di dettaglio dell'ordine, nelle finestre modali, nei blocchi prodotto o nel checkout, ritestali tutti.
• L'ordine di esecuzione degli hook può cambiare in casi limite. Se il tuo modulo dipende dall'eseguire prima o dopo un altro modulo sullo stesso hook, verificalo.

Modifiche ai controller di amministrazione legacy

Diversi pattern che funzionavano su PS 8 si comportano diversamente su PS 9:

• $this->l() è rimosso dai controller di amministrazione. Usa invece $this->module->l('string', 'ControllerClassName').
• Tools::displayPrice() è rimosso. Usa Context::getContext()->getCurrentLocale()->formatPrice($amount, $currencyIsoCode). Lo abbiamo incapsulato nel nostro pacchetto prestashop-compat, così abbiamo dovuto correggerlo una sola volta su 159 moduli.
• $this->meta_title, $this->fields_list, $this->bulk_actions ora devono essere assegnati dopo parent::__construct(). Il riferimento al modulo non è disponibile prima di quella chiamata.
• Smetti di codificare in modo fisso la directory del back office. I negozi la rinominano, i token cambiano, e le rotte Symfony andrebbero generate anziché ricucite insieme come stringhe.

Audit di un modulo per la prontezza a PS 9

Per ogni modulo installato, in ordine dai controlli più rapidi:

1. Dichiarazione di compatibilità del fornitore. Cerca un'affermazione esplicita su PS 9, la versione, non la categoria.
2. Override. Controlla dentro modules/yourmodule/override/. Qualsiasi cosa lì è un campanello d'allarme.
3. Chiamate a funzioni rimosse. Cerca nel PHP del modulo quelle più ovvie:
   • Tools::displayPrice(
   • $this->l( in qualsiasi file di controller di amministrazione
   • Classi AdminController che personalizzano display()
   • Percorsi della directory di amministrazione codificati in modo fisso
4. ps_versions_compliancy nel file PHP principale del modulo, il limite superiore include davvero la 9.x?

# Esegui dall'interno della directory del modulo

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

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

# Compatibilità dichiarata
grep -A2 "ps_versions_compliancy" *.php

Tratti gli aggiornamenti disponibili dei moduli come lavoro di migrazione

La schermata Aggiornamenti dei moduli mostra quali moduli necessitano già di attenzione prima dell'aggiornamento del core. Aggiornali prima in staging, poi esegui i test di checkout, pagamento, spedizione e ordine prima di toccare il sito live.

Evita un clic su "aggiorna tutto" in live durante la migrazione. Gli aggiornamenti dei moduli appartengono alla stessa matrice di test controllata dell'aggiornamento di PrestaShop stesso.

Migrazione del tema: Hummingbird è la direzione

PS 9.1 rende Hummingbird il tema predefinito per le nuove installazioni PS 9.1. I negozi PS 9.0 mantengono ciò che avevano. Alcune distribuzioni di PS 9 includono ancora Classic come opzione. Quindi pianifica a partire dallo stato reale del negozio, non da un'unica assunzione universale.

Parta da Tema e Logo

Su un vero negozio di sviluppo PS 9.1, Design > Tema e Logo mostra Hummingbird come tema corrente, Classic ancora disponibile e il nostro tema figlio di Hummingbird installato. Ecco perché l'unico consiglio sicuro è "fai prima l'audit del negozio attuale, poi decidi". Abbiamo visto piani di migrazione costruiti su assunzioni di negozi con solo Hummingbird andare in pezzi perché Classic era ancora attivo.

Se mantieni template personalizzati, lavora in un tema figlio di Hummingbird. Non modificare il tema padre.

Cosa c'è di diverso in Hummingbird

• Bootstrap 5.3 invece di Bootstrap 4. Nomi delle classi, sistema a griglia e classi di utilità sono cambiati. Il porting di un tema non è un cerca-e-sostituisci.
• Proprietà personalizzate CSS per la tematizzazione. Colori, spaziature, tipografia, tutte variabili, non partial SCSS.
• Meno JavaScript. Funzionalità native del browser al posto dei plugin jQuery dove possibile. Pagine più leggere.
• Sistema di build moderno. Webpack con tree shaking. Bundle più piccoli.
• Mobile-first. Il mobile è il layout di base, il desktop è il miglioramento. Classic era l'opposto. Il modello mentale è diverso.

Se è ancora su Classic

1. Passa a Hummingbird. Il più semplice. Crea un tema figlio per le tue personalizzazioni.
2. Acquista un tema compatibile con PS 9. Molti fornitori hanno rilasciato versioni PS 9.
3. Porta le tue personalizzazioni Classic in un tema figlio di Hummingbird. Il più lavoro, ma il miglior risultato a lungo termine.

Costruire un tema figlio di Hummingbird

Un tema figlio ti consente di personalizzare Hummingbird senza toccare il padre, così le tue modifiche sopravvivono agli aggiornamenti 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

Inserisci gli stili personalizzati in themes/my-child-theme/assets/css/custom.css. Hummingbird carica custom.css dal tema figlio con la priorità più bassa, così le tue regole prevalgono sul padre.

Per fare l'override di un template, copialo da themes/hummingbird/templates/ nello stesso percorso relativo all'interno del tuo tema figlio. Copia solo i file che devi modificare, tutto il resto ricade automaticamente sul padre.

Se ha acquistato il Suo tema

Scrivi al fornitore prima di fare qualsiasi altra cosa. Le domande che contano:

• Esiste una versione compatibile con PS 9?
• È basata su Hummingbird o è autonoma?
• La tua licenza esistente copre la versione PS 9?
• Qual è il percorso di migrazione dalla versione attuale?

Se il fornitore non può darti una versione PS 9 e non può darti una data, inizia a pianificare ora il tuo passaggio a Hummingbird. Aspettare sei mesi per scoprire che la risposta è ancora "no" è una posizione peggiore in cui trovarsi.

Checklist post-aggiornamento

L'aggiornamento è finito, il back office si carica, puoi accedere. Non metterlo ancora in produzione. Ogni funzione critica va verificata prima di rimuovere la pagina di manutenzione.

Front office

Back office

Gateway di pagamento

Questo merita un paragrafo a sé perché è la parte che decide se i ricavi ripartono. Per ogni metodo di pagamento:

1. Piazza un ordine di prova reale (o in sandbox se il gateway ne ha una).
2. Verifica che il pagamento sia incassato nella dashboard del gateway.
3. Verifica che lo stato dell'ordine si aggiorni correttamente in PrestaShop.
4. Testa i rimborsi se il tuo flusso di lavoro li usa.
5. Controlla gli URL dei webhook / IPN: l'aggiornamento può spostare la struttura degli URL e tu perderesti silenziosamente le callback.

Spedizione

• Verifica che i corrieri mostrino tariffe corrette per zona.
• Testa le soglie di spedizione gratuita.
• Per il calcolo tariffe in tempo reale tramite API del corriere, conferma che l'integrazione si autentichi ancora.
• Inserimento del numero di tracking, email di notifica, stampa delle etichette, tutto quanto.

Cron job

Ogni attività pianificata, abbandono del carrello, sincronizzazione delle giacenze, generazione dei feed, sitemap, tassi di cambio, script personalizzati. PS 9 può rinominare gli URL dei cron:

# Ispeziona i job attuali
crontab -l

# Richiama ogni URL di cron e conferma un 200
curl -s -o /dev/null -w "%{http_code}" "https://yourshop.com/modules/yourmodule/cron.php?token=XXXXX"

SEO

• Gli URL semplificati si risolvono ancora.
• La sitemap si genera correttamente.
• robots.txt intatto.
• Le pagine di destinazione chiave per il ranking esistono ancora agli stessi URL.
• Se qualcosa si è spostato, imposta i redirect 301 lo stesso giorno. Search Console non concede periodi di grazia.

Problemi comuni durante l'aggiornamento

Schermata bianca

Il più comune. Pagina vuota, nessun errore.

1. Attiva la modalità debug in config/defines.inc.php:

   define('_PS_MODE_DEV_', true);

2. Ricarica. L'errore reale dovrebbe ora comparire.
3. Se è ancora bianca, l'errore viene soppresso prima dell'output. Controlla i log:

   # Apache
   tail -50 /var/log/apache2/error.log
   
   # Nginx + PHP-FPM
   tail -50 /var/log/php-fpm/error.log
   
   # Il log proprio di PrestaShop
   tail -50 /var/www/html/var/logs/prod.log

4. I soliti sospetti:
   • Memoria PHP esaurita: aumenta memory_limit a 512M.
   • Estensione PHP mancante: installala, riavvia PHP-FPM/Apache.
   • Permessi dei file: chown -R www-data:www-data /var/www/html/var/.

Disattiva di nuovo la modalità debug nel momento in cui hai trovato il problema. Le pagine di debug di PS 9 espongono le credenziali del database. Non è un'esercitazione.

Errore 500 Internal Server Error

Di solito è .htaccess o la configurazione PHP dopo l'aggiornamento.

# Aggira .htaccess per isolare il problema
mv /var/www/html/.htaccess /var/www/html/.htaccess.bak

# Se il negozio si carica, rigeneralo dal back office:
# Parametri del negozio → Traffico e SEO → Genera il file .htaccess

Conferma inoltre:

• Apache mod_rewrite abilitato: a2enmod rewrite && systemctl restart apache2
• Il vhost consente AllowOverride All
• Il PHP web è davvero 8.1+. La CLI è spesso più recente del pool web, conferma entrambi.

Conflitti tra moduli

Il back office si carica parzialmente, errori in sezioni specifiche, errori JS in console. La soluzione è il metodo di isolamento:

1. Disabilita ogni modulo non nativo. Se anche il back office è rotto, fallo via 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. Svuota la cache: rm -rf var/cache/*
3. Conferma che il negozio funzioni con i soli moduli nativi.
4. Abilita i moduli uno alla volta, svuotando la cache tra l'uno e l'altro.
5. Quello che lo rompe è quello da aggiornare, sostituire o segnalare al fornitore.

Traduzioni mancanti

Alcune stringhe spariscono o vengono rese come chiavi grezze tipo Modules.YourModule.SomeString.

• Esporta/importa il tuo pacchetto lingua da Internazionale → Traduzioni.
• Per le traduzioni dei moduli, reinstallare il modulo risolve il problema, ma la reinstallazione può azzerare la configurazione, quindi fai prima il backup della config.
• PS 9 si appoggia di più al sistema di traduzioni di Symfony. I file in vecchio stile in modules/yourmodule/translations/ a volte vanno convertiti nel nuovo formato.

Cache

Una cache stantia è dietro a un numero sorprendente di segnalazioni del tipo "l'aggiornamento è rotto" che in realtà non sono aggiornamenti rotti. In caso di dubbio, svuota tutto:

# Cancella e ricostruisci
rm -rf var/cache/*
php bin/console cache:clear --env=prod --no-warmup
php bin/console cache:warmup --env=prod --no-optional-warmers

# Proprietà
chown -R www-data:www-data var/

# E svuota la cache del browser: vecchi CSS/JS ti perseguiteranno altrimenti

Immagini che non si visualizzano

• Rigenera le miniature: Design → Impostazioni delle immagini → Rigenera le miniature.
• Conferma che i permessi di img/ siano corretti.
• Se usi una CDN, svuotala.
• Verifica che il formato dell'URL delle immagini corrisponda a quello che il tuo tema si aspetta, Hummingbird e Classic non concordano su ogni percorso.

Accesso all'amministrazione non funzionante

PS 9 ha cambiato l'hasher delle password con il MigratingPasswordHasher di Symfony (bcrypt/argon2). Nella maggior parte dei casi le password esistenti funzionano, l'hasher migra automaticamente al primo accesso. Se sei bloccato fuori:

# Reimposta la password di amministrazione: PS 9 richiede l'hasher delle password di Symfony
# NON usare MD5 grezzo o un UPDATE SQL diretto sul campo della password

# Usa invece la CLI di PrestaShop (se disponibile):
php bin/console prestashop:user:change-password --email=admin@yourshop.com

# Oppure crea uno script PHP temporaneo per reimpostare la password correttamente
# (elimina questo file subito dopo l'uso!)

Non lasciare mai script di reset della password sul tuo server. Creali, usali, eliminali, tutto nella stessa sessione. Uno script di reset dimenticato è una vulnerabilità di sicurezza.

Fai-da-te o assumere qualcuno

Sii onesto su dove ti collochi sulla scala tecnica. Un aggiornamento fallito può costare di più in ricavi persi e fiducia dei clienti di quanto l'intero lavoro sarebbe costato in ore di sviluppo.

Probabilmente può fare da sé se

• Stai passando da PS 8.2 a 9.x: un salto di una versione.
• Meno di 10 moduli di terze parti, tutti confermati compatibili con PS 9.
• Tema standard: da Classic a Hummingbird, o un tema acquistato che ha già una versione PS 9.
• Ti trovi a tuo agio con la riga di comando e con le operazioni sul database.
• Hai un ambiente di staging funzionante su cui testare prima.
• Nessun override personalizzato o modifica al core.

Assuma qualcuno se

• Stai arrivando da PS 1.6.x o dalle prime 1.7.x.
• Hai un negozio carico di moduli, soprattutto con override.
• Tema personalizzato che necessita di porting.
• Modifiche personalizzate al core o file di override da qualche parte.
• La riga di comando e le operazioni sul database non sono il tuo lavoro quotidiano.
• I ricavi giornalieri sono abbastanza significativi da rendere un giorno di inattività una somma di denaro rilevante.
• Hai già provato in staging e ti sei bloccato.

Cosa cercare in uno sviluppatore

• Esperienza specifica su PrestaShop. Non "PHP" o "e-commerce". Uno sviluppatore PHP generico passerà ore fatturabili a imparare cose che uno specialista di PS conosce già.
• Lavoro recente su PS 9. Chiedi negozi che ha effettivamente aggiornato alla 9.x. Symfony 6.4 ha i suoi tranelli; vuoi qualcuno che ci sia già passato.
• Un piano scritto. Audit → aggiornamento in staging → test → aggiornamento in produzione → monitoraggio. Non "improvviserò".
• Supporto post-aggiornamento. I casi limite emergono 1-2 settimane dopo, quando un flusso di lavoro fino ad allora silenzioso finalmente si attiva. Assicurati che quella finestra sia coperta.

Costi indicativi (mercato 2025-2026)

• Aggiornamento semplice: da PS 8.x a 9.x, pochi moduli, tema standard: 500-1500 EUR.
• Aggiornamento medio: da PS 1.7.x a 9.x, porting di tema personalizzato, numero moderato di moduli: 2000-5000 EUR.
• Aggiornamento complesso: da PS 1.6.x a 9.x, moduli personalizzati, ricostruzione completa: 5000-15000+ EUR.

Se qualcuno ti propone 200 EUR per un aggiornamento da PS 1.6 a PS 9, o non capisce la portata del lavoro o ha intenzione di tagliare angoli che pagherai più avanti in una valuta diversa. Un aggiornamento di versione maggiore non è clicca-e-via.

Piano di rollback

Hai fatto i backup. Ecco come usarli quando l'aggiornamento fallisce in modo abbastanza grave da rendere il proseguire la scelta sbagliata.

Rollback dall'aggiornamento automatico

Se hai usato 1-Click Upgrade e gli hai lasciato fare il proprio backup:

1. Moduli → 1-Click Upgrade.
2. Fai clic su Rollback e seleziona il backup pre-aggiornamento.
3. Il modulo ripristina file e database.

Se il back office è completamente inaccessibile, dovrai farlo a mano:

Rollback manuale del database

# Elimina e ricrea
mysql -u root -p -e "DROP DATABASE prestashop; CREATE DATABASE prestashop;"

# Ripristini
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

Rollback manuale dei file

# Rimuovi i file aggiornati
rm -rf /var/www/html/*

# Ripristina dal backup
tar -xzf ~/prestashop_files_pre_ps9_XXXXXXXX_XXXXXX.tar.gz -C /

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

# Cache
rm -rf /var/www/html/var/cache/*

Verifichi il rollback

1. Il front office si carica.
2. L'accesso al back office funziona.
3. Gli ordini recenti risultano intatti.
4. Piazza un ordine di prova reale attraverso il checkout.
5. Disabilita la modalità manutenzione una volta soddisfatto.

Dopo un rollback, non ritentare subito l'aggiornamento. Diagnostica prima. Leggi i log dell'aggiornamento, identifica il passaggio esatto in cui è fallito, riproducilo in staging, correggi lì la causa radice. Ritentare la produzione con gli stessi prerequisiti è il modo in cui i rollback si trasformano in danni permanenti.

Nessun backup: il caso di emergenza

Capita. Non spesso, ma capita. Le opzioni quando non c'è alcun backup:

• Backup del provider di hosting. Molti host conservano snapshot giornalieri per 7-30 giorni. Apri subito un ticket, scadono.
• Log binari di MySQL. Se i binlog sono attivi, è possibile un ripristino point-in-time. Serve un DBA competente.
• Il backup del modulo autoupgrade stesso. Guarda in /admin/autoupgrade/backup/. Spesso dimenticato perché il back office è rotto.
• Avanti, non indietro. Se il recupero è genuinamente impossibile, concentrati sul riparare il negozio aggiornato anziché ripristinare quello vecchio. A volte è l'unica strada.

Il percorso di aggiornamento, in sintesi

1. Audit: requisiti del server, ogni modulo, compatibilità del tema.
2. Backup: database tramite mysqldump, file tramite tar, configurazioni annotate.
3. Staging: esegui l'intero aggiornamento prima su un ambiente di staging. Non "vado dritto in produzione".
4. Pianificazione: finestra a basso traffico con un margine reale per le cose che andranno storte.
5. Aggiornamento: modalità manutenzione attiva, eseguilo, svuota le cache.
6. Test: front office, back office, checkout, pagamenti, spedizione, email. Ognuno di essi.
7. Monitoraggio: log degli errori per 48 ore di fila dopo il passaggio in live.
8. Pulizia: modalità debug disattivata, file temporanei eliminati, documentazione aggiornata per la persona successiva.

PS 9 è davvero migliore di ciò che c'era prima. Symfony 6.4, soglia minima PHP 8.1+, amministrazione Twig, la direzione AdminAPI, Hummingbird come obiettivo del front-office. È la piattaforma su cui volevamo rilasciare moduli da anni. L'inghippo è che arrivarci da un vero negozio PS 8 o PS 1.7 richiede preparazione. Salta la preparazione e ti ritroverai a scrivere la sezione del rollback. Fai la preparazione e l'aggiornamento in sé è la parte facile.

Letture correlate

• Compatibilità PrestaShop 9 nei nostri moduli: stato modulo per modulo, utile per pianificare il rischio delle terze parti.
• PrestaShop 9.1, Hummingbird e checkout multi-corriere: il contesto attuale di PS 9.1 per i commercianti.
• Pacchetto PrestaShop Compatibility: come il nostro livello di compatibilità condiviso gestisce le differenze di versione su 159 moduli.
• Guida alla risoluzione dei problemi di PrestaShop: passaggi di recupero per schermate bianche, errori 500 e moduli rotti.
• Guida alle prestazioni di PrestaShop e Performance Revolution: cosa fare dopo l'aggiornamento quando ottimizzi i Core Web Vitals.
• Ottimizzazione delle prestazioni su negozi PrestaShop reali: database, cache e pulizia del full-page-cache dopo la migrazione.
• Guida a hook e override: cosa usare al posto degli override che PS 9 rende più difficili da mantenere.
• Guida alla Webservice API: per verificare i permessi di ERP e integrazioni dopo l'aggiornamento.
• Temi figli di PrestaShop: il pattern a prova di aggiornamento per le personalizzazioni di Hummingbird.

Domande correlate

• Il modulo mostra "This module requires PHP X.Y", posso comunque installarlo?
• Come abilito la modalità debug in PrestaShop?
• Ho rotto per errore il file .htaccess. Come lo sistemo?
• La traduzione del modulo non funziona. Il testo resta in inglese.
• Override non funzionante, il mio template custom viene ignorato.
• Configurare redirect 301 in PrestaShop dopo una migrazione