Índice

  1. Introducción

  2. ¿Qué es un módulo Dolibarr?

  3. La arquitectura central de Dolibarr

  4. Cómo encajan los módulos en la arquitectura de Dolibarr

  5. Directorio y estructura de archivos de un módulo típico

  6. El papel del descriptor del módulo

  7. Ganchos, activadores y eventos: ampliación de la funcionalidad principal

  8. Administración de tablas de bases de datos en módulos

  9. Creación de interfaces: páginas, formularios, plantillas

  10. Integración con funciones principales (menús, permisos, archivos PDF)

  11. Mejores prácticas para la personalización sin modificar el núcleo

  12. Errores comunes y cómo evitarlos

  13. Escenarios de personalización avanzados

  14. Mantener la compatibilidad entre las versiones de Dolibarr

  15. Conclusión

  16. Recursos y referencias para desarrolladores


1. Introducción

Dolibarr ERP & CRM se ha convertido en una plataforma de gestión empresarial de código abierto ampliamente adoptada gracias a su flexibilidad, escalabilidad y facilidad de uso. Lo que hace a Dolibarr particularmente potente es su Arquitectura modularEste diseño permite a los desarrolladores y empresas personalizar y ampliar el software sin alterar los archivos principales, lo que garantiza un entorno estable y seguro para las actualizaciones.

Este artículo proporciona una Análisis profundo de la arquitectura de los módulos DolibarrAyuda a desarrolladores y profesionales de TI a comprender el funcionamiento interno de los módulos. Tanto si planea crear un nuevo módulo desde cero como personalizar los existentes, esta guía le proporcionará una comprensión detallada de cómo hacerlo de forma eficaz, profesional y conforme a las mejores prácticas.


2. ¿Qué es un módulo Dolibarr?

A módulo Dolibarr es un paquete autónomo que añade nuevas funcionalidades al sistema ERP. Estas pueden incluir:

  • Creación de nuevos objetos de negocio (por ejemplo, contratos, tickets, certificaciones)

  • Agregar nuevos informes o paneles

  • Integración con API de terceros

  • Modificar flujos de trabajo o interfaces de usuario existentes

Los módulos permiten ambas cosas interfaz de usuario (UI) y back-end (lógica, base de datos) cambios manteniendo la compatibilidad con el ciclo de actualización de Dolibarr.

Los módulos pueden ser:

  • Módulos centrales:Enviado con Dolibarr por defecto

  • Módulos de terceros:Instalado desde el Dolistore o desarrollado a medida

  • Módulos personalizados/privados:Construido para uso interno, residiendo en /htdocs/custom/


3. La arquitectura central de Dolibarr

Dolibarr está desarrollado principalmente con PHP y se ejecuta en una pila LAMP o LEMP. Su arquitectura se basa en:

  • Arquitectura de entrada única:Todas las solicitudes pasan por main.inc.php

  • Estructura tipo MVC:Modelado libremente con objetos, controladores y plantillas.

  • Capa modular:Los módulos se cargan dinámicamente y agregan funcionalidad en tiempo de ejecución

  • Modelo de seguridad basado en permisos

  • Configuración global mediante $conf y $user objetos

  • Capa de abstracción de la base de datos Construido sobre SQL sin procesar con funciones auxiliares

Cada componente de Dolibarr, ya sean facturas, clientes o productos, se crea utilizando un modelo de objeto base que puede ampliarse mediante módulos.


4. Cómo encajan los módulos en la arquitectura de Dolibarr

Los módulos se ubican sobre la aplicación principal e interactúan con ella a través de:

  • Escuchadores de eventos (desencadenantes)

  • Ganchos (complementos a nivel de interfaz)

  • Páginas y formularios personalizados

  • Permisos y adiciones al menú

  • Extensiones de tablas de bases de datos

  • Puntos finales de la API REST (opcional)

Cuando se activa un módulo, Dolibarr carga dinámicamente:

  • Sus menús

  • Permisos

  • Configuraciones personalizadas

  • Gatillos y ganchos

  • Objetos personalizados (clases, plantillas, formularios)

Esta separación asegura desarrollo modular limpio y personalización segura para actualizaciones.


5. Directorio y estructura de archivos de un módulo típico

¡Comprende la estructura de un módulo es esencial para una personalización adecuada.

A continuación se muestra un desglose de una carpeta de módulo estándar ubicada en /htdocs/custom/mymodule/:

pitón

mymodule/ ├── admin/ # Backend config pages ├── class/ # PHP class files (business logic) ├── core/ │ └── triggers/ # System triggers │ └── modules/ # PDF, numbering modules ├── lang/ # Language translation files ├── page/ # Custom user-facing pages ├── sql/ # Install and upgrade SQL scripts ├── tpl/ # Template files for UI ├── modMyModule.class.php # Module descriptor

