Gestione delle modifiche al database durante gli aggiornamenti dei moduli in PrestaShop

C’è un tipo di richiesta di assistenza che ho imparato a temere. Un commerciante aggiorna un modulo; l’aggiornamento sembra andare a buon fine, poi qualcosa smette di funzionare. Mai l’intero negozio. Una pagina del controller di PrestaShop che non funziona correttamente, o un valore di configurazione che non viene salvato, o una colonna di un elenco prodotti che si è svuotata. Quando controllo, il codice del modulo è aggiornato alla nuova versione, ma il database sottostante è ancora quello vecchio.

Questo articolo si propone di affrontare proprio questa lacuna. Un modulo PrestaShop non è solo il codice PHP che hai distribuito, ma include anche le tabelle e le colonne che il codice PHP si aspetta di trovare. Se si salta l’aggiornamento del database di PrestaShop, che dovrebbe essere incluso in ogni nuova versione del codice, si ottiene un modulo installato, apparentemente funzionante, ma in realtà errato.

L’ho fatto a me stesso più di una volta. Quello che segue è ciò che ho imparato a riguardo aggiornamenti del database del modulo PrestaShop, nel modo più difficile.

1.0 Come gli aggiornamenti dei moduli PrestaShop gestiscono effettivamente il database

Qui circolano molte supposizioni, e alcune sono errate.

Inserisci una nuova versione in /moduli/ e la tua routine di installazione non viene eseguita di nuovo. Tabelle intatte. Cosa succede invece: PrestaShop legge il modulo aggiornamento / cartella, trova i file denominati aggiornamento- .php si posiziona tra la versione registrata e quella dichiarata dalla classe del tuo modulo, ed esegue entrambe in sequenza.

Un negozio con versione 1.9.0 che riceve la versione 2.1.0 esegue tre script, in sequenza.

Da ciò derivano tre cose, e tutte e tre sono importanti per modifiche al database di PrestaShop.

La versione presente nella tabella `module` è la fonte di verità. Non quello presente nel file di classe principale. PrestaShop li legge entrambi. Agisce su quello registrato, ed è quello che determina quanti script di aggiornamento verranno eseguiti.

Il tuo metodo `install()` è valido solo per le nuove installazioni. Diciamo che la versione 2.0 ha bisogno di una nuova tabella. Inseriscila in installare() Chiunque passi alla versione 2.0 da zero è coperto. Il negozio che ha la versione 1.9 non riceve nulla, perché l’installazione è stata eseguita un anno fa e non verrà più eseguita.

Un singolo errore blocca tutto. Rientro falso Quando si esegue un aggiornamento, accadono tre cose: PrestaShop si blocca, registra la versione che ha causato l’errore e disabilita il modulo. Non è possibile passare allo script successivo. Questo comportamento è intenzionale, anche se significa che una modifica dello schema applicata solo parzialmente non risolve completamente il problema, ma lo disabilita.

Migliori attivazione dell’aggiornamento automatico per i moduli Questa pagina illustra le regole per la denominazione dei file. Leggetela attentamente una volta, anziché cercarla a memoria.

La trappola di denominazione della funzione di aggiornamento

Questo mi è costato un pomeriggio. modulo_di_aggiornamento_2_0_1 or modulo di aggiornamento201 funziona come nome di funzione e PrestaShop cerca entrambi. Inoltre, prima di includere il file, verifica se uno di questi nomi esiste già. Se lo trova, il file viene contrassegnato come duplicato e ignorato.

Copiare un vecchio script di aggiornamento come modello è esattamente il modo in cui le persone arrivano a questo punto. Il nome al suo interno non viene mai modificato. Non viene eseguito alcun aggiornamento e il messaggio di errore non fornisce molte informazioni.

2.0 Migrazione del database di PrestaShop: cosa va storto nei negozi reali

Tutto ciò è accaduto nei negozi in cui ho lavorato.

Modifiche allo schema del database di PrestaShop che si spostano tra le installazioni

