Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 30 ยท Hooks

Hooks: How Modules Plug In

Understand PrestaShop hooks: display and action hooks, registerHook, hookDisplay and hookAction methods, execution order and positions, discovery, with a dispatcher you can run.

Hooks are the heart of PrestaShop's design. A hook is a named point in the code where the core says: "something is happening here, does any module want to take part?" Modules answer by registering for the hooks they care about. The core never needs to know which modules exist, and modules never need to edit the core. That is how an invoice module, a banner module and a payment module can all work on the same page without knowing about each other.

This lesson explains the two kinds of hooks, how registration and execution work, how the order of modules is decided, and how to find the right hook for a job. The real calls are shown read-only; the stand-ins are a small hook dispatcher that you can run and change, in the spirit of the real Hook class. If hooks look like events from other frameworks, that is exactly the right instinct (see Event Dispatching in PHP for the general pattern).

Two kinds of hooks

Display hooks produce output. They sit inside templates, for example displayHeader, displayHome, displayProductAdditionalInfo or displayFooter. The core calls them and inserts what the modules return. Each registered module's method returns a string of HTML, and the results are concatenated in order.

Action hooks announce that something happened or is about to happen: a product was saved (actionProductSave), an order was validated (actionValidateOrder), a customer registered (actionCustomerAccountAdd). Modules react by doing work, such as sending data to a CRM or updating a table. Their return value is normally ignored. Many action hooks pass objects in the parameters, so that modules can read them (and, for some hooks, change them).

The naming convention helps: names that begin with display are for output, names that begin with action are for events. A few hooks, such as filter... hooks in newer versions, let modules transform a value; their documentation tells you what to return.

Registering and the hook method

A module attaches itself to a hook with registerHook(), usually in install():

PHP
public function install()
{
    return parent::install()
        && $this->registerHook('displayHome')
        && $this->registerHook('actionValidateOrder');
}

public function hookDisplayHome(array $params)
{
    return $this->fetch('module:hellomodule/views/templates/hook/home.tpl');
}

public function hookActionValidateOrder(array $params)
{
    /** @var Order $order */
    $order = $params['order'];
    // for example: log the order reference somewhere
}

registerHook() writes a row into the hook_module table that links your module to the hook. The method that runs is named hook plus the hook name with a capital first letter: hookDisplayHome, hookActionValidateOrder. You can also register a list of hooks at once by passing an array, and unregisterHook() removes a registration. If the method does not exist, the registration does nothing useful, so a misspelled method name is a classic silent bug.

Hooks are registered at install time. If you add a new hook to an existing module, the already-installed copies do not know about it until you re-register, which is a job for an upgrade script (Tables, Installers and Upgrades). The same applies to reinstalling during development: use Reset so that install() runs again.

How a hook is executed

When a template contains {hook h='displayHome'}, or PHP code calls Hook::exec('displayHome'), PrestaShop:

  1. looks up the hook by name (and resolves aliases: old hook names that still work, such as legacy names kept for backward compatibility),
  2. finds all modules registered to it, in their stored position order, restricted to modules that are enabled for the current shop and not excluded for the current page,
  3. calls each module's hook<Name> method with the parameters,
  4. for display hooks, concatenates the returned strings and outputs them.
flowchart TD
    A["Template: {hook h='displayHome'}<br/>or Hook::exec('displayHome')"] --> B["Find the hook<br/>(resolve aliases)"]
    B --> C["Load registered modules<br/>ordered by position"]
    C --> D["Call hookDisplayHome()<br/>of module 1"]
    D --> E["Call hookDisplayHome()<br/>of module 2"]
    E --> F["Concatenate results<br/>into the page"]

A hook call visits each registered module in position order and, for display hooks, joins the outputs.

The parameters you receive depend on the hook. For displayProductAdditionalInfo you get the product; for actionValidateOrder you get the cart, the order, the customer and the order status. Hook documentation lists them, and var_dump(array_keys($params)) in dev mode shows what is there.

Order of execution and positions

When several modules use the same display hook, the order matters: it decides which banner sits above which. The order is stored as a position number per module and hook. Merchants change it in the back office under Design > Positions by dragging modules up and down. There they can also:

  • Transplant a module to another hook (the module must implement a method for that hook),
  • Edit a module's registration to add exceptions: pages on which the module should not appear,
  • Unhook a module from a hook.

