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/<name_of_the_module>/. A module published in an archive file must be in a same subfolder.

Here are the possible files and folders for a PrestaShop 1.7 module:

➜  module tree -L 3
.
├── config
│   ├── services.yml
│   ├── admin
│   │    └── services.yml
│   └── front
│       └── services.yml
├── config.xml
├── controllers
├── logo.png
├── module_name.php
├── override
├── src
│   └── Entity
├── themes
│   └── theme_name
│       └── modules
├── translations
├── upgrade
└── views
    ├── css
    ├── img
    ├── js
    └── templates

13 directories, 4 files

Main file: module_name.php

The main PHP file should have the same name as the module’s root folder. For instance, for the BlockCMS module:

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

Icon files: logo.png && logo.gif

This needs to be a 32*32 pixels PNG file.

Templating: the views folder

This folder contains your module’s template files (.tpl or .html.twig files).

Depending on your needs, your files are located in differents subfolders:

  • /views/templates/admin: For template files used by the module’s administration legacy controllers.
  • /views/templates/front: For template files used by the module’s front office controllers.
  • /views/templates/hook: For template files used by the module’s hooks.

If you want to override a Twig template file from Back Office, declare your own following the same path in /views/PrestaShop subfolder. For instance, if you want to override product.html.twig template located in Admin/Product/ProductPage, create your own file in /views/PrestaShop/Admin/Product/ProductPage/product.html.twig.

Every asset you need to use in the module (css, js or image files) must be located in their folders: /views/{js, css, img, fonts}.

Make actions and pages: the controllers folder

This folder contains the Controller files. You can use the same sub-folder paths as for the View files.

For instance, /modules/<module_name>/controllers/front/payment.php is a valid path to share an action with your Front Office.

Override Core classes of PrestaShop: the override folder

Try to avoid the overriding Core classes, this make the upgrade of your application risky.

You need to follow the same path as the PrestaShop application in your module. For instance:

  • Shop class
    • PrestaShop class => classes/shop/Shop.php
    • Module override => modules/<module_name>/override/classes/shop/Shop.php

If /modules/<module_name>/override/classes/Shop.php exists in your module and is not overriden by any more module later, this class will be used instead of the native ShopCore class everywhere in your application.

Translate your strings: the translations folder

This folder contains a php file for each locale: fr.php, es.php. Translating your module can be done within your shop administration panel, in International > Translations > Installed modules translations.

Adapt behavior of others modules: the themes/<theme_name>/modules folder

This folder is essential during modifications of an existing module, so that you can adapt it without having to touch its original files. Notably, it enables you to handle the module’s template files in various ways, depending on the current theme.

Manage the upgrade: the upgrade folder

When releasing a new version of the module, the older might need an upgrade of its data or files. This can be done using this folder.

Configuration file: services.yml

In services.yml file, you can register your own classes as a Symfony service and alter the ones provided by PrestaShop.

Cache file: config.xml

If it does not exist yet, config.xml file is automatically generated by PrestaShop when the module is installed.

It contains some properties on the main module class and optimizes the loading of the module list in the back office.

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. Otherwise it must be regenerated by PrestaShop before the upgrade file application is suggested.

<?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[Firstname Lastname]]></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>.

External libraries

All external library you’d use 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 not have the same meaning as ‘sdk’). You can have more than one such folder, for instance /sdk and /vendor.