Structure des dossiers PrestaShop expliquée : rôle de chaque répertoire et quand l’utiliser

Vérifié avec PrestaShop 1.6, 1.7, 8.x et 9.x. Les répertoires ci-dessous existent dans ces versions ; la principale différence tient au volume de code déplacé vers /src/ (Symfony) et au fait que PrestaShop 9 fournit Hummingbird à la place de Classic. Les différences propres à chaque version sont signalées dans les tableaux en fin d’article.

Pourquoi il est important de comprendre la structure des dossiers

PrestaShop est une application volumineuse. Une installation classique contient plus de 30 000 fichiers répartis dans des centaines de répertoires. La plupart des marchands n’ont jamais besoin d’explorer le système de fichiers. Mais si vous développez des modules, personnalisez des thèmes, déboguez des problèmes ou gérez votre propre serveur, savoir à quoi sert chaque dossier vous évite des heures de recherche et des erreurs coûteuses.

Ce guide couvre les répertoires les plus importants d’une installation PrestaShop 1.7.x, 8.x ou 9.x. Nous commençons par ceux avec lesquels vous interagirez le plus souvent, puis descendons vers ceux qu’il vaut mieux laisser tranquilles.

/modules/ -- Le cœur de la personnalisation PrestaShop

C’est le répertoire avec lequel vous travaillerez le plus. Chaque module, qu’il soit installé depuis la place de marché, importé sous forme de ZIP ou développé sur mesure, y vit dans son propre sous-répertoire.

modules/
  ps_emailsubscription/       -- PrestaShop native module
  mprcheckoutrevolution/      -- third-party module
  mymodule/                   -- your custom module
    mymodule.php              -- main module file (required)
    config.xml                -- cached module metadata
    views/
      templates/              -- Smarty templates
      css/                    -- stylesheets
      js/                     -- JavaScript
    controllers/
      front/                  -- front office controllers
      admin/                  -- admin controllers
    sql/                      -- install/upgrade SQL
    upgrade/                  -- version upgrade scripts
    translations/             -- translation files
    vendor/                   -- Composer dependencies

Règles essentielles :

• Le fichier PHP principal doit porter exactement le même nom que le répertoire : modules/mymodule/mymodule.php
• Le nom de la classe doit lui aussi correspondre : class Mymodule extends Module
• Ne modifiez jamais les modules natifs de PS (préfixés par ps_) -- les mises à jour écraseront vos changements. Utilisez plutôt les hooks, les overrides ou les surcharges de templates dans le thème
• Les fichiers du module doivent appartenir à l’utilisateur du serveur web (www-data sur la plupart des installations Linux) pour que les imports et la génération du cache fonctionnent

Quand vous avez besoin de ce répertoire : installation de modules, développement de modules, débogage de problèmes liés aux modules, vérification des modules installés, lecture du code source d’un module.

/themes/ -- Apparence visuelle et templates

Toute la sortie visuelle du front office est contrôlée par les thèmes. Chaque thème est un sous-répertoire contenant des templates, des ressources et de la configuration.

themes/
  classic/                    -- PS default theme (1.7/8)
    config/theme.yml          -- theme metadata, asset registration
    templates/                -- Smarty .tpl files
      catalog/                -- product, category pages
      checkout/               -- cart, checkout flow
      cms/                    -- CMS pages
      customer/               -- account pages
      _partials/              -- header, footer, notifications
      layouts/                -- page layout wrappers
    assets/
      css/                    -- compiled CSS
      js/                     -- compiled JS
      img/                    -- theme images (icons, placeholders)
    modules/                  -- module template overrides
  hummingbird/                -- PS 9 default theme
  my-child-theme/             -- your child theme

Règles essentielles :