Cada carpeta cumple una función distinta al permitir la funcionalidad y al mismo tiempo mantener el módulo organizado y mantenible.


6. El papel del descriptor del módulo

En el corazón de cada módulo de Dolibarr se encuentra su clase descriptora, normalmente llamado modMyModule.class.php.

Este archivo contiene:

  • Metadatos básicos (nombre, número, versión, descripción)

  • Habilitar/deshabilitar la lógica

  • Definiciones del menú

  • Declaraciones de permisos

  • URL de la página de configuración

  • Definiciones de esquemas de base de datos

  • Ganchos, desencadenadores y trabajos cron

Fragmento de ejemplo:

php

class modMyModule extends DolibarrModules { public function __construct($db) { $this->numero = 104100; // Unique ID $this->rights_class = 'mymodule'; $this->family = "projects"; $this->name = "MyModule"; $this->description = "A module to manage certifications."; $this->version = '1.0.0'; $this->const_name = 'MAIN_MODULE_MyModule'; $this->dirs = array("/mymodule/temp"); $this->config_page_url = array("admin_mymodule.php@mymodule"); $this->menu = array(); // Add menus $this->rights = array(); // Add permissions } }

Este archivo se ejecuta cuando se activa el módulo en el panel de administración.


7. Ganchos, desencadenadores y eventos: ampliación de la funcionalidad principal

Dolibarr proporciona dos mecanismos clave para ampliar la funcionalidad principal sin modificarlo:

Desencadenadores 7.1

Los activadores son detectores de eventos que se ejecutan durante acciones del sistema como:

  • Creando facturas

  • Eliminar productos