La versione 2.0 necessita di una nuova colonna, quindi si aggiorna installare() e scrivere uno script di aggiornamento. Entrambe le opzioni sono corrette. Dopo tre versioni, qualcuno rinomina la cartella del modulo o un rivenditore reinstalla. In alcune installazioni, install() ha creato quella colonna. In altre, l’ha fatto il percorso di aggiornamento. Due definizioni, che si discostano, e ora un singolo numero di versione le copre entrambe.

Quindi la definizione risiede in un singolo metodo chiamato da entrambi i percorsi. Le modifiche allo schema del database di PrestaShop non possono derivare se ce n’è solo uno.

Script di aggiornamento che presuppongono un punto di partenza pulito

ALTER TABLE … ADD COLUMN Se si verifica un errore su una colonna già esistente, la funzione restituisce false e il modulo viene disabilitato. Se si interrompe un aggiornamento precedente, si ripristina un backup parziale o si sincronizza due volte dall’area di staging, si finisce nel problema.

Ogni modifica dello schema che scrivo ora controlla prima. L’aggiunta di una colonna significa un MOSTRA COLONNE prima, creare una tabella significa MOSTRA LE TABELLE, un indice significa MOSTRA INDICE. Poche righe e lo script sopravvive a una seconda esecuzione. Questo è importante, perché il database di uno sconosciuto può trovarsi in qualsiasi stato. C’è SE NON ESISTE in entrambi MySQL e MariaDBma solo su alcune operazioni, quindi il controllo esplicito funziona meglio.

Multistore: righe di configurazione scritte solo per un singolo negozio

Silenzioso e insidioso, questo. Nella nuova versione è arrivata un’impostazione per singolo negozio. Riga predefinita creata dallo script di aggiornamento, testata dallo sviluppatore, tutto sembra a posto. Ma è stata scritta una riga, per il negozio in questione, e il commerciante ne gestisce quattro.

Ora mancano tre negozi. A seconda di come il tuo codice lo interpreta, ricevi un avviso PHP, un valore vuoto trattato come un’impostazione reale o uno spazio vuoto dove dovrebbe esserci un prezzo. documentazione multi-negozio copre le regole di contesto. Esegui un ciclo su ogni ID negozio in qualsiasi aggiornamento che coinvolga la configurazione o i dati specifici del negozio.

In un’installazione a negozio singolo, questo bug è invisibile.

ALTER TABLE blocca le grandi tabelle dei cataloghi

L’aggiunta di una colonna a una tabella di 400,000 righe non è mai istantanea. A seconda dell’operazione, della versione di MySQL e del motore di archiviazione, potrebbe essere necessario copiare l’intera tabella. In un negozio online attivo, durante l’orario di negoziazione, questo blocco dura abbastanza a lungo da essere notato dai clienti.

Quindi, prima di scrivere la migrazione, verifico le dimensioni della tabella. Se è grande: finestra di manutenzione, oppure ristrutturazione per evitare la ricostruzione.

La chiave di configurazione senza valore predefinito

Quello che vedo più spesso nei moduli di altri, e non prevede l’uso di tabelle.

Aggiungi un’impostazione nella nuova versione. Il modulo di amministrazione la legge. Così come il front controller. Entrambi sono stati scritti su una macchina in cui la pagina delle impostazioni era già stata salvata almeno una volta. Quindi la chiave esiste e tutto sembra a posto. Distribuiscila e ogni installazione esistente sta leggendo un Configurazione chiave che nessuno ha mai scritto.

Ciò che ritorna è falsoIl tuo valore predefinito non viene mai visualizzato, né una stringa vuota che potresti almeno verificare. Da lì viene utilizzato come numero o passato a una funzione che richiedeva una stringa. Con la modalità di debug disattivata, spesso te la cavi: il commerciante vede una pagina leggermente errata e non ci pensa due volte. Con la modalità di debug attivata, l’errore si manifesta come una notifica o un errore di tipo. Ed è così che ti arriva la notizia che “il modulo si blocca in modalità di debug”, quando in realtà solo la modalità di debug è effettivamente coinvolta.