• Ne modifiez jamais directement le thème parent. Créez un thème enfant qui hérite du parent et ne surchargez que ce que vous changez.
• Le thème actif se définit dans Back Office > Apparence > Thème & Logo
• Le dossier modules/ à l’intérieur d’un thème est prioritaire sur les propres templates du module -- c’est ainsi que les thèmes 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 répertoire : personnalisation de l’apparence de la boutique, création de thèmes enfants, surcharge de templates de modules, débogage de problèmes de templates.

/config/ -- Fichiers de configuration

Configuration cœur que PrestaShop lit à chaque requête.

config/
  config.inc.php              -- NEVER EDIT: auto-generated, loads settings.inc.php
  settings.inc.php            -- database credentials, cookie key, PS version
  defines.inc.php             -- path constants, debug flags
  smarty.config.inc.php       -- Smarty template engine configuration
  autoload.php                -- Composer autoloader bootstrap

Fichiers clés :

• settings.inc.php -- Contient l’hôte, le nom, l’utilisateur et le mot de passe de votre base de données, ainsi que la clé de chiffrement des cookies. Ce fichier est généré lors de l’installation. Sauvegardez-le. Si vous perdez la clé des cookies, toutes les sessions clients et employées existantes deviennent invalides.
• defines.inc.php -- C’est là que vous activez ou désactivez le mode debug : définissez _PS_MODE_DEV_ sur true en développement (affiche les erreurs), ou sur false en production. Il contient aussi _PS_CACHE_ENABLED_ et d’autres indicateurs d’exécution.

Un point piège souvent les utilisateurs de PrestaShop 8 et 9 : settings.inc.php peut ne pas exister. Les installations récentes stockent les mêmes identifiants dans app/config/parameters.php, généré par l’installateur. Si vous cherchez la connexion à la base de données et que config/settings.inc.php est absent, regardez dans app/config/parameters.php, c’est l’emplacement moderne de ces mêmes valeurs.

Quand vous avez besoin de ce répertoire : mise en place d’une nouvelle installation, modification des identifiants de base de données, activation du mode debug, résolution de problèmes de connexion.

/var/ -- Cache, journaux et fichiers temporaires

Données d’exécution de PrestaShop. Ce répertoire grossit avec le temps ; videz son cache depuis le back office ou la console, en conservant les journaux que vous voulez garder.

var/
  cache/
    prod/                     -- production cache
      smarty/
        compile/              -- compiled Smarty templates
        cache/                -- Smarty output cache
      ContainerProdDebugProjectContainer.php  -- Symfony DI container
    dev/                      -- development cache (when _PS_MODE_DEV_ = true)
  logs/
    prod.log                  -- Symfony/PS error logs
    dev.log                   -- development mode logs

Opérations clés :

