Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 30 ยท Hooks

Overrides vs Hooks

Understand PrestaShop class and controller overrides, why they conflict between modules, and which safer alternatives (hooks, service decoration) to use instead.

Sometimes a hook is not enough: the behavior you need to change lives inside a core method, and no hook is fired around it. PrestaShop offers a second tool for that case, the override. An override replaces or extends a core class, so every part of the shop that uses that class now runs your code.

That power is also the danger. Overrides are global, only one can exist per class method, they interact badly with other modules, and they can break after a core upgrade. This lesson explains how overrides work, what goes wrong with them, and what to do instead. It assumes you know how hooks work and have seen how to add your own.

Real override files need a running PrestaShop and cannot run here. The runnable examples are stand-ins that model how overrides are merged and where they collide. They are not PrestaShop code.

How an override works

PrestaShop's legacy classes come in pairs. The real implementation is in a class whose name ends in Core (for example ProductCore, in classes/Product.php). The class you use in code, Product, is an empty shell that extends it. The autoloader decides what Product really is:

  • With no override, Product is the empty shell.
  • With an override, Product is replaced by your class, which extends ProductCore.

An override file lives in the shop's override/ folder, mirroring the core path, and extends the Core class:

PHP
<?php
// override/classes/Cart.php (read-only; the signature is the one of recent 8.x releases: copy yours from the installed core)
class Cart extends CartCore
{
    /*
    * module: acmegift
    * date: 2026-01-12 10:00:00
    * version: 1.0.0
    */
    public function getOrderTotal(
        $withTaxes = true,
        $type = Cart::BOTH,
        $products = null,
        $id_carrier = null,
        $use_cache = false,
        bool $keepOrderPrices = false
    ) {
        $total = parent::getOrderTotal($withTaxes, $type, $products, $id_carrier, $use_cache, $keepOrderPrices);

        // custom rule here
        return $total;
    }
}

Two details matter. First, you call parent:: to keep the core behavior and only add yours around it. Second, the comment block with module:, date: and version: is written by PrestaShop when it installs the override from a module; the uninstaller uses it to know which methods belong to which module. Never delete those comments by hand.

Other places overrides can live:

What Folder
Core classes (Product, Cart, Tools) override/classes/
Front controllers (ProductController) override/controllers/front/
Admin controllers (legacy pages) override/controllers/admin/
Classes of another module override/modules/<modulename>/

Modules ship overrides

The proper way to deliver an override is inside a module. Put the file in modules/<name>/override/classes/Cart.php. When the module is installed, Module::install() calls its override installer, which merges the module's methods into the shop's override/classes/Cart.php (creating the file if needed). When the module is uninstalled, the module's methods are removed again. Hand-editing the shop's override/ folder works, but then nothing tracks it and nobody remembers it exists.

The class index

PrestaShop's autoloader keeps a map from class names to files, stored in a cache file called class_index.php (under var/cache/<environment>/). When you add or remove an override, the index must be rebuilt, otherwise the shop keeps loading the old class. Installing and uninstalling a module usually triggers a rebuild, and clearing the cache always does. If an override seems to do nothing, clear the cache first.

flowchart LR
    A["new Cart()"] --> B["Autoloader<br/>reads class_index.php"]
    B --> C{"override file<br/>listed?"}
    C -->|"no"| D["classes/Cart.php<br/>empty shell: Cart extends CartCore"]
    C -->|"yes"| E["override/classes/Cart.php<br/>Cart extends CartCore"]
    D --> F["CartCore<br/>real code"]
    E --> F

An override swaps the empty shell class for your class; both end up extending the real CartCore.

Why overrides cause trouble

  1. Only one override per method. The shop has a single override/classes/Cart.php. If two modules both define getOrderTotal(), the second cannot be installed. PrestaShop stops the installation with an error saying the method is already overridden by the other module. The merchant must then choose one module.
  2. Global effect. Every code path that uses Cart runs your method: the product page, the checkout, the webservice, scheduled tasks. A bug is a shop-wide bug, and a fatal error in an override file can take down the whole storefront and the back office.
  3. Upgrade fragility. If a new PrestaShop version changes the parent method (arguments, return type), your override may no longer match. PHP then fails with a signature error, or worse, silently behaves differently.
  4. Hidden behavior. The merchant sees nothing in the module list that explains why prices differ. Debugging needs you to remember to look in override/.
  5. Performance. Overrides add a file to the autoload map and an extra level of class inheritance for hot classes.
  6. Uninstall pitfalls. Removing a module has to remove exactly its methods. If someone edited the override file by hand, deleted the comment markers, or merged two files, the uninstaller may leave junk or refuse. A leftover override that calls a removed helper breaks the shop.
  7. Not everywhere. Overrides apply to legacy classes (classes/, controllers/). Newer code in src/ that lives in namespaces and is wired by the Symfony container is not overridden this way, and many back office pages run on that newer code.

