Module Upgrades, Overrides and Decoration

Two version numbers matter. The file version is the $this->version literal in the main module file (modules/pcfe46/pcfe46.php); PrestaShop reads it without loading the class, by parsing the file, and falls back to config.xml if the parse fails, so keep the assignment a plain string literal. The stored version is the column version of the table ps_module, written at install time and updated after every upgrade. When the file version is greater than the stored one, the module is "upgradable": the Module Manager of the back office shows an Upgrade button, and bin/console prestashop:module upgrade <name> does the same from the console. A deployment that replaces the module folder (git pull, zip upload, composer) therefore has to be followed by the upgrade action; copying the files does not touch the stored version.

The Update Assistant, which moves a whole shop from one PrestaShop version to another, upgrades the modules it carries as well (it is described with the release process in Testing, Upgrades and Addons); this page is about the module mechanism that every one of those paths calls.

The scripts live in modules/pcfe46/upgrade/. The rules, taken from the module code of 9.2.0 and confirmed by running them:

The docs table of which scripts run is the one to remember:

Source: PrestaShop devdocs: Enabling the auto-update

Version 1.1.0 adds the table and the footer hook:

Version 1.2.0 renames a configuration key without losing the merchant’s value, adds a column, registers two hooks and refreshes the override (the reason for the last step is explained in Refreshing an override on upgrade):

Source: PrestaShop devdocs: Enabling the auto-update, Script examples

Four habits keep scripts safe. Write each statement so that it can run twice (CREATE TABLE IF NOT EXISTS, a column check before ALTER, registerHook that ignores an already registered hook, Configuration::updateValue), because a failure part-way through is repaired by fixing the script and running it again. Escape every value that comes from outside with pSQL() or an (int) cast and every identifier with bqSQL(), and build table names from _DB_PREFIX_. Never alter core tables: add a table of your own. And keep the work proportional: an ALTER TABLE on a table with millions of rows inside a web request is a timeout waiting to happen, so large data migrations belong in a console command that the script only schedules.

Start the shop at 1.0.0 (install the module, change the discount to 15 to prove the value survives), put the 1.2.0 files in place and run:

The command printed "Update action on module pcfe46 succeeded." After it:

Source: PrestaShop devdocs: Enabling the auto-update, How to test-run an upgrade

A fresh install of 1.2.0 on another database must end in the same state. The check that matters is a diff of show create table ps_pcfe46_club_note after the upgrade and after a clean uninstall plus install: the two outputs were identical (a table id_note, id_customer, note, source, date_add with a primary key and an index on id_customer, in InnoDB with utf8mb4). Keep that test in the module’s own test suite whenever a script changes the schema.

ModuleManager::upgrade (the code behind both the console command and the Module Manager button) does four things in this order: it disables the hooks of the module for the duration of the upgrade, executes the hook actionBeforeUpgradeModule (parameters moduleName and source), runs the scripts, and dispatches the upgrade event. When the stored version has moved, Module::upgradeModuleVersion executes actionModuleUpgradeAfter with the parameters module_name, old_version and new_version. The hook is new in 9.1 and the 9.1 changelog lists it with actionModuleEnable, actionModuleDisable and actionConfigurationUpdateValueBefore.

The first consequence was observed by running it: the hooks of a module are disabled while that module is being upgraded. With the hook method hookActionModuleUpgradeAfter in pcfe46, a plain version bump from 1.2.0 to 1.2.1 did not write PCFE46_LAST_UPGRADE, while the second module pcfe46b, which listens to the same hook, recorded pcfe46 1.2.0 -> 1.2.1; the same held for an upgrade that ran a script (pcfe46 1.2.1 -> 1.2.2). Calling the hook by hand with Hook::exec('actionModuleUpgradeAfter', [...]) ran the handler of pcfe46 normally, so the handler itself is fine. Use the hook to react to other modules being upgraded (clear a cache, re-register a widget), and put your own post-upgrade work in the script.

Source: PrestaShop devdocs: Changes in 9.1

A script that returns anything but true stops the chain. In 9.2.0 a test script upgrade-1.3.0.php returning false produced:

and the table showed active = 0 for the module. The remaining scripts do not run, the hook actionModuleUpgradeAfter is not sent, and the module is disabled so that code written for the new version does not run on half-migrated data. Two details are easy to miss. First, the stored version was nevertheless set to 1.3.0 (the console and the Module Manager call Module::upgradeModuleVersion with the file version after the scripts, whatever they returned), so running upgrade again does nothing and the failed script is never retried. Second, scripts that succeeded before the failing one stay applied.

Recovering is manual and was tested: fix the script, set the stored version back to the last good one, enable the module and upgrade again.

Source: PrestaShop devdocs: Enabling the auto-update