• Vider le cache depuis Paramètres avancés > Performances > Vider le cache.
• Autre possibilité : php bin/console cache:clear --env=prod
• Le répertoire de compilation Smarty stocke les templates précompilés. Si une modification de template n’apparaît pas, supprimez var/cache/prod/smarty/compile/*
• Consulter les journaux : var/logs/prod.log est le premier endroit à vérifier quand quelque chose casse. Il contient les erreurs PHP, les exceptions Symfony et les erreurs de modules.

Attention, en particulier avec PrestaShop 9 : le back office est une application Symfony avec son propre conteneur généré sous var/cache/prod/admin. Un rm -rf var/cache/prod/* lancé à l’aveugle sur une boutique PS 9 en production peut laisser l’administration avec un conteneur incomplet et provoquer des erreurs 500 sur la page de connexion jusqu’à ce que le cache admin soit reconstruit. Sur PS 9, préférez la console (php bin/console cache:clear --env=prod) à la suppression brute, et videz le cache avec l’utilisateur du serveur web afin que les fichiers régénérés aient les bons droits.

Quand vous avez besoin de ce répertoire : vidage du cache après des changements, débogage d’erreurs via les journaux, libération d’espace disque sur de petits serveurs.

/classes/ -- Logique métier cœur (legacy)

Le modèle objet historique de PrestaShop. Chaque fichier est une classe PHP représentant une entité métier ou un utilitaire.

classes/
  Product.php                 -- Product entity (attributes, prices, stock)
  Category.php                -- Category entity
  Cart.php                    -- Shopping cart logic
  Order.php                   -- Order entity
  Customer.php                -- Customer entity
  Module.php                  -- Base module class (install, hooks, config)
  Tools.php                   -- Utility functions (redirect, getValue, etc.)
  Db.php                      -- Database abstraction
  ObjectModel.php             -- Base ORM class
  shop/
    Shop.php                  -- Multi-shop logic
  tax/
    Tax.php                   -- Tax calculation
  stock/
    StockAvailable.php        -- Stock management

Règles essentielles :

• Ne modifiez jamais directement ces fichiers. Utilisez le mécanisme /override/classes/ si vous devez absolument modifier un comportement du cœur (mais les overrides ont leurs propres problèmes -- privilégiez les hooks et les modules).
• Dans PS 1.7+, beaucoup de ces classes sont progressivement remplacées par des services Symfony dans /src/. Les deux systèmes coexistent.
• ObjectModel est la classe de base de toutes les entités. La comprendre est essentiel pour développer des modules -- elle fournit add(), update(), delete(), getFields() et la validation.

Quand vous avez besoin de ce répertoire : comprendre comment PrestaShop calcule les prix, gère les stocks et traite les commandes. Lire ces fichiers (sans les modifier) est la meilleure façon de comprendre l’API interne.

/controllers/ -- Traitement des requêtes

Les contrôleurs traitent les requêtes HTTP et affichent les pages. PrestaShop possède deux ensembles : front office et administration.

controllers/
  front/
    ProductController.php     -- product page
    CategoryController.php     -- category listing
    CartController.php        -- cart operations
    OrderController.php       -- checkout steps
    CmsController.php         -- CMS pages
    SearchController.php      -- search results
  admin/
    AdminProductsController.php
    AdminOrdersController.php
    AdminCustomersController.php

Règles essentielles :

• Les contrôleurs front office étendent FrontController. Les contrôleurs d’administration étendent AdminController.
• Dans PS 1.7+, les contrôleurs d’administration migrent vers Symfony (dans /src/PrestaShopBundle/Controller/). Certaines pages d’administration utilisent les nouveaux contrôleurs Symfony, d’autres utilisent encore les contrôleurs legacy présents ici. Les deux coexistent.
• Les contrôleurs de module se trouvent dans modules/yourmodule/controllers/, pas ici.

Quand vous avez besoin de ce répertoire : comprendre le fonctionnement d’une page précise, déboguer des problèmes au niveau d’une page, trouver quels hooks sont disponibles sur quelle page (les contrôleurs appellent Hook::exec()).

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

La couche d’architecture moderne. Depuis la version 1.7, PrestaShop migre progressivement du modèle legacy /classes/ + /controllers/ vers Symfony.

src/
  Adapter/                    -- bridges between legacy and Symfony
  Core/
    Domain/                   -- CQRS commands and queries
      Product/
        Command/              -- CreateProduct, UpdateProduct, etc.
        Query/                -- GetProductForEditing, etc.
    Grid/                     -- admin list/grid definitions
    Form/                     -- admin form definitions
  PrestaShopBundle/
    Controller/               -- Symfony admin controllers
    Entity/                   -- Doctrine entities
    Form/                     -- Form types
    Translation/              -- Translation system
    Twig/                     -- Twig extensions for admin

Règles essentielles :

• Ce répertoire prend de l’importance à chaque version de PS, à mesure que davantage de fonctionnalités migrent vers Symfony
• La couche Adapter/ est critique -- elle encapsule les classes legacy afin que les services Symfony puissent les utiliser
• Dans PS 9, la plupart des pages d’administration sont entièrement Symfony. Dans PS 1.7/8, c’est un mélange de legacy et de Symfony.
• Les développeurs de modules ont rarement besoin de modifier quoi que ce soit ici -- interagissez avec cette couche via les services Symfony enregistrés dans le services.yml de votre module

Quand vous avez besoin de ce répertoire : développement avancé de modules avec des services Symfony, compréhension du modèle CQRS pour la gestion des produits et des commandes dans PS 8+, contribution au cœur de PrestaShop.

/override/ -- Le système d’override

Le mécanisme PrestaShop qui permet de modifier le comportement du cœur sans éditer les fichiers cœur.

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

Règles essentielles :

• Les classes d’override étendent la classe d’origine et surchargent des méthodes précises
• Un seul override par classe est possible. Si deux modules tentent de surcharger la même classe, seul le dernier l’emporte. C’est pourquoi les overrides sont fragiles -- les conflits entre modules sont inévitables dans les boutiques actives.
• Après l’ajout ou la suppression d’overrides, régénérez l’index des classes : supprimez var/cache/prod/class_index.php et videz le cache
• PS 9 rend le système d’override obsolète. Pour les nouveaux développements, privilégiez les hooks, la décoration de services Symfony ou les commandes CQRS.
• Les overrides peuvent provoquer des bugs difficiles à identifier. Vérifiez toujours override/ lorsque vous déboguez un comportement inattendu.

Quand vous avez besoin de ce répertoire : en dernier recours, lorsque les hooks ne donnent pas le contrôle nécessaire. Privilégiez toujours les hooks et les approches basées sur des modules. Consultez notre référence Hooks & Overrides pour une vue d’ensemble complète.

/img/ -- Images produits et contenus

img/
  p/                          -- product images (organized by ID digits)
    1/2/3/                    -- product ID 123's images
      123.jpg                 -- original
      123-home_default.jpg    -- resized for homepage
      123-large_default.jpg   -- resized for product page
  c/                          -- category images
  m/                          -- manufacturer/brand logos
  s/                          -- supplier logos
  cms/                        -- CMS page images (uploaded via editor)
  l/                          -- language flag icons
  tmp/                        -- temporary uploads

Règles essentielles :

• Les images produit sont stockées dans un chemin dérivé des chiffres de l’ID produit : produit 123 → img/p/1/2/3/. Cela répartit les fichiers entre plusieurs répertoires afin d’éviter les limites du système de fichiers.
• La régénération des images (Back Office > Apparence > Paramètres des images > Régénérer) recrée toutes les versions redimensionnées à partir des originaux. Cela peut prendre des heures sur de grands catalogues.
• Sauvegardez ce répertoire. Les images produit ne peuvent pas être régénérées si les originaux sont perdus.
• Dans PS 8+, les versions WebP sont générées à côté des JPG/PNG lorsque l’option est activée.

Quand vous avez besoin de ce répertoire : débogage d’images produit manquantes, contrôle de la qualité des images, opérations d’images en masse, migration de serveur (c’est souvent le plus gros répertoire en nombre de fichiers).

/app/ -- Noyau de l’application Symfony

app/
  AppKernel.php               -- Symfony kernel, registers bundles
  config/
    config.yml                -- Symfony service configuration
    parameters.php -- configuration générée ; les installations récentes y stockent les identifiants.
    routing.yml               -- URL routing definitions
    security.yml              -- authentication/authorization
    services.yml              -- service container definitions

Règles essentielles :

• AppKernel.php est le point d’entrée de la partie Symfony de PrestaShop. Il enregistre tous les bundles, y compris ceux des modules.
• config/routing.yml définit les modèles d’URL de l’administration. Les routes d’administration des modules sont enregistrées séparément via les propres fichiers de routing du module.
• Dans PS 9, le noyau a été largement refactorisé. La génération de parameters.php peut différer.

Quand vous avez besoin de ce répertoire : débogage avancé du routing Symfony, de problèmes de conteneur de services ou d’authentification. La plupart des développeurs ne le touchent jamais directement.

/translations/ -- Fichiers de traduction du cœur

translations/
  default/                    -- default English strings
  en-US/                      -- US English
  fr-FR/                      -- French
  de-DE/                      -- German
    ShopTheme.fr-FR.xlf       -- front office translations
    AdminNavigation.fr-FR.xlf -- admin menu translations

Règles essentielles :

• Les traductions du cœur utilisent le format XLIFF (.xlf). Les traductions des modules utilisent des tableaux PHP ou XLIFF selon la version de PS.
• Les packs de langue s’installent via Back Office > International > Traductions ou avec php bin/console prestashop:translation:export
• Les traductions stockées en base de données (modifiées dans le back office) sont prioritaires sur les traductions basées sur des fichiers.

Répertoires à ne jamais modifier

Ces répertoires font partie de l’infrastructure cœur de PrestaShop. Les modifier directement signifie que vos changements seront perdus lors d’une mise à jour, avec en plus le risque de casser toute l’installation :

• /vendor/ -- Dépendances Composer (Symfony, Doctrine, etc.). Géré par composer install. Ne jamais modifier.
• /bin/ -- Commandes console (bin/console). Exécutez-les, ne les modifiez pas.
• /tools/ -- Scripts de build et de maintenance. Usage interne.
• /install/ -- Assistant d’installation. Supprimé après l’installation (il devrait l’être, pour la sécurité).
• /admin-dev/ (ou votre dossier d’administration renommé) -- Point d’entrée de l’administration. Renommez-le pour la sécurité, mais ne modifiez pas les fichiers qu’il contient.
• /webservice/ -- Point d’accès de l’API REST. À configurer via le back office, pas en éditant les fichiers.

Référence rapide : où trouver quoi

Sur un serveur en production, cet audit rapide vous indique où la boutique contient du code personnalisé avant que vous touchiez à quoi que ce soit :

find modules themes override -maxdepth 2 -type d | sort
find override -type f -name '*.php' -print
find themes -path '*/modules/*' -type f -name '*.tpl' -print
find var/logs -type f -mtime -3 -print

Ce qui change selon les versions de PS

La tendance générale est claire : PrestaShop passe de l’architecture legacy (/classes/ + /controllers/ + /override/) vers Symfony (/src/ + décoration de services + CQRS). Les nouveaux développements de modules devraient cibler les modèles Symfony lorsqu’ils sont disponibles, tout en conservant la compatibilité avec la 1.7 grâce à du code conditionné par version.

Questions fréquentes

Puis-je supprimer tout le répertoire var/ sans risque pour libérer de l’espace ?

Supprimez le cache, pas les journaux dont vous avez encore besoin, et n’effacez jamais à l’aveugle le cache admin d’une boutique PrestaShop 9 en production. Utilisez la méthode de vidage du cache du back office ou de la console pour que le cache soit reconstruit correctement. Mais sur PS 9, le back office dépend d’un conteneur Symfony généré sous var/cache/prod/admin, et une suppression brute peut casser la connexion à l’administration avec une erreur 500 jusqu’à ce que ce conteneur soit reconstruit. Utilisez plutôt le bouton "Vider le cache" du back office ou php bin/console cache:clear --env=prod, au lieu de rm -rf en production. Les journaux sous var/logs/ peuvent être supprimés sans risque technique, mais ils sont souvent la seule trace de ce qui s’est mal passé ; archivez-les avant de les vider.

J’ai modifié un template / une classe, mais rien n’a changé sur le site. Pourquoi ?

Presque toujours à cause du cache. Smarty stocke les templates compilés sous var/cache/prod/smarty/compile/, et PrestaShop met également en cache le conteneur Symfony et l’index des classes. Videz le cache après avoir modifié des templates ou des overrides. S’il s’agit d’un changement de classe PHP et que le fichier se trouve sur un serveur avec OPcache, vous devrez peut-être aussi réinitialiser OPcache (ou redémarrer PHP-FPM), car l’ancien bytecode compilé peut persister même après la suppression du répertoire de cache.

Où doivent réellement vivre mes changements pour survivre à une mise à jour ?

Tout ce que vous voulez conserver lors d’une mise à jour du cœur doit se trouver dans /modules/ (vos propres modules), dans votre thème enfant sous /themes/, ou, en dernier recours, dans /override/. Modifier des fichiers sous /classes/, /controllers/, /src/, dans le thème parent ou dans des modules natifs ps_ signifie que la prochaine mise à jour écrasera votre travail. Tout l’intérêt du système d’overrides et de modules est de garder vos personnalisations hors des répertoires remplacés par l’outil de mise à jour.

La liste des dossiers de cet article ne correspond pas à mon installation, certains manquent.

Deux raisons possibles. D’abord, la version : une installation fraîche de PrestaShop 8/9 peut conserver les identifiants de base de données dans app/config/parameters.php plutôt que dans config/settings.inc.php, et l’organisation Symfony sous /src/ et /app/ évolue selon les versions. Ensuite, le durcissement de sécurité : beaucoup de boutiques en production renomment le dossier d’administration, suppriment /install/ après l’installation et restreignent l’accès à /config/ et /app/config/. L’absence du répertoire /install/ est bon signe, pas le symptôme d’une installation cassée.

Comment trouver quel fichier gère une page ou une fonctionnalité précise ?

Partez de l’URL. Une page front office correspond à un contrôleur dans controllers/front/ (ou dans le controllers/front/ d’un module) ; le template correspondant se trouve dans votre thème actif sous templates/. Pour les pages d’administration, vérifiez si l’écran est legacy (controllers/admin/) ou Symfony (src/PrestaShopBundle/Controller/). Les écrans récents sont Symfony. Activez _PS_MODE_DEV_ et la barre de debug pour voir exactement quel contrôleur et quel template ont rendu une page donnée ; c’est beaucoup plus rapide que de deviner à partir des noms de fichiers.

Ceci est la première partie d’une série

Cette vue d’ensemble vous donne la carte. Les articles suivants de cette série entreront dans chaque répertoire avec le niveau de détail qu’exige un guide de référence -- fichier par fichier, modèle par modèle, avec de vrais exemples issus de boutiques en production.

La série Architecture PrestaShop :

• Vue d’ensemble de la structure des dossiers (cet article) -- le rôle des répertoires les plus importants en un coup d’œil
• Analyse approfondie de /themes/ -- résolution des templates, pipeline des assets, fonctionnement interne des thèmes enfants, Hummingbird vs Classic, couches CSS, rendu d’une page par Smarty de la requête au HTML
• Analyse approfondie de /modules/ -- cycle de vie des modules, enregistrement des hooks, scripts de mise à niveau, chaîne installation/désinstallation, fonctionnement du cache config.xml, modèles d’autoloading
• Analyse approfondie de /classes/ et /src/ -- fonctionnement interne d’ObjectModel, coexistence du legacy et de Symfony, couche Adapter, modèles de commandes/requêtes CQRS dans PS 8/9
• Analyse approfondie de /controllers/ -- contrôleurs front vs admin, état de la migration Symfony page par page, routing, appel des hooks par contrôleur
• Analyse approfondie de /config/ et /var/ -- séquence de chargement de la configuration, couches de cache (Smarty, Symfony, OPcache, Redis), indicateurs de debug, référence defines.inc.php
• Analyse approfondie de /override/ -- fonctionnement interne du système d’override, class_index.php, raisons des conflits, ce qui le remplace dans PS 9, quand l’utiliser plutôt que les hooks
• Analyse approfondie de /img/ -- stockage des images par chiffres d’ID, pipeline de régénération, génération WebP, intégration CDN, système des types d’images

Chaque article est écrit du point de vue de quelqu’un qui a conçu et maintenu 159 modules PrestaShop sur PS 1.6, 1.7, 8 et 9. Ce n’est pas une documentation réécrite à partir des docs officielles -- c’est un savoir pratique tiré d’années de débogage, de profiling et de construction de systèmes en production.