Structure des dossiers PrestaShop : A quoi sert chaque repertoire et quand l'utiliser

Pourquoi comprendre la structure des dossiers est important

PrestaShop est une application volumineuse. Une installation classique contient plus de 30 000 fichiers repartis dans des centaines de repertoires. La plupart des proprietaires de boutique n'ont jamais besoin de consulter le systeme de fichiers. Mais si vous developpez des modules, personnalisez des themes, deboguez des problemes ou gerez votre propre serveur, savoir quel repertoire fait quoi vous fait gagner des heures de recherche et evite des erreurs couteuses.

Ce guide couvre les repertoires les plus importants d'une installation PrestaShop 1.7.x, 8.x ou 9.x. Nous commencons par ceux avec lesquels vous interagirez le plus souvent, puis descendons vers ceux que vous devriez laisser tranquilles.

/modules/ -- Le coeur de la personnalisation PrestaShop

C'est le repertoire avec lequel vous interagirez le plus. Chaque module -- qu'il soit installe depuis la marketplace, televerse en ZIP ou developpe sur mesure -- se trouve ici sous forme de sous-repertoire.

modules/
  ps_emailsubscription/       -- module natif PrestaShop
  mprcheckoutrevolution/      -- module tiers
  mymodule/                   -- votre module personnalise
    mymodule.php              -- fichier principal du module (obligatoire)
    config.xml                -- metadonnees du module en cache
    views/
      templates/              -- templates Smarty
      css/                    -- feuilles de style
      js/                     -- JavaScript
    controllers/
      front/                  -- controleurs front office
      admin/                  -- controleurs back office
    sql/                      -- SQL d'installation/mise a jour
    upgrade/                  -- scripts de mise a jour de version
    translations/             -- fichiers de traduction
    vendor/                   -- dependances Composer

Regles essentielles :

• Le fichier PHP principal doit porter exactement le meme nom que le repertoire : modules/mymodule/mymodule.php
• Le nom de la classe a l'interieur doit correspondre egalement : class Mymodule extends Module
• Ne modifiez jamais les modules natifs PS (prefixes ps_) -- les mises a jour ecraseront vos modifications. Utilisez plutot les hooks, les overrides ou les surcharges de templates via le theme
• Les fichiers du module doivent appartenir a l'utilisateur du serveur web (www-data sur la plupart des configurations Linux) pour que les televerserments et la generation du cache fonctionnent

Quand vous avez besoin de ce repertoire : installation de modules, developpement de modules, debogage de problemes lies aux modules, verification des modules installes, lecture du code source des modules.

/themes/ -- Apparence visuelle et templates

Tout l'affichage front office est controle par les themes. Chaque theme est un sous-repertoire contenant des templates, des ressources et une configuration.

themes/
  classic/                    -- theme par defaut PS (1.7/8)
    config/theme.yml          -- metadonnees du theme, declaration des ressources
    templates/                -- fichiers Smarty .tpl
      catalog/                -- pages produit, categorie
      checkout/               -- panier, tunnel de commande
      cms/                    -- pages CMS
      customer/               -- pages compte client
      _partials/              -- en-tete, pied de page, notifications
      layouts/                -- gabarits de mise en page
    assets/
      css/                    -- CSS compile
      js/                     -- JS compile
      img/                    -- images du theme (icones, placeholders)
    modules/                  -- surcharges de templates de modules
  hummingbird/                -- theme par defaut PS 9
  my-child-theme/             -- votre theme enfant

Regles essentielles :

• Ne modifiez jamais le theme parent directement. Creez un theme enfant qui herite du parent et ne surchargez que ce que vous modifiez.
• Le theme actif est defini dans le Back Office > Apparence > Theme & Logo
• Le dossier modules/ a l'interieur d'un theme a priorite sur les templates propres du module -- c'est ainsi que les themes personnalisent l'affichage des modules
• PrestaShop 9 utilise Hummingbird (Bootstrap 5, couches CSS). PrestaShop 1.7/8 utilise Classic (Bootstrap 4).

Quand vous avez besoin de ce repertoire : personnalisation de l'apparence de la boutique, creation de themes enfants, surcharge de templates de modules, debogage de problemes d'affichage.

/config/ -- Fichiers de configuration

La configuration centrale que PrestaShop lit a chaque requete.

