Releasing and upgrading a module

The module is ready and has to be handed over to another shop — a client's production server or the marketplace. A module is distributed as a ZIP archive that is uploaded through the back office. For the installation and later upgrades to go smoothly, the archive is built by a few rules.

The final structure

This is what the module has accumulated during the course:

modules/acmehello/
├── acmehello.php               the main class
├── composer.json               autoload of classes from src
├── logo.png                    the icon
├── classes/
│   └── AcmeReview.php          the ObjectModel model
├── config/
│   ├── routes.yml              back office routes
│   └── services.yml            services and commands
├── controllers/
│   ├── admin/                  the legacy back office controller
│   └── front/                  front office pages
├── mails/
│   └── en/                     mail templates
├── src/
│   ├── Command/                console commands
│   ├── Controller/Admin/       Symfony controllers
│   └── Repository/             services
├── upgrade/
│   └── upgrade-1.1.0.php       upgrade scripts
├── vendor/                     the Composer autoloader
└── views/
    ├── css/  js/               styles and scripts
    └── templates/
        ├── admin/              Twig templates
        ├── front/              page templates
        └── hook/               hook templates

The version

The version number is three numbers separated by dots in the constructor of the main class:

// modules/acmehello/acmehello.php
$this->version = '1.2.0';

The engine stores the installed version in the database. Seeing a higher version in the code, it knows the module has to be upgraded.

What goes into an upgrade

Everything install() does once is not repeated for an installed module. If a new version adds a hook, a setting, a table or a column, describe it in an upgrade script:

<?php
// modules/acmehello/upgrade/upgrade-1.2.0.php
if (!defined('_PS_VERSION_')) {
    exit;
}
 
function upgrade_module_1_2_0($module)
{
    return $module->registerHook('actionProductDelete')
        && Configuration::updateValue('ACMEHELLO_LIMIT', 5);
}

The script subscribes the module to a new hook and creates a new setting. The same is added to install() — for those who install the module for the first time. If the function returns false, the upgrade stops and the back office shows an error.

Preparing the folder

Before building the archive, run this in the module folder:

composer install --no-dev --optimize-autoloader

The command creates the vendor folder without development libraries. The vendor folder goes into the archive: nobody will run Composer in the shop where the module is installed.

What does not go into the archive:

The index.php files

It is customary to put an index.php file that redirects to the home page into every module folder. It blocks directory listing if the server is configured poorly. The PrestaShop marketplace requires such files in all folders.

Building the archive

The archive root must hold one folder with the module name:

cd modules
zip -r acmehello-1.2.0.zip acmehello -x "acmehello/.git/*" "acmehello/config*.xml"

The command creates the archive acmehello-1.2.0.zip with the acmehello folder and all its files inside.

Installing and upgrading from the archive

1. Open "Modules → Module Manager" in the back office.
2. Press "Upload a module" and drop the archive into the window.

If the shop does not have the module, it is installed. If an older version is installed, the files are replaced and the upgrade scripts from the installed version up to the new one are run. From the console an upgrade after replacing the files is started like this:

php bin/console prestashop:module upgrade acmehello

Checks before a release

Common mistake

The archive is built from the contents of the folder rather than from the folder itself: acmehello.php and views sit in the ZIP root. The back office answers that the archive is not a module. The archive root must hold exactly one folder, and its name must match the technical name of the module.