As a module author, you cannot rely on being first or last. If your output must be visible, make it self-contained; if you depend on another module's data, check that it exists. For action hooks, the same ordering applies, so two modules that modify the same object in actionProductSave run one after the other and see each other's changes. Write action hook code defensively and make no assumption about who ran before.

The display order is per shop in a multistore setup. A module can be at position 1 on one shop and position 5 on another.

Finding the right hook

You have three practical ways to discover hooks:

  1. Design > Positions lists every hook that exists in the shop, and with the "show available hooks only" option, only those that the active theme and modules actually call. Hovering shows the hook description. This is the quickest way to see where display hooks are placed in your theme.
  2. The theme's templates. Search the theme for {hook h= to see exactly where the display hooks sit, and the core for Hook::exec( to find action hooks.
  3. The developer documentation lists hooks by area (product page, cart, checkout, orders, customers), with their parameters.

A good question to ask: "Is this about showing something (display) or reacting to something (action)?" Then pick the hook closest to the thing you want. Choosing a too-general hook such as displayHeader to add product-page content is a common mistake, because your code then runs on every page.

Writing hook code safely

  • Return the output, never echo it from a display hook; echoed text appears at the wrong position or breaks JSON responses.
  • Check conditions early. A hook method runs on every call of the hook, so test whether you are on the right page or whether the feature is on, and return an empty string otherwise.
  • Keep it fast. A slow hook slows every page that calls it. Avoid queries inside loops; see Performance and Caching.
  • Do not assume parameter keys. Check with isset() or the null-safe operator before using them.
  • One responsibility per hook method. If your module needs different work for different hooks, keep each method small and call shared services from them.

A hook dispatcher you can run

The first stand-in is a small hook system with registration, positions and an exec() method that concatenates display output. It is not the PrestaShop Hook class (which uses database tables, caching, shop contexts and aliases) but it reproduces the visible behavior: modules are called in position order, a module without a method for the hook is skipped, and unregistering removes it.

PHP A tiny hook dispatcher

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.

Note the Typo class: its method is named hookDisplayHom, so the dispatcher never finds a method for the hook and silently skips it. Nothing fails and nothing appears, which is exactly how a misspelled hook method behaves in a real module. When a hook output is missing, compare the method name with the hook name letter by letter.

Display versus action in code

The second stand-in shows the two kinds side by side: a display hook whose results are joined, and an action hook that receives an object and where modules run in order and see each other's changes.

PHP Display hooks return output, action hooks react

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.

The try/catch in the stand-in is a teaching choice, not a statement about what PrestaShop does when a hook throws. In your own hook methods, assume that an uncaught exception may stop the page, so catch the errors of optional integrations (an offline ERP, a failing HTTP call) and log them rather than breaking checkout.

Hooks and Symfony events

In newer PrestaShop versions the hook system is connected to the Symfony event dispatcher: calling a hook can also dispatch a Symfony event with the hook's name, so that Symfony-style listeners and subscribers can respond too. Existing hook-based modules keep working unchanged. For now, treat classic hook... methods as the standard way for modules to plug in; Creating and Dispatching Your Own Hooks returns to the event side.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the difference between display hooks and action hooks?

    Display hooks return HTML that is joined into the page; action hooks tell modules that something happened and their return value is normally ignored.
  2. 2. A module registered for the hook displayProductAdditionalInfo. Which method must it have?

    Hook methods are named hook followed by the hook name with a capital first letter.
  3. 3. Where does a merchant change the order in which modules appear in a display hook?

    Positions are stored per module and hook and edited by drag and drop under Design > Positions.
  4. 4. You add registerHook('displayFooter') to install() of a module that is already installed in many shops. What happens in those shops?

    install() runs once. Existing installations need the registration in an upgrade script or a reset.
  5. 5. Why should a display hook method return a string instead of echoing it?

    The caller joins return values into the right spot of the page. Echoed output bypasses that and can break layouts or JSON responses.

Summary

  • Hooks are named extension points; modules register for them and the core stays unaware of specific modules.
  • Display hooks return HTML that is concatenated into pages; action hooks announce events and receive objects in $params.
  • registerHook() (usually in install()) links a module to a hook; the method is hook<HookName>.
  • Execution follows the stored position order, editable under Design > Positions, with per-page exceptions and transplanting.
  • Find hooks in Positions, in theme templates and in the developer documentation; keep hook methods fast, defensive and return-only.
  • Newly added hooks need an upgrade script for shops that already have the module.

Next: Common Front Office Hooks