config/
  config.inc.php              -- NE JAMAIS MODIFIER : genere automatiquement, charge settings.inc.php
  settings.inc.php            -- identifiants de base de donnees, cle de cookie, version PS
  defines.inc.php             -- constantes de chemins, drapeaux de debogage
  smarty.config.inc.php       -- configuration du moteur de templates Smarty
  autoload.php                -- amorce de l'autoloader Composer

Fichiers cles :

• settings.inc.php -- Contient l'hote, le nom, l'utilisateur et le mot de passe de votre base de donnees, ainsi que la cle de chiffrement des cookies. Ce fichier est genere lors de l'installation. Sauvegardez-le. Si vous perdez la cle de cookie, toutes les sessions existantes (clients et employes) deviennent invalides.
• defines.inc.php -- C'est ici que vous activez le mode debogage : definissez _PS_MODE_DEV_ sur true pour le developpement (affiche les erreurs), false pour la production. Contient egalement _PS_CACHE_ENABLED_ et d'autres drapeaux d'execution.

Quand vous avez besoin de ce repertoire : mise en place d'une nouvelle installation, modification des identifiants de base de donnees, activation du mode debogage, resolution de problemes de connexion.

/var/ -- Cache, logs et fichiers temporaires

Les donnees d'execution de PrestaShop. Ce repertoire grossit avec le temps et peut etre vide en toute securite (sauf les logs que vous souhaitez conserver).

var/
  cache/
    prod/                     -- cache de production
      smarty/
        compile/              -- templates Smarty compiles
        cache/                -- cache de sortie Smarty
      ContainerProdDebugProjectContainer.php  -- conteneur DI Symfony
    dev/                      -- cache de developpement (quand _PS_MODE_DEV_ = true)
  logs/
    prod.log                  -- logs d'erreurs Symfony/PS
    dev.log                   -- logs du mode developpement

Operations essentielles :