After this the console printed "Update action on module pcfe46 succeeded." and the module was active with version 1.3.0, and pcfe46b recorded pcfe46 1.2.2 -> 1.3.0. Because of this behaviour, test the upgrade path in a copy of the production database before shipping, back up before upgrading, and make every script idempotent so that the replay is safe.

Overrides are exclusive: if one module overrides a method, another module cannot override it as well, or must collide with it. The official docs therefore allow overrides only for the modules you build for your own shop, advise against them in modules you distribute, and forbid them in Addons partner modules. The docs themselves disagree: the good-practices page for Addons modules says that overrides are permitted but should be few (two or three at most) and not dangerous, while the overrides page says they are forbidden in partner modules. Treat the stricter rule as binding. The docs also state that creating a custom table and a custom ObjectModel is always preferable to overriding a core class to add fields.

This is the legacy habit. Older books teach PrestaShop through core overrides (Pérez Castaño’s PrestaShop Recipes, Apress, 2017, targets 1.6, where overriding Product, Cart or Customer was the normal way to change behaviour), and many stores still carry such code. On 9.x the same job is done with a hook, a decorated service or an own table; the next sections show how.

Source: PrestaShop devdocs: Overrides

The path of the module-side file is the path of the core file under the shop root: the module code asks the autoloader for the location of <Class>Core and looks for the same relative path under its own override/ folder. Also, a theme cannot override a module (the docs say it is not possible and never will be); the opposite, a theme overriding a module’s templates, is covered in Theme template overrides.

The module in this page ships this file in override/classes/controller/FrontController.php:

Installing the module (bin/console prestashop:module install pcfe46) created override/classes/controller/FrontController.php in the shop with this content. The comment block before every method is added by PrestaShop and is how it knows later which module owns the method; other comments of the module file are removed.

Every front page then answered with X-Pcfe46-Override: 1.0.0. The same applies to properties and constants: each gets its own module/date/version block. The class index is regenerated, and the new file is created together with an index.php in each folder it needed. If an override file already exists for that class (another module, or the merchant), the module’s methods are merged into it. If the same method, property or constant already exists in that file, installation stops.

Source: PrestaShop devdocs: Overrides, Overriding a class

pcfe46b first shipped an override of the same method, FrontController::initContent, with a different header. Installing it failed, and since reset is an uninstall plus an install, the module ended up uninstalled:

The failure printed by the install of 9.2.0 names both files and leaves the existing override untouched. Changing the second module to override a different method, initHeader, installed without error and produced one merged file with two blocks, each stamped with its own module name. Both headers were then sent on every page. In other words two modules can share an overridden class only if they override different methods, properties and constants, and neither can know that in advance, which is the practical meaning of "exclusive".

Uninstalling pcfe46 removed only its own method block from the shared file; the pcfe46b block stayed. When the last method was gone (after pcfe46b was uninstalled too), the file and its now empty folder were removed from override/. This is why a manual edit of an override file (adding a method by hand without the comment block) is dangerous: the uninstall cannot tell which module owns it.

Because the main class of another module is just a class, pcfe46b can ship override/modules/pcfe45classic/pcfe45classic.php:

After the install, the product page printed the classic badge of Module Translations wrapped in the paragraph. The docs add that you should clear the cache after adding such an override and that the pattern "is not recommended, since the exact usage of a module to be overridden is unknown": the other module’s author may rename the method in the next release.

Source: PrestaShop devdocs: Overrides, Override a module

Overrides are copied to the shop only by install(), never by an upgrade. When version 1.2.0 changed the header text of the override, prestashop:module upgrade alone would have left the old file in place and the shop would still send X-Pcfe46-Override: 1.0.0. That is why upgrade-1.2.0.php calls $module->removeOverride('FrontController') and then $module->addOverride('FrontController'), both public methods of Module. The test confirmed that after the upgrade the override file carried version: 1.2.0 in its comment block and the header was 1.2.0.

prestashop:module install|uninstall|reset|... <name> --skip-overrides is documented as "Skip installing/uninstalling module overrides". On 9.2.0, install --skip-overrides really did install the module without creating the override (no block for the module in the shop file), but uninstall --skip-overrides still removed the module’s override block. If you need to keep an override after uninstalling a module, copy the file elsewhere first.

If the module’s override/ folder disappears from disk before the module is uninstalled, the override stays behind in override/classes/, because uninstall reads the module’s own file to know what to remove. Delete the file and var/cache/<env>/class_index.php by hand in that case.

The Performance page of the back office has a switch "Disable all overrides" (the setting PS_DISABLE_OVERRIDES). In 9.2.0 the code that reads this key is the back office template lookup of the legacy AdminController; the form clears the class index when saved. Setting the key to 1 from the console and rebuilding the class index did not stop the class override above from running (the header was still sent), so do not rely on the switch as a kill switch for a misbehaving class override; uninstall the module or remove the file from override/ instead, then clear the cache.

