Crear un módulo en PrestaShop desde cero: tutorial para novatos

Introducción: ¿Qué necesitas para crear tu primer módulo en PrestaShop?

Si estás leyendo esto, probablemente ya tienes una tienda online con PrestaShop y te has dado cuenta de que, aunque es una plataforma muy completa, a veces necesitas una función extra que no viene de serie. La solución más común es instalar un módulo, pero ¿y si te dijera que puedes crear el tuyo propio desde cero? No necesitas ser un gurú de la programación para empezar. Con conocimientos básicos de PHP, HTML y un poco de lógica, puedes dar tus primeros pasos en el desarrollo PrestaShop.

En esta guía, pensada para principiantes absolutos, te voy a explicar paso a paso cómo crear un módulo básico que mostrará un mensaje de bienvenida personalizado en la página de inicio de tu tienda. A lo largo del camino, entenderás la estructura de los módulos PrestaShop, aprenderás a programar PrestaShop de forma segura y resolverás las dudas más frecuentes que surgen al empezar.

No te preocupes si al principio ves cosas que no entiendes del todo. Iremos despacio, con ejemplos claros y explicaciones sencillas. Al final de este artículo, habrás creado tu primer módulo funcional y, lo más importante, habrás aprendido la lógica que hay detrás de cualquier módulo de PrestaShop.

¿Qué es un módulo en PrestaShop y por qué te conviene crearlos?

Antes de ponernos manos a la obra, es fundamental entender qué es un módulo. En términos sencillos, un módulo es un paquete de código que se conecta a PrestaShop para añadir funcionalidades nuevas o modificar las existentes. Piensa en ello como una aplicación para tu tienda, tal y como instalas apps en tu móvil.

La arquitectura básica: el patrón MVC

PrestaShop (desde la versión 1.5 en adelante) se basa en un patrón de diseño llamado MVC (Modelo-Vista-Controlador). No te asustes con el nombre, es más simple de lo que parece:

Modelo: Se encarga de la lógica de negocio y de hablar con la base de datos (guardar, borrar, actualizar información).
Vista: Es la parte visual, las plantillas que el usuario ve en el navegador (los archivos .tpl).
Controlador: Es el intermediario. Recibe las peticiones del usuario, consulta al modelo y le dice a la vista qué mostrar.

Cuando creas un módulo, básicamente estás empaquetando estos tres componentes (y algunos más) en una carpeta específica. PrestaShop se encarga de "conectarlo" al resto del sistema mediante un archivo principal llamado {nombre_del_modulo}.php.

¿Por qué es útil saber esto?

Conocer esta estructura te permitirá crear módulos PrestaShop con lógica, no solo copiar y pegar código. Entenderás dónde va cada cosa y por qué, lo cual es la clave para el desarrollo de módulos más complejos en el futuro. Además, cuando tengas un error, sabrás buscarlo en el lugar correcto.

Requisitos previos y preparación del entorno

Para empezar a programar PrestaShop, necesitas un entorno de desarrollo local. No te recomiendo que experimentes directamente en tu tienda en producción (la real), ya que un error podría dejarla inaccesible.

Herramientas que necesitas

Un servidor local: Puedes usar herramientas como XAMPP, WAMP o Laragon. Estas instaladas en tu ordenador te permiten simular un servidor web con PHP y MySQL.
Una instalación limpia de PrestaShop: Descarga la última versión estable desde el sitio oficial y móntala en tu servidor local.
Un editor de código: Puedes usar el Bloc de Notas, pero es mucho mejor usar un editor con resaltado de sintaxis como Visual Studio Code, Sublime Text o Notepad++.
Acceso a la carpeta de módulos: Necesitas poder ver y crear archivos dentro de la carpeta modules de tu instalación de PrestaShop.

Configuración inicial

Una vez que tengas todo instalado, asegúrate de que tu PrestaShop local funcione correctamente. Accede al panel de administración (normalmente en /admin) y ve a la sección de "Parámetros avanzados" -> "Rendimiento". Si tienes la opción de "Forzar la compilación de las plantillas", actívala. Esto hará que los cambios en los archivos de plantilla (.tpl) se vean al instante, sin tener que borrar la caché manualmente.

[INFO] Trabajar en local es la forma más segura de aprender. Si metes la pata, solo tienes que borrar la carpeta del módulo y empezar de nuevo sin causar daños a una tienda real.

Paso 1: La estructura de carpetas de tu módulo

Todo módulo PrestaShop vive dentro de su propia carpeta en modules/. El nombre de la carpeta es muy importante: debe ser único, en minúsculas y sin espacios ni caracteres especiales. Para este ejemplo, llamaremos a nuestro módulo mimodulobienvenida.

Dentro de esta carpeta, necesitaremos al menos los siguientes archivos:

