Module file structure

A module is made of a lot of files, all stored in a folder that bears the same name as the module, that folder being in turn stored in the /modules folder at the root of the main PrestaShop folder: /modules/<modulename>/.

Your module can be called anything, as long as it only contains lowercase letters and numbers (/[a-z0-9]/). Although accepted, we strongly discourage using underscores (_) because they don’t work with translation domains.

A module distributed in a zip archive file must also be placed in a subfolder within the zip file.

Main files and directories

Here are an example of files and folders for a PrestaShop 1.7 module:

mymodule
├── config
│   ├── admin
│   │    └── services.yml
│   ├── front
│   │   └── services.yml
│   └── services.yml
├── controllers
├── override
├── src
│   ├── Controller
│   └── Entity
├── translations
├── upgrade
├── vendor
├── views
│   ├── css
│   ├── img
│   ├── js
│   └── templates
├── config.xml
├── logo.png
└── mymodule.php

Let’s go through each one of the above.

config/ folder

The config folder is the place where configuration files are stored. In particular, Routes and Services.

controllers/ folder

The controllers folder contains the legacy-style Controller files.

Depending on where the controller belongs to, it is located in a different subfolder:

  • /controllers/admin: module’s back office controllers.
  • /controllers/front: module’s front office controllers.
Symfony-based controllers go in the "src" folder, described below.

Read more about Controllers →

override/ folder

PHP files placed in the override folder will replace the ones from the Core.

Overrides is a powerful, yet risky feature. Avoid using it if you can.

Read more about Overrides →

src/ folder

The src folder is the recommended folder to place all of your module’s PHP classes–like Grids, Entities, Forms, and so on.

Symfony-based controllers go in the src/Controller folder.

translations/ folder

The translations folder contains translation files allowing to display the module’s wording in different languages.

Read more about Translation →

upgrade/ folder

The upgrade folder contains upgrade scripts to be executed when updating the module from a previous version.

Read more about the Upgrade feature →

vendor/ folder

The vendor folder usually contains libraries imported through Composer as well as its autoloader. This folder is optional.

views/ folder

The views folder contains your module’s template files (.tpl for Smarty or .html.twig for Twig) as well as static assets used by the module (css, js or image files). Each type must be located in their own folders: /views/{js, css, img, fonts}.

Depending on your needs, template files are located in different subfolders:

  • /views/templates/admin: Smarty or Twig template files used by the module’s back office controllers.
  • /views/templates/front: Smarty template files used by the module’s front office controllers.
  • /views/templates/hook: Smarty template files used by the module’s hooks.

Since 1.7.3 you can redefine back office views by placing files in this folder. This is covered in Overriding back office views.

Read more about Templating →

config.xml file

The config.xml file contains a cached copy of properties from main module class in order to optimize performance of module listings.

This file is automatically generated by PrestaShop when the module is installed, if it doesn’t exist yet.

It can be useful to provide it in your release, as it will allow your upgrade scripts (in upgrade/) to be executed immediately after the zip is downloaded.

<?xml version="1.0" encoding="UTF-8" ?>
<module>
    <name>mymodule</name>
    <displayName><![CDATA[My module]]></displayName>
    <version><![CDATA[1.0]]></version>
    <description><![CDATA[Description of my module.]]></description>
    <author><![CDATA[Author name]]></author>
    <tab><![CDATA[front_office_features]]></tab>
    <confirmUninstall>Are you sure you want to uninstall?</confirmUninstall>
    <is_configurable>0</is_configurable>
    <need_instance>0</need_instance>
    <limited_countries></limited_countries>
</module>

A few details:

  • is_configurable indicates whether the module has a configuration page or not.
  • need_instance indicates whether an instance of the module must be created when it is displayed in the module list. This can be useful if the module has to perform checks on the PrestaShop configuration, and display warning message accordingly.
  • limited_countries is used to indicate the countries to which the module is limited. For instance, if the module must be limited to France and Spain, use <limited_countries>fr,es</limited_countries>.

logo.png file

This icon file will be displayed in module listings if present. It needs to be a 32x32 pixel PNG file.

mymodule.php file (main file)

The module’s main PHP file should be named the same as the module’s root folder.

Example for the BlockCMS module:

  • Folder name: /modules/blockcms
  • Main file name: /modules/blockcms/blockcms.php

External libraries

All external libraries should be put in a dedicated folder.

That folder can use one of these names: lib, libs, libraries, sdk, vendor, vendors.

Choose the most appropriate one for your library (indeed, libraries doesn’t have the same meaning as sdk). You can have more than one such folder, for instance /sdk and /vendor.