Creating a Custom Module in PrestaShop: A Step-by-Step Guide for Developers

If you’re a developer working with PrestaShop, you’ve likely come across situations where default functionality just isn’t enough — and that’s where custom modules come in.

In this guide, we’ll walk through the process of building a basic PrestaShop module. You’ll learn how to:

Set up the folder structure

Register hooks

Display frontend content

Add configuration options in the admin panel

Whether you’re building something simple like a promotional banner or a complex integration, the same fundamentals apply.

Let’s dive in.

📁 Step 1: Create the Module Folder and File
Go to your PrestaShop root directory and navigate to:
/modules

Create a new folder, e.g., mymodule.

Inside that, create a PHP file with the same name:
mymodule.php

Folder Structure:
markdown
Copy
Edit
modules/
└── mymodule/
└── mymodule.php
🧱 Step 2: Define the Module Class
Your module class should extend Module. Here’s a basic setup:

php
Copy
Edit
<?php
if (!defined('PS_VERSION')) {
exit;
}

class MyModule extends Module
{
public function __construct()
{
$this->name = 'mymodule';
$this->tab = 'front_office_features';
$this->version = '1.0.0';
$this->author = 'Your Name';
$this->need_instance = 0;

    parent::__construct();

    $this->displayName = $this->l('My Custom Module');
    $this->description = $this->l('Displays a custom message on the homepage.');
}

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

public function uninstall()
{
    return parent::uninstall();
}

public function hookDisplayHome($params)
{
    return '<p style="text-align:center;">Hello from My Custom Module 👋</p>';
}

}
🪝 Step 3: Register and Use a Hook
We’ve used hookDisplayHome in this example. It outputs HTML on the homepage.

Make sure you go to the Modules → Module Manager in the back office, install your module, and position it correctly via Positions.

🔧 You can explore other hooks like displayFooter, displayNav1, or admin-specific ones.

⚙️ Step 4: Add Configuration in the Back Office
Let’s make it configurable! Add the following methods to your class:

Add the config form:
php
Copy
Edit
public function getContent()
{
$output = '';
if (Tools::isSubmit('submit_mymodule')) {
$custom_message = Tools::getValue('MYMODULE_MESSAGE');
Configuration::updateValue('MYMODULE_MESSAGE', $custom_message);
$output .= $this->displayConfirmation($this->l('Settings updated'));
}

return $output.$this->renderForm();

}

protected function renderForm()
{
$default_lang = (int)Configuration::get('PS_LANG_DEFAULT');

$fields_form[0]['form'] = [
    'legend' => ['title' => $this->l('Settings')],
    'input' => [
        [
            'type' => 'text',
            'label' => $this->l('Custom Message'),
            'name' => 'MYMODULE_MESSAGE',
            'size' => 20,
            'required' => true
        ]
    ],
    'submit' => [
        'title' => $this->l('Save'),
        'class' => 'btn btn-default pull-right'
    ]
];

$helper = new HelperForm();
$helper->module = $this;
$helper->name_controller = $this->name;
$helper->default_form_language = $default_lang;
$helper->allow_employee_form_lang = $default_lang;
$helper->submit_action = 'submit_mymodule';
$helper->fields_value['MYMODULE_MESSAGE'] = Configuration::get('MYMODULE_MESSAGE');

return $helper->generateForm($fields_form);

}
Update the hook output:
php
Copy
Edit
public function hookDisplayHome($params)
{
$message = Configuration::get('MYMODULE_MESSAGE');
return '

' . htmlspecialchars($message) . '

🐞 Common Pitfalls to Avoid
Make sure your module folder name and main class name match (mymodule and mymodule.php).

Always check for Tools::getValue() vs. Configuration::get() usage.

Use htmlspecialchars() or PrestaShop sanitization functions to avoid XSS vulnerabilities.

Clear PrestaShop cache after making changes.

🧪 Bonus: Testing Your Module
Use a staging environment before pushing changes to a live site.

Enable debugging via config/defines.inc.php:

php
Copy
Edit
define('PS_MODE_DEV', true);
Check for errors in /var/logs or browser console if your output doesn’t render.

🚀 Final Thoughts
PrestaShop modules give you huge flexibility as a developer — from tiny UI tweaks to full-featured integrations. This example is basic, but once you understand the fundamentals, you can build almost anything.

If you found this useful or want more advanced tutorials (like admin controller creation, API integrations, or AJAX forms in modules), drop a comment below or follow me!