Lo stesso codice, con e senza l’impostazione predefinita.

La soluzione è banale. Ogni nuova chiave di configurazione ha il suo valore predefinito scritto nello script di aggiornamento, per ogni negozio, distribuito insieme al codice che lo legge. Leggetelo con attenzione, perché non potete essere certi che l’aggiornamento sia andato a buon fine.

Migrazione del database del modulo PrestaShop rispetto alla modifica dello schema.

Le modifiche allo schema sono la parte più semplice. La parte difficile inizia quando cambia il significato dei dati esistenti: dividere una colonna in due, spostare un campo CSV in una tabella correlata, ricodificare uno stato.

È lì che ho visto i danni maggiori. Un lavoro mal riuscito ALTER TABLE Fallisce rumorosamente; una trasformazione dei dati mal riuscita ha successo e scrive cose senza senso. Una migrazione del database di un modulo PrestaShop che sposta i dati richiede un conteggio prima e dopo, quindi un confronto. Meglio scoprirlo all’interno dello script di aggiornamento che da un commerciante tre settimane dopo.

Migliori pratiche per l’aggiornamento del modulo PrestaShop 3.0 che difenderei senza esitazione

Coloro che mi hanno salvato:

Rendere ogni migrazione idempotente

Nulla dovrebbe cambiare nella seconda esecuzione che la prima esecuzione non abbia già gestito. Ottieni quella proprietà e un’intera categoria di problemi di supporto scompare, perché lo stato del database smette di essere qualcosa che devi stabilire prima. Prima di scrivere SQL grezzo sulle tabelle principali, PrestaShop note sui livelli del database valgono un’ora.

La versione protetta sopravvive a una seconda esecuzione.

Registra ogni errore invece di restituire automaticamente false

Un nudo restituire false Questo è sufficiente perché PrestaShop si fermi e disabiliti il ​​modulo. Non è sufficiente per te. Quindi, completa il lavoro. Cattura tutto ciò che ne deriva e passalo a PrestaShopLogger con il nome e la versione del modulo allegati. Altrimenti, un commerciante segnala un aggiornamento fallito e tu vai a tentoni.

Su PHP 7 e versioni successive, cattura Errore così come Eccezione. Ricevi un errore di tipo nel tuo codice di migrazione e arriva come un Errore, quindi un gestore che guarda solo per Eccezione lo lascia passare.

Supporta ogni versione che hai mai rilasciato

Un commerciante può utilizzare qualsiasi versione rilasciata. Chi passa dalla versione 1.4 alla 3.0 esegue tutti gli script intermedi, in ordine, quindi ognuno deve funzionare con lo schema lasciato in eredità dal precedente. Ecco perché i vecchi file di aggiornamento rimangono nel modulo. Chi è rimasto indietro di due anni non ha altra via d’uscita.

Eseguire il test sull’ambiente di staging, non su un’installazione locale pulita.

Una nuova installazione della nuova versione non dimostra nulla riguardo all’aggiornamento. Quello che dovresti fare invece è: installare la vecchia versione, inserire dati realistici e poi aggiornare. Anche su più store, se lo supporti.

Meglio ancora: prendi una copia di un negozio reale e passa l’aggiornamento attraverso quello. La tua installazione locale ha dati puliti e quattro prodotti, ecco perché non mostra nulla. Un negozio reale ha importazioni incomplete, righe lasciate da un modulo disinstallato due anni fa, colonne aggiunte a mano da un precedente sviluppatore, un catalogo abbastanza grande da ALTER TABLE ci vuole un po’ di tempo.

Poi c’è la questione dei tempi. È più facile capire se un aggiornamento richiede sei minuti, basandosi su dati reali, quando si prenota una finestra di manutenzione, piuttosto che alle undici di venerdì.

