PrestaShop code and module folder structure

What we would do

We would start from the task, confirm the shop root the live domain serves and its exact release, then inspect the relevant files without changing them. Use the back office for supported configuration and cache operations, and put planned customization in a maintained module or child theme rather than in core files.

Before changing or deleting anything, take a files-and-database backup, rehearse the change on a staging copy and confirm the rollback steps; the backup guide and the staging guide cover both. The upgrade route depends on your existing modules, integrations, theme, data and custom code. For a major migration, the usual safe route is a clean target shop on staging, rebuilt and tested customizations, a rehearsed data migration and a planned cutover. An update in place remains an option where the inventory and staging tests support it. The PrestaShop 9 migration guide compares both routes.

Choose the map for your release family

Paths below are relative to the shop root. They are starting points to confirm against the installed build, not a promise that every minor release or hosting package has the same tree. A directory being present does not prove that the shop currently uses it.

Check the release in the back office or the deployment records. A shop installed in a subdirectory can also make paths differ from an example. The back-office menu paths below use modern labels. On PrestaShop 1.6, use Preferences > Themes, Preferences > Images and Localization > Translations for the corresponding tasks.

Before browsing further, ask which directory the live domain actually serves. A hosting account can contain old copies, staging installations or linked release directories. Finding a familiar modules/ folder does not establish that you are looking at the active shop. Use the compatibility guide when planning work across releases.

Locate the main platform directories

PrestaShop 1.7 and later combine legacy classes and controllers with a Symfony layer. Read core code to understand behaviour, and keep shop customizations in your module, child theme or a supported extension point.

Core vendor/ contains Composer dependencies; a fault there needs investigation through the package and deployment process, because direct edits are easily lost. bin/console runs console commands: confirm the available commands and the PHP runtime before executing anything. The admin entry directory is normally renamed on deployed shops. Installer directories should be removed after installation. Configure webservice access through the back office rather than editing its entry scripts.

Other directories include mail templates, PDF templates, localization data, uploads and downloadable-product files. Include their business data in your backup plan: uploads and downloadable products are not disposable cache.

Find files by the job you need to do

For an error report, capture the page or action, the failure time with time zone, the release and a relevant redacted log extract. Do not send an entire configuration file to prove which database is in use.

Distinguish legacy and modern code

Examples of actual legacy lookup paths are:

classes/Product.php
classes/Category.php
classes/Cart.php
classes/Customer.php
classes/ObjectModel.php
classes/order/Order.php
classes/module/Module.php
classes/db/Db.php
classes/shop/Shop.php
classes/tax/Tax.php
classes/stock/StockAvailable.php

ObjectModel is the base of the legacy Active Record model. It supplies persistence and validation methods for classes that extend it. Modern Doctrine entities do not all extend ObjectModel.

Storefront controllers include controllers/front/ProductController.php, CategoryController.php, CartController.php, OrderController.php, CmsController.php and SearchController.php. Legacy admin controllers live under controllers/admin/; a migrated page may instead use a Symfony controller.

Within src/, Adapter/ bridges legacy functionality, Core/Domain/ organizes domain commands and queries, and PrestaShopBundle/ contains Symfony controllers, entities, form types, translation and Twig integration. Exact subdirectories and routes vary by release.

In PrestaShop 9.1, app/ includes separate admin, front and Admin API kernels as well as application configuration. Do not assume an older AppKernel.php diagram describes every request path.

PrestaShop 1.6 uses a different map: classes/, controllers/, modules/, themes/, override/, config/, cache/ and log/. It does not have the standard modern src/, app/ and var/cache/ layout. Compare the official 1.6 source tree when maintaining an old shop.

Organize a module by responsibility

The main file uses the module directory's technical name. For example, modules/cataloghelper/cataloghelper.php contains the corresponding module class extending Module. Keep metadata, lifecycle entry points and hook wiring there.

modules/cataloghelper/
  cataloghelper.php
  config.xml
  logo.png
  composer.json
  controllers/
    front/
    admin/
  src/
    Service/
    Repository/
    Form/
    Installer/
  config/
  views/
    templates/
      front/
      admin/
      hook/
    css/
    js/
    img/
  translations/
  upgrade/
  vendor/

This is an example, not a mandatory collection of empty folders, and a missing optional folder is not evidence of a broken installation. A small hook-only module may need only its main file and a template. Add directories as their responsibilities appear. See the official module structure requirements.

• Controllers: validate requests, call services, assign data and return responses. Keep reusable pricing, importing or API logic outside the controller so hooks and jobs can call it too.
• src: place reusable services, validators, repositories, installers and integration clients here with an appropriate autoloader. Modern controllers and service definitions can use Symfony integration where the target release supports it.
• views: separate front, admin and hook templates. Render prepared data; keep database queries and business calculations out of templates. Document how source SCSS or JavaScript produces the shipped assets.
• translations: cover labels, errors, emails, help and storefront strings using the supported translation system.
• config.xml and logo.png: keep the cached descriptor's version consistent with the module's version property and ship the icon used in listings.

