Índice
-
Introducción
-
¿Qué es un módulo Dolibarr?
-
La arquitectura central de Dolibarr
-
Cómo encajan los módulos en la arquitectura de Dolibarr
-
Directorio y estructura de archivos de un módulo típico
-
El papel del descriptor del módulo
-
Ganchos, activadores y eventos: ampliación de la funcionalidad principal
-
Administración de tablas de bases de datos en módulos
-
Creación de interfaces: páginas, formularios, plantillas
-
Integración con funciones principales (menús, permisos, archivos PDF)
-
Mejores prácticas para la personalización sin modificar el núcleo
-
Errores comunes y cómo evitarlos
-
Escenarios de personalización avanzados
-
Mantener la compatibilidad entre las versiones de Dolibarr
-
Conclusión
-
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
$confy$userobjetos -
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/:
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:
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:
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:
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
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
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:
9.2 Procesamiento de formularios
Manejar la entrada del usuario usando GETPOST() y checkToken():
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ú.
10.2 permisos
Definir en el descriptor del módulo:
Luego el acceso se valida con:
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
entitycampo en todas las tablas personalizadas -
Saludos
$conf->entityal consultar datos
13.2 Tareas programadas con trabajos cron
Agregue trabajos cron para realizar tareas en segundo plano:
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.
