OpenCart è stato per anni la scelta di molti piccoli e-commerce: leggero, gratuito, facile da installare su un hosting condiviso. Tanti negozi aperti tra il 2012 e il 2017 girano ancora su OpenCart 1.5 o 2.x, con decine di estensioni che modificano il core attraverso file XML gestiti da vQmod o da OCMOD. Finché nessuno tocca niente il negozio funziona. Poi arriva il momento di cambiare server, o di passare a PHP 8, e ci si accorge che il negozio non si può aggiornare un pezzo alla volta.
In questo articolo spieghiamo come funzionano vQmod e OCMOD, perché le modifiche XML sono il punto più fragile di ogni aggiornamento, come si porta una modifica da un sistema all’altro e quali sono le strade verso OpenCart 3.0 e 4.1, le due serie che a ottobre 2026 ricevono ancora rilasci. I dati sulle versioni vengono dal codice sorgente pubblicato nel repository ufficiale di OpenCart.
Le versioni di OpenCart oggi
Le serie 1.5 e 2.x non ricevono rilasci da anni: le ultime versioni sono la 1.5.6.4 e la 2.3.0.2. Nell’agosto 2026 il progetto ha pubblicato insieme la 3.0.5.1 e la 4.1.0.4, quindi oggi convivono due serie mantenute. Entrambe, nel controllo dei requisiti dell’installer, chiedono almeno PHP 8.1. Le versioni precedenti erano meno esigenti: le prime 3.0 si installavano da PHP 5.4, le 3.0.4.x da PHP 7.3, la 4.0.2.3 da PHP 8.0.
Per un negozio su 1.5 o 2.x questo significa due salti in uno: cambiare versione di OpenCart e portare tutto il codice personalizzato a PHP 8. Le estensioni scritte per PHP 5 usano spesso funzioni rimosse nelle versioni 7 e 8, come le vecchie funzioni mysql_* o each(), e vanno corrette a prescindere dal sistema di modifica che usano. Ne parliamo nel dettaglio nell’articolo sulle funzioni rimosse in PHP 8.
Come funzionano vQmod e OCMOD
OpenCart 1.5 non aveva un meccanismo per estendere il core senza modificarne i file. vQmod, un progetto esterno, ha risolto il problema in modo ingegnoso: invece di cambiare i file originali, legge delle regole scritte in XML, crea una copia modificata di ogni file interessato in una cartella di cache e fa caricare a OpenCart quella copia. Con la 2.0 OpenCart ha integrato nel core un sistema analogo, OCMOD, con una sintassi simile e la cache nella cartella di storage.
La serie 4.0 ha tolto OCMOD dal core e ha puntato tutto sul sistema di eventi, con cui un’estensione si aggancia a punti precisi del flusso, prima o dopo un controller, un modello o una vista, senza toccare il codice originale. Nella 4.1 OCMOD è tornato, con le modifiche contenute nel pacchetto dell’estensione e applicate nella cartella extension/ocmod. In entrambe le versioni della serie 4 ogni estensione vive nella propria cartella sotto extension/, con il proprio namespace PHP e un file install.json nel pacchetto .ocmod.zip.
Perché le modifiche XML si rompono
Una regola vQmod o OCMOD dice in sostanza: cerca questa riga in questo file e aggiungi questo codice prima o dopo. Funziona finché il file del core resta identico. Quando OpenCart cambia versione, i file vengono riscritti: cambiano i percorsi, i nomi delle variabili, l’indentazione, a volte l’intera logica. La ricerca non trova più la riga e la modifica non viene applicata, a volte con un avviso nel log, a volte in silenzio.
Il problema si moltiplica con il numero di estensioni. Due modifiche che cercano la stessa riga entrano in conflitto, e l’ordine in cui vengono applicate decide il risultato. Su un negozio con trenta o quaranta file XML, accumulati negli anni da fornitori diversi, l’aggiornamento diventa difficile da prevedere. Per questo il primo passo è sempre un inventario delle modifiche:
- i file XML di vQmod nella cartella
vqmod/xmle i log invqmod/logs; - le modifiche OCMOD elencate nel pannello, alla voce delle modifiche, e i file
*.ocmod.xmlpresenti nella cartellasystem; - i file del core modificati a mano, che si trovano confrontando l’installazione con il pacchetto originale della stessa versione;
- i temi, che nella 1.5 e nella 2.x contengono spesso logica oltre alla grafica.
Da vQmod a OCMOD: un esempio
Le due sintassi sono vicine, e convertire una regola semplice è un lavoro meccanico. Immaginiamo una piccola modifica che rende disponibile alla pagina prodotto il codice SKU. In vQmod, su OpenCart 1.5, la posizione si indica nel tag di ricerca; in OCMOD, su OpenCart 3.0, si indica nel tag di aggiunta, e il file si identifica con path invece di name:
<!-- vQmod per OpenCart 1.5: file in vqmod/xml/mostra_sku.xml -->
<modification>
<id>Mostra SKU nella pagina prodotto</id>
<version>1.0</version>
<vqmver>2.6.0</vqmver>
<author>esempio</author>
<file name="catalog/controller/product/product.php">
<operation>
<search position="after"><![CDATA[$this->data['model'] = $product_info['model'];]]></search>
<add><![CDATA[$this->data['sku'] = $product_info['sku'];]]></add>
</operation>
</file>
</modification>
<!-- OCMOD per OpenCart 3.0: install.xml dentro mostra_sku.ocmod.zip -->
<modification>
<name>Mostra SKU nella pagina prodotto</name>
<code>mostra_sku</code>
<version>1.0</version>
<author>esempio</author>
<link></link>
<file path="catalog/controller/product/product.php">
<operation>
<search><![CDATA[$data['model'] = $product_info['model'];]]></search>
<add position="after"><![CDATA[$data['sku'] = $product_info['sku'];]]></add>
</operation>
</file>
</modification>Nota che la riga cercata è cambiata: nella 1.5 i controller scrivono in $this->data, dalla 2.x in poi in una variabile $data. È esattamente il tipo di differenza che rompe le modifiche durante un aggiornamento. Dopo l’installazione, in OCMOD le modifiche diventano attive solo premendo il pulsante di aggiornamento nella pagina delle modifiche, che rigenera la cache. Per mostrare il valore serve poi una seconda operazione sul template, che dalla 3.0 è un file Twig invece di un .tpl.
Verso la serie 4: eventi al posto della ricerca di testo
Nella serie 4 conviene ripensare le modifiche invece di convertirle. Il sistema di eventi permette di ottenere lo stesso risultato dell’esempio, aggiungere un dato alla pagina prodotto, registrando un’azione che viene eseguita dopo il controller o prima della vista, e che riceve i dati da modificare. Non dipende dal testo dei file del core, quindi sopravvive agli aggiornamenti minori. OCMOD nella 4.1 resta utile nei pochi casi senza un evento adatto, e conviene limitarlo a quelli.
Il passaggio alla serie 4 cambia anche la struttura delle estensioni: ogni estensione ha una sua cartella, classi con namespace come Opencart\Catalog\Controller\Extension\..., un pacchetto installabile con install.json. Un’estensione scritta per la 2.x o la 3.0 non si installa sulla 4 senza essere riscritta. Prima di scegliere la serie di destinazione va quindi verificato, per ogni estensione commerciale, se il fornitore offre la versione per la 3.0, per la 4.1 o per entrambe.
Il percorso di aggiornamento
Le istruzioni ufficiali coprono solo una parte dei salti. Il file UPGRADE.md della serie 3.0 descrive l’aggiornamento dalla 2.x, con lo script nella cartella install che adegua il database, e per chi parte dalla 1.5 rimanda al supporto a pagamento del progetto. Quello della 4.1.0.4 copre solo gli aggiornamenti dalle versioni 4.1.0.0–4.1.0.3. Per un negozio su 1.5 o 2.x la strada più affidabile è di solito un’installazione pulita della versione di destinazione, con la migrazione dei dati e la ricostruzione di tema ed estensioni. Le fasi tipiche sono queste:
- copia completa di file e database del negozio attuale su un ambiente di prova;
- inventario delle estensioni e delle modifiche XML, con la decisione per ciascuna: sostituire, riscrivere o eliminare;
- installazione pulita della 3.0 o della 4.1 su un server con PHP 8.1 o superiore;
- migrazione di prodotti, categorie, clienti, ordini e pagine informative, con uno script dedicato o con lo script di aggiornamento quando il salto è supportato;
- nuovo tema e reinstallazione delle estensioni nelle versioni compatibili;
- prove complete del percorso di acquisto, dei pagamenti, delle email e delle integrazioni;
- reindirizzamenti permanenti per gli URL che cambiano e passaggio in produzione con un breve blocco degli ordini.
I punti da non sottovalutare in un e-commerce, cioè ordini in corso, password dei clienti e posizionamento, sono comuni a tutte le piattaforme e li trattiamo nell’articolo su come migrare un e-commerce su PHP legacy.
3.0 o 4.1?
La serie 3.0 è più vicina alla 2.x: stessa organizzazione delle estensioni, OCMOD funzionante, ampia disponibilità di estensioni commerciali. È la scelta più rapida per chi ha molte estensioni e vuole uscire presto da PHP 5 o 7. La serie 4.1 ha un’architettura più moderna e un sistema di estensioni più pulito, ma richiede di riscrivere o sostituire quasi tutto il codice aggiuntivo. Per un negozio che deve durare anni, partire dalla 4.1 evita un secondo grande salto in futuro. In entrambi i casi vale la stessa regola: meno modifiche XML, più codice che usa i punti di estensione previsti dal core.
Se il negozio deve restare sulla versione attuale per qualche mese, il server va comunque protetto: il backport delle patch di sicurezza sul PHP in uso chiude le vulnerabilità note mentre il nuovo negozio viene preparato. Il nostro servizio di migrazione applicativa copre anche OpenCart.
Per concludere
Un negozio OpenCart 1.5 o 2.x dipende quasi sempre da modifiche XML gestite da vQmod o OCMOD, che funzionano cercando e sostituendo testo nei file del core e per questo si rompono quando il core cambia. A ottobre 2026 le serie mantenute sono la 3.0 e la 4.1, aggiornate ad agosto 2026 ed entrambe con PHP 8.1 come requisito minimo. La 3.0 conserva OCMOD e un’organizzazione simile alla 2.x, la 4.1 introduce una struttura delle estensioni nuova, con gli eventi come strumento principale e OCMOD come eccezione. Le istruzioni ufficiali non coprono il salto dalla 1.5 e dalla 2.x alla serie 4, quindi la via più sicura è un’installazione pulita con migrazione dei dati, partendo da un inventario completo di estensioni, modifiche XML e file del core toccati a mano.