mimodulobienvenida.php: El archivo principal del módulo. Contiene la clase principal.
logo.png: (Opcional) Un icono de 32x32 píxeles que aparecerá en el listado de módulos. Si no lo pones, se usará uno genérico.
views/: Esta carpeta contendrá las vistas (plantillas .tpl).
- views/templates/
  - front/: Para plantillas que se muestran en la parte pública de la tienda.
  - admin/: Para plantillas que se muestran en el panel de administración.
config.xml: (Opcional) Un archivo de configuración que PrestaShop puede generar automáticamente al instalar el módulo. No es necesario crearlo a mano.

Vamos a crear la estructura:

Ve a tu carpeta modules y crea una nueva carpeta llamada mimodulobienvenida.
Dentro de mimodulobienvenida, crea las carpetas views, views/templates y views/templates/front.

Paso 2: El archivo principal del módulo

Ahora viene la parte más importante. Vamos a crear el archivo mimodulobienvenida.php. Este archivo define la clase principal del módulo, que debe extender la clase base Module de PrestaShop.

Crea el archivo y pega el siguiente código:

<?php
// El nombre de la clase debe ser igual al nombre de la carpeta, pero en CamelCase.
if (!defined('_PS_VERSION_')) {
    exit;
}

class MiModuloBienvenida extends Module
{
    public function __construct()
    {
        $this->name = 'mimodulobienvenida';
        $this->tab = 'front_office_features';
        $this->version = '1.0.0';
        $this->author = 'Tu Nombre';
        $this->need_instance = 0;
        $this->ps_versions_compliancy = [
            'min' => '1.7',
            'max' => _PS_VERSION_
        ];
        $this->bootstrap = true;

        parent::__construct();

        $this->displayName = $this->l('Módulo de Bienvenida');
        $this->description = $this->l('Muestra un mensaje de bienvenida en la página de inicio.');
        $this->confirmUninstall = $this->l('¿Seguro que quieres desinstalar este módulo?');

        // La configuración por defecto
        if (!Configuration::get('MI_MODULO_BIENVENIDA_MENSAJE')) {
            $this->mensaje_por_defecto = '¡Bienvenido a nuestra tienda!';
        } else {
            $this->mensaje_por_defecto = Configuration::get('MI_MODULO_BIENVENIDA_MENSAJE');
        }
    }

    public function install()
    {
        // Instalamos la configuración por defecto
        if (!parent::install()
            || !Configuration::updateValue('MI_MODULO_BIENVENIDA_MENSAJE', '¡Bienvenido a nuestra tienda!')
            || !$this->registerHook('displayHome')
        ) {
            return false;
        }

        return true;
    }

    public function uninstall()
    {
        // Eliminamos la configuración al desinstalar
        return parent::uninstall()
            && Configuration::deleteByName('MI_MODULO_BIENVENIDA_MENSAJE');
    }

    public function hookDisplayHome()
    {
        // Esta función se llama cuando el hook 'displayHome' se ejecuta.
        $this->context->smarty->assign('mensaje_bienvenida', $this->mensaje_por_defecto);
        return $this->display(__FILE__, 'views/templates/front/mensaje.tpl');
    }
}

Vamos a analizar el código pieza por pieza:

Línea 3-5: Esta es una medida de seguridad. Impide que el archivo se ejecute directamente si no es dentro del contexto de PrestaShop.
Línea 7: class MiModuloBienvenida extends Module. Aquí definimos la clase. El nombre es la versión en CamelCase de mimodulobienvenida (Mi + Modulo + Bienvenida). Es crucial que coincida.
Línea 9-25 (__construct): Es el constructor. Aquí se definen las propiedades básicas del módulo.
- $this->name: El nombre de la carpeta.
- $this->tab: La categoría del módulo en el mercado de PrestaShop. front_office_features es para funciones de la tienda.
- $this->version, $this->author: Información básica.
- $this->ps_versions_compliancy: Indica que el módulo es compatible con PrestaShop 1.7 y versiones posteriores.
- $this->bootstrap: Habilita el uso de la librería CSS/JS de Bootstrap en el panel de administración, lo que facilita crear configuraciones bonitas.
Línea 27-39 (install): Este método se ejecuta cuando instalas el módulo. Es el momento de crear configuraciones, tablas en la base de datos y registrar los hooks que queremos usar.
- parent::install(): Llama al método install de la clase padre.
- Configuration::updateValue(...): Guarda un valor en la tabla de configuración de PrestaShop.
- $this->registerHook('displayHome'): Esta es la clave. Le dice a PrestaShop que nuestro módulo quiere "engancharse" al hook displayHome, que se ejecuta en la página de inicio.
Línea 41-47 (uninstall): El método inverso. Se asegura de limpiar todo lo que nuestro módulo haya creado.
Línea 49-54 (hookDisplayHome): Este es el método que se llama cuando el hook displayHome se ejecuta. El nombre del método debe ser hook + el nombre del hook en CamelCase (displayHome -> hookDisplayHome).
- $this->context->smarty->assign(...): Pasamos una variable llamada mensaje_bienvenida a la plantilla.
- $this->display(...): Le dice a PrestaShop qué plantilla debe renderizar.