A front controller at controllers/front/display.php with the corresponding CataloghelperDisplayModuleFrontController class can be addressed through the link builder, for example with the module, controller and fc=module parameters. Use generated links for friendly-URL compatibility.

Legacy admin controllers need the appropriate tab and access integration. A modern admin controller uses a route and permission configuration. A directory name alone does not make an admin page accessible or place it in the menu.

Ship dependencies and deliberate upgrades

Installation creates the initial schema, configuration, tabs and hook registrations. Versioned files in upgrade/ bring existing installations forward. A script such as upgrade-1.2.0.php can expose upgrade_module_1_2_0($module) and return a truthful success result.

For an added priority column and a new media hook, check the existing schema before adding the column, register the hook, and return failure if a required step fails. A partial deployment can leave the column present even if a later step failed. Design the script so retrying handles that state.

Keep destructive schema changes and data transformations explicit. A supported integrity guard may handle declared additive repair, but runtime checks do not replace upgrade design.

If the module requires vendor/autoload.php, include the required production dependencies in the release ZIP. A normal merchant upload does not run Composer for you. Build dependencies for the supported PHP target, exclude development-only packages from the production artifact, and test the exact ZIP.

Fix dependencies in their maintained source, then update the consuming module. Manual edits inside vendor/ can disappear on the next build.

Trace templates and PHP overrides separately

In PrestaShop 1.7, 8 and 9, a theme typically contains config/theme.yml, templates, assets and a modules/ directory for module template overrides. Front templates can be grouped into catalog, checkout, CMS, customer, partial and layout directories.

Use a child theme for changes you need to preserve through parent-theme updates; where your theme supports one, the child theme guide covers the setup. Check the active theme under Design > Theme & Logo. A matching module template in the active theme can take priority over the module's own template.

PrestaShop 9.0 defaults to Classic. Hummingbird becomes the default with 9.1, while Classic remains available, as described in the Hummingbird 2.0 release notes. Check the installed theme's framework and assets rather than assuming a Bootstrap version from the core major version.

A PHP override changes legacy behaviour. Compatible additions from modules can be merged into the installed override class, but duplicate method or property overrides can make installation fail. There is no general last-module-wins rule.

Legacy overrides remain supported in PrestaShop 9. Prefer a suitable hook, service decoration, event or module-owned controller when it offers the needed extension point. See the PrestaShop override documentation and our hooks and overrides guide.

Example: a module template change has no effect

1. Confirm you are inspecting the active shop and theme, including the relevant multistore context, and that the deployed file is the one you edited.
2. Find the module's template and check whether the active theme or its parent supplies another copy.
3. Confirm on staging which template is actually selected. A filename match alone is not enough.
4. Put the intended change in the supported customization location, then follow the cache procedure below and test the page.

Find credentials and bootstrap settings

config/config.inc.php is core bootstrap code. It loads definitions, autoloading and bootstrap.php; it is not an installer-generated credentials file.

Modern 1.7 and later installations use app/config/parameters.php for installation parameters, including database credentials and keys. Historical installations can have parameters.yml handling. Legacy 1.6 commonly uses config/settings.inc.php.

Keep credential files and their backups private. Confirm a file exists without printing its values, and keep its contents out of tickets, screenshots and public downloads. Preserve installation keys during a move; changing keys can affect sessions and protected application values.

config/defines.inc.php contains definitions such as _PS_MODE_DEV_. The bootstrap derives _PS_CACHE_ENABLED_ from the installation's ps_cache_enable parameter. These are separate settings.

Enable development diagnostics on a protected staging environment. Avoid exposing detailed exception pages or a debug toolbar to customers: start with the logs and reproduce on staging, and give any production diagnostic change a controlled procedure and a clear return to normal operation.

Manage cache, logs and deployment permissions

Modern caches live under var/cache/, including environment-specific Symfony and Smarty data. On 1.7, cache and log locations depend on the minor release, so check the installed tree. Use Advanced Parameters > Performance > Clear cache or the supported console command from the shop root:

php bin/console cache:clear --env=prod

A command-line cache operation is a deployment task: confirm that the release provides the command, and run maintenance with the deployment's correct PHP binary, environment and application user. Ensure newly generated cache files remain accessible to PHP. Do not wipe the entire var/ directory to make space: it can contain logs, sessions and module runtime data as well as caches. Do not delete the whole 1.6 cache/ directory either, or copy generated containers between releases. If clearing cache fails, preserve the error and inspect permissions and the release's procedure rather than repeatedly deleting folders.

If a change does not appear, work through the possible causes in order:

