Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 30 ยท Module Basics

Your First Module

Build a minimal PrestaShop module step by step: constructor properties, version compatibility, display name, a hook, installing it in the back office, plus a registry stand-in.

Now we build one. The module in this lesson is deliberately small: it adds a greeting to the home page. That is enough to touch every mandatory piece: the constructor with its properties, the compatibility range, translated names, install() with a hook, a Smarty template, and the steps to enable it in the back office.

Read the module code carefully but do not worry about every detail yet. Hooks get a whole chapter (Hooks: How Modules Plug In), and templates are covered in Smarty Templates and Theme Integration. The goal here is the shape of a working module and an honest understanding of what each property does. As always, the real module is read-only on this site; the TryIts imitate how a shop lists modules and renders a hook's output.

The files

Create this structure in modules/hellomodule/ (the layout is explained in Anatomy of a Module):

TEXT
modules/hellomodule/
  hellomodule.php
  logo.png
  index.php
  views/templates/hook/hello.tpl
  views/templates/hook/index.php
  views/templates/index.php
  views/index.php

The constructor and its properties

Everything starts with the constructor. These are the properties that PrestaShop reads:

PHP
<?php
// modules/hellomodule/hellomodule.php
if (!defined('_PS_VERSION_')) {
    exit;
}

class Hellomodule extends Module
{
    public function __construct()
    {
        $this->name = 'hellomodule';
        $this->tab = 'front_office_features';
        $this->version = '1.0.0';
        $this->author = 'Your Name';
        $this->need_instance = 0;
        $this->bootstrap = true;
        $this->ps_versions_compliancy = ['min' => '8.0.0', 'max' => _PS_VERSION_];

        parent::__construct();

        $this->displayName = $this->trans('Hello module', [], 'Modules.Hellomodule.Admin');
        $this->description = $this->trans('Greets visitors on the home page.', [], 'Modules.Hellomodule.Admin');
        $this->confirmUninstall = $this->trans('Do you really want to uninstall this module?', [], 'Modules.Hellomodule.Admin');
    }
}

Each property has a job:

  • name: the technical name. It must equal the folder name, use lowercase letters, digits and underscores, and never change after release.
  • tab: the category in which the module is listed in the module manager, for example front_office_features, administration, payments_gateways, shipping_logistics, seo, analytics_stats, pricing_promotion or others. It has no technical effect, only presentation, but pick the closest one.
  • version: your module's version as a string like 1.0.0. PrestaShop compares it with the installed version to decide whether upgrade scripts must run. Use semantic versioning.
  • author: shown to merchants.
  • need_instance: 0 means PrestaShop does not need to create an instance of the class just to show the module list. Almost every module uses 0; it loads the list faster.
  • bootstrap: set it to true if your module's admin page uses the Bootstrap-styled helpers (configuration forms built with HelperForm). Without it the form looks broken in older styling.
  • ps_versions_compliancy: the range of PrestaShop versions you support, as an array with min and max. If the shop's version is outside the range, the module cannot be installed. Using _PS_VERSION_ as the maximum means "up to the current shop", the common choice. Note the exact spelling of this property (with the y); a misspelled property is silently ignored.
  • displayName and description: the title and text in the module list. They are set after parent::__construct() and are translated with $this->trans(). The third argument is the translation domain; for modules it follows the pattern Modules.<Modulename>.Admin for back-office strings and Modules.<Modulename>.Shop for storefront strings. We cover that in Translations and Multilingual Modules.
  • confirmUninstall: the question shown before uninstalling.

In a module for older versions you may also see $this->controllers (a list of front controllers) and $this->limited_countries; neither is needed for this lesson.

install() and a hook

Our module should show a greeting on the home page. For that it registers on the displayHome hook, which the default theme calls in the middle of the home page:

PHP
    public function install()
    {
        return parent::install()
            && $this->registerHook('displayHome')
            && Configuration::updateValue('HELLOMODULE_GREETING', 'Hello, and welcome!');
    }

    public function uninstall()
    {
        return parent::uninstall()
            && Configuration::deleteByName('HELLOMODULE_GREETING');
    }

    public function hookDisplayHome($params)
    {
        $this->context->smarty->assign([
            'hellomodule_greeting' => Configuration::get('HELLOMODULE_GREETING'),
        ]);

        return $this->fetch('module:hellomodule/views/templates/hook/hello.tpl');
    }