Merchants can switch all overrides off in the Advanced Parameters > Performance page ("Disable all overrides"). This is a useful debugging step: if the bug disappears, an override is the cause. It also means your override may simply not run, so code that depends on one is fragile.

Choosing the right tool

Use this order of preference:

  1. A hook that already exists around the behavior. Many things are available: actionCartSave, actionProductUpdate, actionObjectXxxAddAfter, displayXxx.
  2. Your own hook, fired by your module, when you control the code path (Creating and Dispatching Your Own Hooks).
  3. Service decoration or replacement for logic that lives in a Symfony service: wrap the service and delegate to the original.
  4. A pull request to PrestaShop that adds a hook or extension point, when a real gap exists.
  5. An override, as the last resort, kept small: one method, calling parent::, documented.

Service decoration (read-only)

In the Symfony part of PrestaShop, services are defined in YAML. A module can define a service that decorates another: the container passes the original service to yours, and every consumer receives your wrapper.

YAML
# modules/acmegift/config/services.yml (read-only; the decorated id is a made-up example)
services:
  Acme\Gift\Pricing\GiftAwareCalculator:
    decorates: 'some.core.price_calculator'
    arguments:
      - '@Acme\Gift\Pricing\GiftAwareCalculator.inner'
PHP
<?php
// read-only
namespace Acme\Gift\Pricing;

final class GiftAwareCalculator implements PriceCalculatorInterface
{
    public function __construct(private PriceCalculatorInterface $inner)
    {
    }

    public function calculate(int $productId): int
    {
        $price = $this->inner->calculate($productId);

        return $price; // adjust here, then return
    }
}

Decoration is safer than an override: it is explicit, the original service stays reachable, several modules can stack decorators, and it only touches what you wrap. It only works for services the container creates, and the service must be written against an interface or at least be a public contract; check the PrestaShop documentation for the service ids that are meant to be decorated in your version.

Stand-in: how overrides merge and collide

The first stand-in models the module-owned override pipeline. A CoreCart class has methods; modules can install an override for a method; the manager records who owns each method, refuses a second owner, calls parent through a callback, and removes a module's methods on uninstall. It is a model of the idea, not of PrestaShop's file merging.

PHP Stand-in: override install, conflict, uninstall

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Notice that the second module could not be installed while the first one owned getOrderTotal, and that the failed install left nothing behind. In a real shop the merchant would have to drop one of the two modules, even though both ideas are reasonable.

The same goal with hooks

Now suppose the core method fired a hook with the total passed by reference, so listeners could adjust it. Both modules could coexist, each doing its part in position order. Core PrestaShop does not provide such a hook for every method, which is exactly why overrides exist, but where a hook is available (or where you can fire your own at a code path you control) it is far friendlier.

PHP Stand-in: two modules cooperating through a hook

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Both modules work at once, uninstalling one does not affect the other, and the core code stays untouched. Note the trade-off: the result depends on listener order (minus 500 then minus 5% is not the same as the reverse), so such a hook must document how the adjustments combine.

If you must override

  • Override the smallest thing, usually one method, and call parent:: so core behavior is kept.
  • Match the parent's signature exactly for the PrestaShop versions you support, and state them in ps_versions_compliance.
  • Ship the override inside a module so it can be installed and removed cleanly; never edit override/ by hand on a client's shop without telling anyone.
  • Keep the module:, date: and version: comment markers.
  • After installing or uninstalling, clear the cache so the class index is rebuilt.
  • Test install, uninstall and reinstall, and test with another popular module that overrides the same class.
  • Describe the override in the module's documentation so support staff can find it.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Two modules both override Cart::getOrderTotal(). What normally happens when the second one is installed?

    A shop has a single override file per class and one definition per method, so PrestaShop stops the second install and reports which module already owns the method.
  2. 2. What is the main reason hooks are preferred over overrides?

    Hooks let many modules cooperate and are designed as extension points. Overrides are global, exclusive per method and fragile across upgrades.
  3. 3. You added a new override file to a module but the shop still runs the old class. What should you try first?

    The autoloader reads a class index from the cache. It must be regenerated for a new or removed override to take effect.
  4. 4. Which approach fits best when the logic you need to change lives in a Symfony service?

    Service decoration wraps the original service and delegates to it. Legacy class overrides do not apply to namespaced Symfony services.
  5. 5. Why should you keep the module/date/version comment above an installed override method?

    PrestaShop writes the marker when merging a module's override and reads it on uninstall to remove exactly that module's methods.

Summary

  • An override replaces the empty shell class (Cart) with your class that extends the ...Core class; modules ship overrides and PrestaShop merges them at install.
  • The class index in the cache must be rebuilt for overrides to take effect; clear the cache when in doubt.
  • Overrides are global, exclusive per method, fragile after upgrades, and tricky to uninstall; they do not apply to namespaced Symfony code.
  • Prefer, in order: an existing hook, your own hook, service decoration, a contribution to core, and only then an override.
  • If you must override, keep it tiny, call parent::, keep the markers, and test install, uninstall and conflicts.

Next, move from hooks to pages of your own: Module Front Controllers.