Eseguite un backup prima di apportare modifiche allo schema e comunicatelo.

Prima di un aggiornamento di un modulo, non viene creata alcuna istantanea delle tabelle. Né da PrestaShop, né da nessun altro sistema. Quindi, se il commerciante non ha un backup e la migrazione si interrompe a metà della trasformazione dei dati, quei dati andranno persi. È meglio specificarlo nel registro delle modifiche, piuttosto che scoprirlo insieme.

Recupero di un aggiornamento del database di PrestaShop non riuscito

Aggiornamento non riuscito su un negozio online; modulo disabilitato. All’incirca in quest’ordine:

Scopri quale versione ha fallito. Questa operazione viene registrata e, se hai scritto un messaggio di log, sarà presente anche quello. Insieme, saprai quale script aprire e quali modifiche sono state applicate prima dell’interruzione.

Verifica lo schema effettivo, non il numero di versione. Tutto l’ modulo La tabella conosce ciò che l’ultimo aggiornamento riuscito ha scritto. Le tabelle reali sono dove si trova la risposta, confrontate con qualunque cosa lo script fallito stesse cercando di fare.

Puntare in avanti, non indietro. Ripristinare la versione precedente è allettante, ma di solito sbagliato, perché gli script precedenti sono già stati eseguiti e rieseguirli su uno schema parzialmente modificato trasforma un problema in tre. Scrivi una migrazione correttiva dallo schema attuale a quello corretto.

Quindi bisogna capire perché la migrazione non è stata idempotente. Questo è il vero bug.

Una breve lista di controllo prima di rilasciare un aggiornamento del modulo

Ecco la lista che gestisco:

1. Versione principale della classe, la più alta aggiornamento-*.php file: corrispondono?
2. Ogni funzione di aggiornamento prende il nome dalla versione del proprio file?
3. Ogni modifica allo schema verifica prima se è già stata applicata.
4. Ogni configurazione viene scritta ciclicamente su tutti i negozi?
5. Ogni nuova chiave di configurazione riceve un valore predefinito per le installazioni esistenti?
6. Hai già effettuato una prova su una riproduzione di un negozio reale?
7. È stata installata la vecchia versione, sono stati aggiunti i dati e poi è stato effettuato l’aggiornamento?
8. Stesso percorso su più negozi?
9. Qualcosa di utile registrato prima di ogni restituire false?
10. attraente Errore così come Eccezione?
11. Vecchi file di aggiornamento sono ancora presenti per i commercianti con versioni precedenti di diverse settimane?
12. Registro delle modifiche che invita i commercianti a fare un backup?
13. Su un tavolo grande, quanto è lungo? ETÀ stai tenendo un lucchetto?

Gli elementi 6 e 7 sono quelli che le persone saltano, e insieme riescono a cogliere la maggior parte del problema.

Conclusione

Aggiornamento del modulo PrestaShop I problemi sono scomodi per un motivo: non c’è alcun preavviso. Il modulo segnala la sua nuova versione senza problemi. La pagina di amministrazione si carica. Nessun log, a meno che non li abbiate scritti voi. Nel frattempo, il vostro codice si aspetta una cosa, il database ne contiene un’altra, e quest’ultima rimane invariata finché qualcuno non utilizza la funzionalità che si trova nel mezzo.

Tratta lo schema come parte della release. Scrivi migrazioni che sopravvivano a una seconda esecuzione. Registra cosa è successo. Mettilo in staging prima che lo faccia qualsiasi commerciante. Lato framework, PrestaShop documentazione per lo sviluppo del modulo è il punto di partenza.

Se hai domande o hai bisogno di assistenza per le prestazioni o la migrazione del tuo sito web, i nostri esperti sono qui per aiutarti. Contatta il team di Knowband all’indirizzo [email protected] Oggi stesso potrete usufruire di plugin per e-commerce affidabili e personalizzati in base alle vostre esigenze.