Three things happen here:

  1. registerHook('displayHome') writes a row that links the module to the hook. From now on, whenever the page calls that hook, PrestaShop calls your method.
  2. The method name is hook plus the hook name with a capital first letter: hookDisplayHome. It receives an array of parameters from the caller (unused here) and must return the HTML for display hooks.
  3. Configuration::updateValue() stores the default greeting in the shop's configuration table. Configuration::get() reads it. The next lesson, A Module Configuration Page, turns this into a form that merchants can edit.

The template is a plain Smarty file:

SMARTY
{* modules/hellomodule/views/templates/hook/hello.tpl *}
<div class="hellomodule alert alert-info">
  {$hellomodule_greeting|escape:'html':'UTF-8'}
</div>

The escape modifier prints the text safely, so a greeting like <script> would be shown as text instead of running. That habit is explained further in Security in Modules.

flowchart LR
    A["Visitor opens home page"] --> B["Theme template calls<br/>hook displayHome"]
    B --> C["PrestaShop finds modules<br/>registered for the hook"]
    C --> D["hookDisplayHome() runs"]
    D --> E["Configuration::get()<br/>+ Smarty template"]
    E --> F["HTML inserted into the page"]

The theme asks for a hook; PrestaShop calls every registered module's method and inserts what they return.

Installing it in the back office

  1. Put the folder in modules/ (or mount it in Docker; see Setting Up a Development Environment).
  2. Open the back office, go to Modules > Module Manager. If the module is not listed, clear the cache or use the module manager's option to upload a module ZIP.
  3. Search for "Hello module" and click Install. PrestaShop creates your class, calls install() and, if it returned true, shows the module as installed.
  4. Open the shop's home page. The greeting should appear. If it does not, clear the cache and check that the theme actually calls displayHome. Not every theme does, and positions differ.
  5. To test changes in install(), uninstall and install again (or use the module manager's Reset action, or the console command php bin/console prestashop:module reset hellomodule).

From the console, the same module could be installed without opening the back office: php bin/console prestashop:module install hellomodule.

If the module does not appear at all, check these in order: folder name equals module name, the class exists in the main file and is spelled like the folder, the PHP file has no syntax error (read the log), the cache is cleared, and the file starts with <?php without whitespace before it.

A registry stand-in

A real shop keeps modules in database tables and shows a module list built from your class's properties. The first stand-in builds such a list: it reads the properties of a few pretend modules, checks the compatibility range with version_compare(), and prints a status. Only the idea is real: ps_versions_compliancy and version_compare() are how compatibility works.

PHP A module list with compatibility checks

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.

Rendering a hook: a stand-in

The second stand-in imitates what hookDisplayHome does: fetch a setting, assign it to a template, escape it, and return HTML. The template engine here is a few lines of PHP and is not Smarty; the lesson on templates builds a slightly bigger one. What is real: the pattern of "assign values, then render a template that escapes them".

PHP A hook method that renders a template

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 second output shows why escaping matters: the & and the tags are turned into safe entities rather than being interpreted as HTML.

Common first-module problems

  • Nothing happens after install. The theme may not call that hook, or the module is not hooked to it (check Design > Positions in the back office, where every hook and its modules are listed).
  • "Unable to install the module". Usually install() returned false or threw an exception. Turn on dev mode and read the log.
  • Text is untranslated. The domain name did not match the pattern, or the translation was not exported; see the translations lesson.
  • The module cannot be installed because of versions. Your ps_versions_compliancy excludes the shop version.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where in the constructor must displayName be assigned?

    The parent constructor sets up the module (and translation context), so translated display names are set after it.
  2. 2. What does the ps_versions_compliancy property define?

    It is an array with min and max PrestaShop versions. Shops outside the range cannot install the module.
  3. 3. A module registered the hook displayHome. Which method does PrestaShop call?

    Hook methods are named hook plus the hook name with a capital first letter.
  4. 4. Why is escape used in the template for the greeting?

    Escaping converts special characters to entities so values are shown as text, not interpreted as markup.

Summary

  • The constructor sets name, tab, version, author, need_instance, bootstrap and ps_versions_compliancy before parent::__construct(), then the translated displayName and description.
  • install() registers hooks and default configuration; uninstall() removes them; both return booleans.
  • Display hook methods are named hook<HookName> and return HTML, usually from a Smarty template via fetch().
  • Install through Modules > Module Manager or php bin/console prestashop:module install; reset to re-run install().
  • Always escape values in templates.

Next: A Module Configuration Page