• Vider le cache : rm -rf var/cache/prod/* -- la solution la plus courante au probleme « j'ai modifie quelque chose mais rien n'a change »
• Alternativement : php bin/console cache:clear --env=prod
• Le repertoire de compilation Smarty stocke les templates pre-compiles. Si une modification de template n'apparait pas, supprimez var/cache/prod/smarty/compile/*
• Consulter les logs : var/logs/prod.log est le premier endroit ou regarder quand quelque chose ne fonctionne pas. Il contient les erreurs PHP, les exceptions Symfony et les erreurs de modules.

Quand vous avez besoin de ce repertoire : vider le cache apres des modifications, deboguer des erreurs via les logs, liberer de l'espace disque sur les petits serveurs.

/classes/ -- Logique metier principale (legacy)

Le modele objet originel de PrestaShop. Chaque fichier est une classe PHP representant une entite metier ou un utilitaire.

classes/
  Product.php                 -- entite Produit (attributs, prix, stock)
  Category.php                -- entite Categorie
  Cart.php                    -- logique du panier d'achat
  Order.php                   -- entite Commande
  Customer.php                -- entite Client
  Module.php                  -- classe de base des modules (install, hooks, config)
  Tools.php                   -- fonctions utilitaires (redirect, getValue, etc.)
  Db.php                      -- abstraction de base de donnees
  ObjectModel.php             -- classe ORM de base
  shop/
    Shop.php                  -- logique multi-boutique
  tax/
    Tax.php                   -- calcul des taxes
  stock/
    StockAvailable.php        -- gestion des stocks

Regles essentielles :

• Ne modifiez jamais ces fichiers directement. Utilisez le mecanisme /override/classes/ si vous devez modifier le comportement du coeur (mais les overrides ont leurs propres inconvenients -- preferez les hooks et les modules).
• Depuis PS 1.7+, bon nombre de ces classes sont progressivement remplacees par des services Symfony dans /src/. Les deux systemes coexistent.
• ObjectModel est la classe de base de toutes les entites. La comprendre est indispensable pour le developpement de modules -- elle fournit add(), update(), delete(), getFields() et la validation.

Quand vous avez besoin de ce repertoire : comprendre comment PrestaShop calcule les prix, gere les stocks, traite les commandes. Lire (sans modifier) ces fichiers est la meilleure facon d'apprendre l'API interne.

/controllers/ -- Traitement des requetes

Les controleurs traitent les requetes HTTP et affichent les pages. PrestaShop en possede deux categories : front office et back office.

controllers/
  front/
    ProductController.php     -- page produit
    CategoryController.php    -- liste des categories
    CartController.php        -- operations du panier
    OrderController.php       -- etapes de la commande
    CmsController.php         -- pages CMS
    SearchController.php      -- resultats de recherche
  admin/
    AdminProductsController.php
    AdminOrdersController.php
    AdminCustomersController.php

Regles essentielles :

• Les controleurs front etendent FrontController. Les controleurs admin etendent AdminController.
• Depuis PS 1.7+, les controleurs admin migrent progressivement vers Symfony (dans /src/PrestaShopBundle/Controller/). Certaines pages admin utilisent les nouveaux controleurs Symfony, d'autres encore ceux de type legacy presents ici. Les deux coexistent.
• Les controleurs de modules se trouvent dans modules/votre-module/controllers/, pas ici.

Quand vous avez besoin de ce repertoire : comprendre le fonctionnement d'une page specifique, deboguer des problemes au niveau de la page, trouver quels hooks sont disponibles sur quelle page (les controleurs appellent Hook::exec()).

/src/ -- Couche Symfony (PS 1.7+)

La couche d'architecture moderne. PrestaShop migre progressivement du modele legacy /classes/ + /controllers/ vers Symfony depuis la version 1.7.

src/
  Adapter/                    -- passerelles entre le legacy et Symfony
  Core/
    Domain/                   -- commandes et requetes CQRS
      Product/
        Command/              -- CreateProduct, UpdateProduct, etc.
        Query/                -- GetProductForEditing, etc.
    Grid/                     -- definitions de grilles/listes admin
    Form/                     -- definitions de formulaires admin
  PrestaShopBundle/
    Controller/               -- controleurs Symfony admin
    Entity/                   -- entites Doctrine
    Form/                     -- types de formulaires
    Translation/              -- systeme de traduction
    Twig/                     -- extensions Twig pour l'admin

Regles essentielles :

• Ce repertoire grandit a chaque version de PS a mesure que de nouvelles fonctionnalites migrent vers Symfony
• La couche Adapter/ est essentielle -- elle enveloppe les classes legacy pour que les services Symfony puissent les utiliser
• Sous PS 9, la plupart des pages admin sont entierement sous Symfony. Sous PS 1.7/8, c'est un melange de legacy et de Symfony.
• Les developpeurs de modules ont rarement besoin de modifier quoi que ce soit ici -- interagissez avec cette couche via les services Symfony declares dans le fichier services.yml de votre module

Quand vous avez besoin de ce repertoire : developpement avance de modules utilisant les services Symfony, comprehension du pattern CQRS pour la gestion des produits/commandes sous PS 8+, contribution au coeur de PrestaShop.

/override/ -- Le systeme de surcharge

Le mecanisme de PrestaShop pour modifier le comportement du coeur sans editer les fichiers principaux.

override/
  classes/
    Product.php               -- surcharge classes/Product.php
    Cart.php                  -- surcharge classes/Cart.php
  controllers/
    front/
      ProductController.php   -- surcharge controllers/front/ProductController.php
    admin/
      AdminProductsController.php

Regles essentielles :

• Les classes de surcharge etendent l'originale et redefinissent des methodes specifiques
• Une seule surcharge par classe est possible. Si deux modules tentent de surcharger la meme classe, seul le dernier l'emporte. C'est pourquoi les overrides sont fragiles -- les conflits entre modules sont garantis dans les boutiques actives.
• Apres avoir ajoute ou supprime des surcharges, regenerez l'index des classes : supprimez var/cache/prod/class_index.php et videz le cache
• PS 9 deprecie le systeme de surcharge. Privilegiez les hooks, la decoration de services Symfony ou les commandes CQRS pour les nouveaux developpements.
• Les overrides peuvent provoquer des bugs mysterieux difficiles a tracer. Verifiez toujours override/ lorsque vous deboguez un comportement inattendu.

Quand vous avez besoin de ce repertoire : en dernier recours, quand les hooks n'offrent pas le controle necessaire. Privilegiez toujours les hooks et les approches basees sur les modules. Consultez notre reference Hooks & Overrides pour le tableau complet.

/img/ -- Images produits et contenus

img/
  p/                          -- images produits (organisees par chiffres de l'ID)
    1/2/3/                    -- images du produit ID 123
      123.jpg                 -- original
      123-home_default.jpg    -- redimensionnee pour l'accueil
      123-large_default.jpg   -- redimensionnee pour la page produit
  c/                          -- images des categories
  m/                          -- logos fabricants/marques
  s/                          -- logos fournisseurs
  cms/                        -- images des pages CMS (televerssees via l'editeur)
  l/                          -- icones de drapeaux des langues
  tmp/                        -- televersements temporaires

Regles essentielles :

• Les images produits sont stockees selon un chemin derive des chiffres de l'ID du produit : produit 123 → img/p/1/2/3/. Cela repartit les fichiers entre les repertoires pour eviter les limites du systeme de fichiers.
• La regeneration des images (Back Office > Apparence > Images > Regenerer) recree toutes les versions redimensionnees a partir des originaux. Cela peut prendre des heures sur les gros catalogues.
• Sauvegardez ce repertoire. Les images produits ne peuvent pas etre regenerees si les originaux sont perdus.
• Les versions WebP sont generees en meme temps que les JPG/PNG dans PS 8+ lorsque l'option est activee.

Quand vous avez besoin de ce repertoire : debogage d'images produits manquantes, verification de la qualite des images, operations en lot sur les images, migration de serveur (c'est souvent le repertoire le plus volumineux en nombre de fichiers).

/app/ -- Noyau applicatif Symfony

app/
  AppKernel.php               -- noyau Symfony, enregistre les bundles
  config/
    config.yml                -- configuration des services Symfony
    parameters.php            -- genere automatiquement depuis settings.inc.php
    routing.yml               -- definitions du routage URL
    security.yml              -- authentification/autorisation
    services.yml              -- definitions du conteneur de services

Regles essentielles :

• AppKernel.php est le point d'entree de la partie Symfony de PrestaShop. Il enregistre tous les bundles, y compris ceux des modules.
• config/routing.yml definit les patterns d'URL admin. Les routes admin des modules sont enregistrees separement via les fichiers de routage propres au module.
• Sous PS 9, le noyau a ete profondement refactorise. La generation de parameters.php peut differer.

Quand vous avez besoin de ce repertoire : debogage avance du routage Symfony, problemes de conteneur de services ou d'authentification. La plupart des developpeurs n'y touchent jamais directement.

/translations/ -- Fichiers de traduction du coeur

translations/
  default/                    -- chaines par defaut en anglais
  en-US/                      -- anglais US
  fr-FR/                      -- francais
  de-DE/                      -- allemand
    ShopTheme.fr-FR.xlf       -- traductions front office
    AdminNavigation.fr-FR.xlf -- traductions du menu admin

Regles essentielles :

• Les traductions du coeur utilisent le format XLIFF (.xlf). Les traductions de modules utilisent des tableaux PHP ou du XLIFF selon la version de PS.
• Les packs de traduction s'installent via le Back Office > International > Traductions ou php bin/console prestashop:translation:export
• Les traductions stockees en base de donnees (modifiees dans le back office) ont priorite sur les traductions dans les fichiers.

Repertoires que vous ne devez jamais modifier

Ces repertoires font partie de l'infrastructure centrale de PrestaShop. Les modifier directement signifie que vos changements seront perdus lors d'une mise a jour, et vous risquez de casser toute l'installation :

• /vendor/ -- Dependances Composer (Symfony, Doctrine, etc.). Gere par composer install. Ne jamais modifier.
• /bin/ -- Commandes console (bin/console). Executez-les, ne les modifiez pas.
• /tools/ -- Scripts de construction et de maintenance. Usage interne.
• /install/ -- Assistant d'installation. Supprime apres l'installation (c'est ce qui devrait etre fait, pour des raisons de securite).
• /admin-dev/ (ou votre dossier admin renomme) -- Point d'entree admin. Renommez-le pour la securite, mais ne modifiez pas les fichiers a l'interieur.
• /webservice/ -- Point d'acces a l'API REST. Configure via le back office, pas en modifiant les fichiers.

Reference rapide : ou trouver quoi

Ce qui change entre les versions PS

La tendance generale est claire : PrestaShop evolue de l'architecture legacy (/classes/ + /controllers/ + /override/) vers Symfony (/src/ + decoration de services + CQRS). Le developpement de nouveaux modules devrait cibler les patterns Symfony lorsqu'ils sont disponibles, tout en maintenant la compatibilite avec la version 1.7 via du code conditionnel selon la version.

Suite de cette serie

Cet apercu couvre la structure des repertoires de premier niveau. De futurs articles approfondiront des domaines specifiques : l'anatomie d'un module (le role de chaque fichier dans un module), le systeme de hooks (comment les modules interagissent avec PrestaShop sans modifier le coeur) et le moteur de templates (variables Smarty, blocs et pipeline de rendu).