1. Confirm that the intended source file reached the active release.
2. Confirm the active theme, the overridden template or code actually serving the request, and the selected environment.
3. Inspect application caches, browser and proxy caches, CDN caches and PHP OPcache. Clearing one cache does not prove the others have refreshed.
4. Rehearse the supported refresh on staging, with backup and rollback prepared, and inspect any regeneration error.
5. Recheck the page and record the deployment procedure that worked.

OPcache behaviour depends on its server settings and may require an authorized reset or PHP worker reload.

Look in var/logs/ for configured application logs, and also check PHP-FPM, web-server and module logs; your host may keep PHP and web-server logs outside the shop tree. One prod.log file is not a universal sink for every PHP or module error, so an empty log does not prove that no error occurred until you have checked the configured destination. Archive logs needed for diagnosis before applying retention cleanup.

If disk space is the problem, identify what is growing first. Logs call for a retention decision; images, uploads and downloads for an ownership and reference check; cache for the release's supported procedure.

Source files need to be readable by the PHP worker; they do not all need to be owned or writable by the web-server user. A separate deployment owner can manage code. There is no universal web-server username or ownership command for every host: confirm the deployment account, PHP process user and access model with the hosting administrator. Grant write access only where uploads, installation or runtime generation require it, using the real user and group model. Avoid world-writable permissions.

Locate images and translations

Product image paths use the image ID, which is distinct from the product ID. Image 123 can have an original at img/p/1/2/3/123.jpg and generated sizes such as 123-home_default.jpg in that directory. A product can have multiple image IDs.

Other directories include img/c/ for categories, img/m/ for brands, img/s/ for suppliers, img/cms/ for editor content and img/tmp/ for temporary files. Generated extensions and image formats depend on the release and settings, and a media or storage integration can change the observed path.

Back up image originals. Thumbnail regeneration under Design > Image Settings needs those originals; it cannot recreate lost photographs. Test regeneration on a suitable batch before a large catalog operation.

For a missing image, start with an affected product and its actual image reference. Compare the requested URL with the image record, the original file and the required generated size, then check file ownership and any media or CDN integration. Do not guess the image ID from the product number, rename folders or regenerate everything first. Product files and customer uploads may also need restricted access.

Core translations use locale resources including XLIFF. Modules can use legacy PHP arrays or the modern translation system, depending on their integration. Check translation domains, locale and back-office customizations when wording differs from a file.

Installing or importing a language through International > Translations differs from exporting module translations. Where available, inspect the module export command with:

php bin/console prestashop:translation:export-module --help

The command takes the module's technical name and can accept a locale. It exports module translation resources; it does not install a language pack. For the back-office side of languages, see the translations and international selling guide.

Find the file behind a feature

1. Start from the page URL or route and identify the controller.
2. For a module page, inspect that module's controllers or route definitions.
3. Follow the called service or legacy model into its actual path.
4. Trace template resolution through the active theme and module overrides.
5. Inspect hook registrations and installed PHP overrides if behaviour differs from core.
6. Check logs and caches after a controlled change.

From the shop root, these read-only searches help locate customizations:

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

A search shows which files exist, not which ones run: a found override or template still needs the checks above, and removing files is not a diagnostic shortcut.

Keep upgrade-surviving changes in maintained module or theme sources, under version control with a documented deployment route. Core and dependency edits can be overwritten by updates, and replacing an existing module or parent-theme file has the same risk. A custom module also needs maintenance and testing across upgrades.

Prepare the way back before changing files

• Configuration change: protect a copy of the original settings, test on staging and keep a way back to the previous values. Restrict access to backup copies that contain secrets.
• Code or template change: record the diff, stage it, check the affected customer or staff journey and keep the previous deployable release for rollback.
• File removal: establish what owns the files and whether database records or external services still reference them. Test the supported removal process on staging with a restorable backup; for modules, follow the module removal guide rather than deleting a directory to see what happens.

Before a live deployment, refresh the backup and agree who can restore service. Restoring old files and restoring an old database are separate operations with different effects, and orders or uploads that arrive after the backup must be preserved before either. Folder knowledge helps you ask a precise question; it does not replace the shop's deployment procedure.

Ask the agency to hand over the active shop root, the release and theme inventory, customization locations, writable runtime locations and the named backup and rollback procedure.

Questions shop owners ask

Does a module folder mean the module is installed?

No. Check its state in the relevant shop context, its version against the package and its hook registrations. Leftover files alone do not establish what is running or whether removal is safe.

Why does our folder list differ from this guide?

Release, packaging, hosting and deployment choices change the tree. Confirm the active installation before creating a missing folder, renaming the admin folder or copying files from another release to match an example.

Can we delete a folder whose name looks temporary?

Not on the strength of its name. A directory called temporary can still hold files that records reference, so check ownership and references first and follow the file removal step above.