Paso 3: Crear la plantilla (Vista)

Ahora necesitamos crear la plantilla que mostrará el mensaje. Vamos a crear el archivo mensaje.tpl dentro de views/templates/front/.

Crea el archivo mensaje.tpl con este contenido:

<div class="alert alert-info">
    <h2>{$mensaje_bienvenida}</h2>
</div>

Explicación:

<div class="alert alert-info">: Usamos una clase de Bootstrap que ya incluye PrestaShop para que se vea bonito.
<h2>{$mensaje_bienvenida}</h2>: Aquí es donde se muestra la variable que asignamos en el método hookDisplayHome. En Smarty (el motor de plantillas de PrestaShop), las variables se muestran entre llaves { } y con el símbolo $ delante.

[TIP] Asegúrate de que el nombre de la variable en la plantilla ({$mensaje_bienvenida}) coincida exactamente con el que usaste en el método assign() ('mensaje_bienvenida').

Paso 4: Instalar y probar tu módulo

Este es el momento de la verdad. Vamos a instalar nuestro módulo en PrestaShop.

Ve al panel de administración de tu tienda local.
Navega a "Módulos" -> "Módulos y servicios".
En el buscador, escribe "mimodulobienvenida". Debería aparecer en la lista, quizás con el icono genérico.
Haz clic en el botón "Instalar".
Si todo ha ido bien, verás un mensaje de éxito. Si hay algún error, PrestaShop te mostrará un mensaje que te ayudará a depurar.

Ahora, ve a la página de inicio de tu tienda (la parte pública). Deberías ver tu mensaje de bienvenida en la parte superior de la página, dentro de un recuadro azul claro.

¡Felicidades! Acabas de crear un módulo PrestaShop funcional.

Paso 5: Añadir configuración avanzada (Opcional pero muy útil)

Un buen módulo no solo muestra algo, sino que permite al administrador configurarlo. Vamos a añadir una pantalla de configuración simple para que puedas cambiar el mensaje desde el panel de administración.

Modificar el archivo principal

Añadiremos los métodos getContent() y postProcess() a nuestra clase.

// ... (al final de la clase, antes de la última llave)

public function getContent()
{
    $output = null;

    // Si el formulario ha sido enviado
    if (Tools::isSubmit('submit' . $this->name)) {
        // Recogemos el valor del campo 'MI_MODULO_BIENVENIDA_MENSAJE'
        $mensaje = Tools::getValue('MI_MODULO_BIENVENIDA_MENSAJE');
        
        // Validamos que no esté vacío
        if (!$mensaje || empty($mensaje)) {
            $output .= $this->displayError($this->l('El mensaje no puede estar vacío.'));
        } else {
            // Guardamos el valor en la configuración
            Configuration::updateValue('MI_MODULO_BIENVENIDA_MENSAJE', $mensaje);
            $output .= $this->displayConfirmation($this->l('Configuración actualizada.'));
        }
    }

    // Mostramos el formulario
    return $output . $this->displayForm();
}

public function displayForm()
{
    // Iniciamos el formulario
    $fields_form = [
        'form' => [
            'legend' => [
                'title' => $this->l('Configuración'),
            ],
            'input' => [
                [
                    'type' => 'text',
                    'label' => $this->l('Mensaje de bienvenida'),
                    'name' => 'MI_MODULO_BIENVENIDA_MENSAJE',
                    'required' => true,
                ],
            ],
            'submit' => [
                'title' => $this->l('Guardar'),
                'class' => 'btn btn-default pull-right',
            ],
        ],
    ];

    $helper = new HelperForm();
    $helper->module = $this;
    $helper->name_controller = $this->name;
    $helper->token = Tools::getAdminTokenLite('AdminModules');
    $helper->currentIndex = AdminController::$currentIndex . '&configure=' . $this->name;
    $helper->title = $this->displayName;
    $helper->submit_action = 'submit' . $this->name;

    // Rellenamos el campo con el valor actual de la configuración
    $helper->fields_value['MI_MODULO_BIENVENIDA_MENSAJE'] = Configuration::get('MI_MODULO_BIENVENIDA_MENSAJE');

    return $helper->generateForm([$fields_form]);
}

Explicación:

getContent(): Este método es llamado automáticamente por PrestaShop cuando haces clic en el botón "Configurar" del módulo.
postProcess(): Lo hemos integrado dentro de getContent(). Es donde procesamos los datos del formulario cuando se envía.
displayForm(): Este método genera el HTML del formulario usando la clase HelperForm