An override copies the signature and behaviour of a core method at the time it was written. When the core changes the method, the override silently runs with the old assumptions or breaks with a fatal error. After every PrestaShop update, rerun the override’s scenarios, and compare the methods you override with the new core version. The files under override/ are the inventory of what the shop carries; the comment blocks name the module, the date and the version of every method.

The override above only adds an HTTP header after the controller content is initialised. The hook actionFrontControllerInitAfter is executed by every front controller at that point, so the same effect needs no core class at all: the module registers the hook (in install() and in the 1.2.0 script, as shown above) and sends the header in hookActionFrontControllerInitAfter. The shop answered with X-Pcfe46-Hook: 1.2.0 next to the override’s header. Hooks of the same name from many modules coexist, so this is always the first choice. When the existing hooks do not expose what you need, propose a new hook in the core repository (the docs encourage a pull request).

Source: PrestaShop devdocs: Hooks

A class that only adds helpers can extend the core class under its own name (class MyCustomTools extends Tools) and be used from the module’s own code. Nothing is replaced, so every other module keeps seeing the original, and the class lives in the module’s src/ folder. Likewise, a controller of the module can extend a core controller to reuse its features. This was not run here, because it needs no PrestaShop mechanism.

PrestaShop 9 builds a large part of the back office on the Symfony container, and a module can modify the container definition through its config/services.yml. Replacing a service means declaring your own definition under the existing id: the original disappears and every consumer gets the replacement. Decorating it means declaring a new service that wraps the old one: the container gives the decorator the original service under the id <decorator id>.inner, and every consumer of the original id gets the decorator.

The documentation example decorates prestashop.core.b2b.b2b_feature. On 9.2.0 that id is an alias that is deprecated since 9.0 (the container definition says so) pointing at the class id PrestaShop\PrestaShop\Core\B2b\B2bFeature, which is final and implements FeatureInterface. The real, supported id is the class, and the decorator must implement the interface, not extend the class. The decorator counts how often the shop asks whether B2B is active, and declares itself with the Symfony attribute (the core uses the same attribute in its own API code):

Source: Symfony: How to decorate services

A small back office controller shows that a consumer receives the decorator. It asks for the service by its class id but types the parameter with the interface, because a consumer that type-hints the final class would reject the decorator:

Source: PrestaShop devdocs: Services

Source: Symfony: How to decorate services

After bin/console cache:clear, bin/console debug:container 'PrestaShop\PrestaShop\Core\B2b\B2bFeature' reported the class id as a private alias of PrestaShop\Module\Pcfe46\Decorator\CountingB2bFeature, with the tag container.decorator (id and inner service named), and listed the core consumers (CustomerType, the customer grid factory, the customer form data provider and handler) among its users. The route returned:

and the Customers page, which consumes the same service, still rendered. The same decoration can be written without the attribute, in YAML, with decorates: and arguments: ['@.inner'].

Source: PrestaShop devdocs: Services, Override an existing Symfony service

The caveats from the docs are real. The decorator must stay compatible with every consumer: if a consumer type-hints an interface, implement it; if it type-hints a class that is not final, extend the class. If you need to know the id of a service, bin/console debug:container <part of the name> lists it. A replacement (same id, new class) is documented but was not run: it removes the original, so only one module can do it.

Back office controllers are services, so they can be decorated too. The docs show the pattern for the Design  Pages controller; on 9.2.0 the action has a long signature with autowired attributes, so the decorator extends CmsPageController to keep the type, receives the original as .inner, repeats the signature of the action it wants to change (the route resolves the action arguments from the decorator’s method) and delegates:

Requesting improve/design/cms-pages/ as the administrator rendered the normal "Pages" screen and the response carried X-Pcfe46-Decorated: cms-pages. No routing change was needed. The routes of the page still point at CmsPageController::indexAction; the container returns the decorator for that service id. The security attribute of the decorated action is repeated on the decorator so that the page keeps its permission check; whether it would be inherited without it was not tested. If you need to change the route itself, the docs give two further tools: remapping a route to a controller of your module (declare the same route name in config/routes.yml with _disable_module_prefix: true) and replacing the controller service entirely, which the docs advise against unless you rewrite the whole controller. Neither was run.

Source: PrestaShop devdocs: Override or decorate a core controller

A theme may replace a module’s template without touching the module: put a file at the same relative path under themes/<theme>/modules/<module>/. For pcfe46 that is themes/hummingbird/modules/pcfe46/views/templates/hook/club.tpl:

After clearing the compiled Smarty templates (var/cache/<env>/smarty/compile and .../cache) the product page printed this paragraph instead of the module’s. Without that clearing, the page still showed the module’s original output. This is the supported way for a theme to change what a module displays, and a module cannot do the opposite to a theme.

Source: PrestaShop devdocs: Overrides, Theme template override