  • Validación de pedidos

Las clases de activación se colocan en /core/triggers/ y nombrado como interface_99_modMyModule_MyTriggers.class.php.

Ellos implementan el DolibarrTriggers interfaz y un runTrigger() método.

Ejemplo:

php

public function runTrigger($action, $object, $user, $langs, $conf) { if ($action == 'BILL_VALIDATE') { // Custom logic when invoice is validated } return 0; }

7.2 ganchos

Los ganchos inyectan lógica o elementos de interfaz en páginas Dolibarr existentes.

  • Ganchos de UI: Inyecta botones, texto o HTML en las plantillas

  • Ganchos lógicos: amplían la lógica de creación, eliminación y validación de objetos.

Las clases de gancho implementan HookInterface y responder a áreas como formObjectOptions, doActions, etc.

Se inicializan mediante:

php

$hookmanager->initHooks(array('myarea')); $res = $hookmanager->executeHooks('formObjectOptions', $parameters, $object, $action);

 

8. Gestión de tablas de bases de datos en módulos

La mayoría de los módulos requieren su propia estructura de datos. Dolibarr te permite definir y gestionar la tuya. tablas de bases de datos personalizadas de una manera limpia y mantenible.

8.1 Scripts de instalación y actualización de SQL

Usted define su esquema utilizando archivos SQL ubicados en /sql/.

Ejemplo: /sql/mymodule.sql

sql

CREATE TABLE llx_mymodule_certification ( rowid INT AUTO_INCREMENT PRIMARY KEY, ref VARCHAR(50), label VARCHAR(255), status TINYINT DEFAULT 0, fk_user INT, date_creation DATETIME NOT NULL, tms TIMESTAMP ) ENGINE=InnoDB;

Dolibarr utiliza el descriptor del módulo para ejecutar estos scripts durante la instalación.

8.2 Mapeo de tablas orientado a objetos

Los objetos personalizados se definen como clases PHP en /class/, que normalmente se extiende CommonObject.

Ejemplo: /class/certification.class.php

php

class Certification extends CommonObject { public $table_element = 'mymodule_certification'; public $element = 'certification'; public $fields = array( 'ref' => array('type' => 'string', 'required' => 1), 'label' => array('type' => 'string'), 'status' => array('type' => 'integer'), ); }

Esta estructura permite a Dolibarr generar automáticamente formularios, listas y vistas detalladas con una codificación mínima.


9. Creación de interfaces: páginas, formularios, plantillas

Los módulos a menudo incluyen páginas personalizadas—ya sean páginas de administración o interfaces comerciales.

9.1 Archivos de página

Las páginas personalizadas se colocan en /page/ y seguir esta estructura:

php

require '../../main.inc.php'; require_once DOL_DOCUMENT_ROOT.'/core/lib/admin.lib.php'; require_once '../class/certification.class.php'; llxHeader('', 'My Certifications'); print load_fiche_titre('Certifications Overview'); // Display UI print '<a class="butAction" href="create.php">New Certification</a>'; llxFooter();

9.2 Procesamiento de formularios

Manejar la entrada del usuario usando GETPOST() y checkToken():

php

if ($_POST['action'] == 'add' && checkToken()) { $ref = GETPOST('ref', 'alphanohtml'); $label = GETPOST('label', 'alpha'); $cert = new Certification($db); $cert->ref = $ref; $cert->label = $label; $cert->create($user); }

9.3 Plantillas (TPL)

Las plantillas se almacenan en /tpl/ y usado con include DOL_DOCUMENT_ROOT.'/custom/mymodule/tpl/mypage.tpl.php';.

Esto separa la lógica del diseño y admite la estructura HTML, las clases y las traducciones de Dolibarr.


10. Integración con funciones principales (menús, permisos, archivos PDF)

Los módulos pueden integrarse profundamente en el ecosistema de Dolibarr.

10.1 Agregar menús

Definido en el descriptor del módulo usando $this->menu[] matrices. Cada menú puede ser de nivel superior, menú izquierdo o submenú.

php

$this->menu[] = array( 'fk_menu'=>'', 'type'=>'top', 'titre'=>'My Module', 'mainmenu'=>'mymodule', 'leftmenu'=>'', 'url'=>'/mymodule/page/index.php', 'langs'=>'mymodule@mymodule', 'position'=>100, 'enabled'=>'1', 'perms'=>'1' );

10.2 permisos

Definir en el descriptor del módulo:

php

$this->rights[] = array( 'id'=>104001, 'desc'=>'Read certifications', 'default'=>1, 'perm'=>'read' );

Luego el acceso se valida con:

php

if ($user->rights->mymodule->read) { ... }

10.3 Módulos PDF y numeración

Los generadores de PDF y los formatos de numeración se pueden ampliar colocando clases personalizadas en /core/modules/.

  • Documentos PDF: Extender ModelePDFXXX

  • Módulos de numeración: Ampliar ModelNumXXX

Declárelos en el descriptor para que aparezcan en el panel de configuración.


11. Mejores prácticas para la personalización sin modificar el núcleo

Para mantener Dolibarr mantenible:

  • ✅ Uso manos en lugar de modificar plantillas

  • ✅ Uso dispara en lugar de editar clases de objetos

  • ✅ Coloca tu módulo en /custom/ para evitar sobrescribir en las actualizaciones

  • ✅Añadir comprobación de versiones en tu descriptor

  • ✅ Uso los archivos de idioma para todas las cadenas de interfaz

  • ✅ Validar todas las entradas y escapar todas las salidas

  • ✅ Mantener la lógica empresarial class/no, page/

Estos hábitos garantizan la compatibilidad de actualizaciones y la estabilidad a largo plazo.


12. Errores comunes y cómo evitarlos

❌ Edición de archivos principales

Solución:Utilice anulaciones, ganchos y extensiones.

❌ Uso de SQL directo en lugar de clases de objetos

Solución: Utilice fetch(), create(), update() métodos en sus clases de objetos.

❌ No administrar permisos

Solución: comprobar siempre $user->rights->mymodule->action.

❌ Omitir la validación de entrada

Solución: Siempre usa GETPOST() y escapar de las entradas SQL.

❌ Rutas de codificación rígida

Solución: Utilice DOL_URL_ROOT, dol_buildpath() y constantes.


13. Escenarios de personalización avanzados

13.1 Soporte multiempresa

Si está utilizando el módulo MultiCompany, asegúrese de que su módulo:

  • Usos entity campo en todas las tablas personalizadas

  • Saludos $conf->entity al consultar datos

13.2 Tareas programadas con trabajos cron

Agregue trabajos cron para realizar tareas en segundo plano:

php

$this->cronjobs[] = array( 'label'=>'Sync Certifications', 'jobtype'=>'method', 'class'=>'CertificationSync', 'method'=>'run', 'parameters'=>'', 'comment'=>'Runs nightly' );

13.3 Puntos finales REST personalizados

Cree API personalizadas colocando scripts en /custom/mymodule/script/api_*.php y registrarlos en el descriptor de su módulo.


14. Mantener la compatibilidad entre versiones de Dolibarr

  • Pruebe su módulo con cada versión de Dolibarr

  • Usar dol_version_compare() Para manejar las diferencias de versión

  • Evite utilizar funciones obsoletas o variables globales

  • Mantenga un registro de cambios (changelog.txt) y mantener el control de versiones semántico


15. Conclusión

Comprender la arquitectura de los módulos de Dolibarr es esencial para crear personalizaciones potentes, confiables y con actualizaciones segurasYa sea que esté desarrollando herramientas internas o complementos comerciales, dominar los siguientes elementos le ayudará:

  • Estructura del módulo y archivos descriptores

  • Ganchos, activadores y permisos

  • Clases de objetos personalizados y esquema de base de datos

  • Paneles de administración e interfaces de usuario

  • Integración con generación de PDF, trabajos cron y API

Dolibarr fue diseñado para ser ampliable. Cuanto mejor comprenda su arquitectura, mayor será el valor que podrá ofrecer con sus módulos personalizados, sin necesidad de modificar el código base.


16. Recursos y referencias para desarrolladores