Struttura delle cartelle di un modulo PrestaShop: guida pratica

Un modulo PrestaShop non è solo un file PHP con alcuni hook. Un modulo serio contiene controller, template, asset, traduzioni, script di aggiornamento, dipendenze Composer e a volte servizi. Una struttura chiara rende più semplici debug, aggiornamenti e supporto.

La documentazione ufficiale offre una guida alla struttura dei file di un modulo. Qui trovi la versione pratica.

Cartella principale

Il modulo vive in /modules/<module_name>/. Il file principale deve avere lo stesso nome: mymodule/mymodule.php. Gestisce installazione, hook, configurazione e metadati.

Se questo file diventa enorme, la logica dovrebbe andare in classi sotto src/.

controllers/

controllers contiene controller front e admin. I front controller stanno in controllers/front, le pagine back office in controllers/admin. Un controller dovrebbe leggere la richiesta, chiamare servizi, assegnare variabili al template e rispondere.

views/

views contiene template e asset. Separare views/templates/front, views/templates/admin e views/templates/hook rende più semplice il debug e gli override di tema.

src/

src è il posto giusto per classi moderne: servizi, entità, validator, client API e logica riutilizzabile. Mantiene pulito il file principale.

translations/

Le traduzioni sono parte del prodotto. Label, errori, email, testi di aiuto e messaggi front office devono avere un percorso di traduzione pulito.

upgrade/

upgrade contiene script di aggiornamento. Tabelle, colonne, hook, tab e configurazioni vanno create in installazione o upgrade, non controllate a ogni richiesta.

vendor/

vendor contiene dipendenze Composer. Non modificare manualmente le copie vendor. Se il bug è in un pacchetto condiviso, correggi il pacchetto sorgente e sincronizzalo.

config.xml e override/

config.xml deve corrispondere alla versione del modulo. override dovrebbe restare una soluzione estrema, perché cambia il comportamento core.

Regola finale

Una buona struttura non rende automaticamente buono un modulo, ma una cattiva struttura rende ogni bug più costoso. Un modulo chiaro è più facile da supportare, tradurre e aggiornare.

Skeleton pratico del modulo

Un modulo pulito non deve essere complicato, ma deve essere prevedibile:

modules/
  mymodule/
    mymodule.php
    config.xml
    composer.json
    controllers/
    src/
    views/
    translations/
    upgrade/
    vendor/

Non ogni modulo ha bisogno di tutte le cartelle. Un piccolo modulo hook può essere semplice. Un modulo checkout, pagamento o SEO richiede quasi sempre più struttura.

Cosa resta nel file principale

Il file principale descrive il modulo e lo collega a PrestaShop: metadati, installazione, disinstallazione, hook e metodi sottili. Non dovrebbe contenere migliaia di righe di logica, SQL nei template o rendering form complesso.

controllers/ deve restare leggero

Il controller coordina: valida la richiesta, chiama servizi, assegna variabili e risponde. Motori prezzo, sitemap generator o migrazioni non dovrebbero vivere interamente lì.

src/ rende il modulo manutenibile

src/ contiene classi riutilizzabili: installer, repository, validator, client API, servizi, export e import. Se una classe può essere capita senza template Smarty, probabilmente appartiene a src/.

views/ non è logica

I template renderizzano dati. Condizioni di presentazione sì, query SQL e regole business no. Separare front, admin e hook aiuta il debug.

upgrade/ è parte del contratto

Un modulo evolve: colonne, hook, tab, configurazioni e migrazioni. Queste cose devono stare negli script upgrade, non in auto-riparazioni casuali a ogni richiesta.

vendor/ richiede disciplina

Patchare copie vendor manualmente non è mantenibile. Un bug in un pacchetto condiviso va corretto alla fonte e propagato.

override/ come ultima scelta

Gli override cambiano il core e complicano gli upgrade. Hook, controller, servizi, eventi o logica del modulo sono spesso più sicuri.

Collegamento con le altre guide

Questa guida copre la cartella modulo. Per l'intera piattaforma vedi la guida alla struttura PrestaShop. Per i temi vedi il deep dive /themes/.

Checklist

• File principale leggibile.
• Controller che chiamano servizi.
• Template senza SQL.
• Asset tracciabili da source a runtime.
• Install e upgrade gestiscono schema, tab, hook e config.
• Traduzioni complete.
• Fix vendor upstream.
• Override solo come eccezione.

La cartella chiarita qui è /modules/<module_name>/.