Struttura delle cartelle PrestaShop: Cosa fa ogni directory e quando serve

Perche comprendere la struttura delle cartelle e importante

PrestaShop is a large application. A typical installation contains over 30,000 files across hundreds of directories. Most store owners never need to look at the filesystem. But if you develop modules, customize themes, debug issues, or manage your own server, knowing which directory does what saves hours of searching and prevents costly mistakes.

This guide covers the most important directories in a PrestaShop 1.7.x, 8.x, or 9.x installation. We start with the directories you will interact with most and work down to the ones you should leave alone.

/modules/ -- Il cuore della personalizzazione PrestaShop

This is the directory you will interact with most. Every module -- whether installed from the marketplace, uploaded as a ZIP, or developed custom -- lives here as a subdirectory.

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

Regole chiave:

• The main PHP file must have the exact same name as the directory: modules/mymodule/mymodule.php
• The class name inside must match too: class Mymodule extends Module
• Never edit native PS modules (prefixed ps_) -- updates will overwrite your changes. Use hooks, overrides, or theme template overrides instead
• Module files must be owned by the web server user (www-data on most Linux setups) for uploads and cache generation to work

Quando serve questa directory: Installing modules, developing modules, debugging module issues, checking which modules are installed, reviewing module source code.

/themes/ -- Aspetto visivo e template

All front-office visual output is controlled by themes. Each theme is a subdirectory containing templates, assets, and 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

Regole chiave:

• Never edit the parent theme directly. Create a child theme that inherits from the parent and override only what you change.
• The active theme is set in Back Office > Design > Theme & Logo
• modules/ inside a theme takes priority over the module's own templates -- this is how themes customize module output
• PrestaShop 9 uses Hummingbird (Bootstrap 5, CSS layers). PrestaShop 1.7/8 uses Classic (Bootstrap 4).

Quando serve questa directory: Customizing the store's appearance, creating child themes, overriding module templates, debugging template issues.

/config/ -- File di configurazione

Core configuration that PrestaShop reads on every request.

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

File chiave:

• settings.inc.php -- Contains your database host, name, user, password, and the cookie encryption key. This file is generated during installation. Back this up. If you lose the cookie key, all existing customer sessions and employee sessions become invalid.
• defines.inc.php -- Where you toggle debug mode: set _PS_MODE_DEV_ to true for development (shows errors), false for production. Also contains _PS_CACHE_ENABLED_ and other runtime flags.

Quando serve questa directory: Setting up a new installation, changing database credentials, toggling debug mode, troubleshooting connection issues.

/var/ -- Cache, log e file temporanei

PrestaShop's runtime data. This directory grows over time and can be safely cleared (except logs you want to keep).

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

Operazioni chiave:

• Svuotare la cache: rm -rf var/cache/prod/* -- the single most common fix for "I changed something but nothing happened"
• Alternatively: php bin/console cache:clear --env=prod
• The Smarty compile directory stores pre-compiled templates. If a template change doesn't appear, delete var/cache/prod/smarty/compile/*
• Check logs: var/logs/prod.log is the first place to look when something breaks. It contains PHP errors, Symfony exceptions, and module errors.

Quando serve questa directory: Clearing cache after changes, debugging errors via logs, freeing disk space on small servers.

/classes/ -- Logica di business (Legacy)

PrestaShop's original object model. Each file is a PHP class representing a business entity or utility.

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

Regole chiave:

• Never edit these files directly. Use the /override/classes/ mechanism if you must change core behavior (but overrides have their own problems -- prefer hooks and modules).
• In PS 1.7+, many of these classes are being gradually replaced by Symfony services in /src/. Both systems coexist.
• ObjectModel is the base class for all entities. Understanding it is essential for module development -- it provides add(), update(), delete(), getFields(), and validation.

Quando serve questa directory: Understanding how PrestaShop calculates prices, manages stock, processes orders. Reading (not editing) these files is how you learn the internal API.

/controllers/ -- Gestione delle richieste

Controllers process HTTP requests and render pages. PrestaShop has two sets: front office and admin.

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

Regole chiave:

• Front controllers extend FrontController. Admin controllers extend AdminController.
• In PS 1.7+, admin controllers are being migrated to Symfony (in /src/PrestaShopBundle/Controller/). Some admin pages use the new Symfony controllers, others still use the legacy ones here. Both coexist.
• Module controllers live in modules/yourmodule/controllers/, not here.

Quando serve questa directory: Understanding how a specific page works, debugging page-level issues, finding which hooks are available on which page (controllers call Hook::exec()).

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

The modern architecture layer. PrestaShop has been gradually migrating from the legacy /classes/ + /controllers/ pattern to Symfony since version 1.7.

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

Regole chiave:

• This directory grows with each PS version as more features migrate to Symfony
• The Adapter/ layer is critical -- it wraps legacy classes so Symfony services can use them
• In PS 9, most admin pages are fully Symfony. In PS 1.7/8, it is a mix of legacy and Symfony.
• Module developers rarely need to modify anything here -- interact with it through Symfony services registered in your module's services.yml

Quando serve questa directory: Advanced module development using Symfony services, understanding the CQRS pattern for product/order management in PS 8+, contributing to PrestaShop core.

/override/ -- Il sistema di override

PrestaShop's mechanism for modifying core behavior without editing core files.

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

Regole chiave:

• Override classes extend the original and override specific methods
• Only one override per class is possible. If two modules try to override the same class, only the last one wins. This is why overrides are fragile -- module conflicts are guaranteed in active stores.
• After adding or removing overrides, regenerate the class index: delete var/cache/prod/class_index.php and clear cache
• PS 9 deprecates the override system. Prefer hooks, Symfony service decoration, or CQRS commands for new development.
• Overrides can cause mysterious bugs that are hard to trace. Always check override/ when debugging unexpected behavior.

Quando serve questa directory: As a last resort when hooks don't provide the control you need. Always prefer hooks and module-based approaches. Read our Hooks & Overrides reference for the full picture.

/img/ -- Immagini prodotto e contenuti

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

Regole chiave:

• Product images are stored with a path derived from the product ID digits: product 123 → img/p/1/2/3/. This distributes files across directories to avoid filesystem limits.
• Image regeneration (Back Office > Design > Image Settings > Regenerate) recreates all resized versions from originals. This can take hours on large catalogs.
• Back up this directory. Product images cannot be regenerated if originals are lost.
• WebP versions are generated alongside JPG/PNG in PS 8+ when enabled.

Quando serve questa directory: Debugging missing product images, checking image quality, bulk image operations, server migration (this is often the largest directory by file count).

/app/ -- Kernel dell'applicazione Symfony

app/
  AppKernel.php               -- Symfony kernel, registers bundles
  config/
    config.yml                -- Symfony service configuration
    parameters.php            -- auto-generated from settings.inc.php
    routing.yml               -- URL routing definitions
    security.yml              -- authentication/authorization
    services.yml              -- service container definitions

Regole chiave:

• AppKernel.php is the entry point for the Symfony side of PrestaShop. It registers all bundles including module bundles.
• config/routing.yml defines admin URL patterns. Module admin routes are registered separately via the module's own routing files.
• In PS 9, the kernel has been significantly refactored. parameters.php generation may differ.

Quando serve questa directory: Advanced debugging of Symfony routing, service container issues, or authentication problems. Most developers never touch this directly.

/translations/ -- File di traduzione

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

Regole chiave:

• Core translations use XLIFF format (.xlf). Module translations use PHP arrays or XLIFF depending on the PS version.
• Translation packs are installed via Back Office > International > Translations or php bin/console prestashop:translation:export
• Database-stored translations (edited in the back office) take priority over file-based translations.

Directory che non dovresti mai modificare

These directories are part of PrestaShop's core infrastructure. Editing them directly means your changes will be lost on update, and you risk breaking the entire installation:

• /vendor/ -- Composer dependencies (Symfony, Doctrine, etc.). Managed by composer install. Never edit.
• /bin/ -- Console commands (bin/console). Run them, don't edit them.
• /tools/ -- Build and maintenance scripts. Internal use.
• /install/ -- Installation wizard. Deleted after installation (should be, for security).
• /admin-dev/ (or your renamed admin folder) -- Admin entry point. Rename for security, but don't edit the files inside.
• /webservice/ -- REST API endpoint. Configured via back office, not by editing files.

Riferimento rapido: Dove trovare cosa

Cosa cambia tra le versioni PS

The overall trend is clear: PrestaShop is moving from the legacy architecture (/classes/ + /controllers/ + /override/) toward Symfony (/src/ + service decoration + CQRS). New module development should target the Symfony patterns where available, while maintaining backward compatibility with 1.7 through version-guarded code.

Prossimo in questa serie

This overview covers the top-level directory structure. Future articles will dive deeper into specific areas: the module anatomy (what every file in a module does), the hook system (how modules interact with PrestaShop without modifying core), and the theme template engine (Smarty variables, blocks, and the rendering pipeline).