Creación de un módulo Dolibarr personalizado: tutorial paso a paso
¿Quieres ampliar las funcionalidades de Dolibarr sin modificar el núcleo del software? Sigue este tutorial completo para crear tu propio módulo, desde la activación del Generador de Módulos hasta el guardado del primer objeto de negocio en la base de datos.
Desarrollo · Dolibarr · PHP • Nivel intermedio
Resumen
1. ¿Por qué crear un módulo Dolibarr personalizado?
2. Requisitos previos antes de comenzar
3. Comprender la arquitectura de un módulo
4. Paso 1: Activar el Creador de módulos
5. Paso 2: Generar el esqueleto del módulo
6. Paso 3: Personalizar el descriptor
8. Paso 5: Agregar una entrada al menú
9. Paso 6: Crear un objeto de negocio y su tabla.
10. Paso 7: Gestionar las traducciones
11. Paso 8: Activar y probar el módulo.
12. Profundizando: ganchos, disparadores y API
13. Buenas prácticas de desarrollo
14. Depurar y resolver problemas comunes
Dolibarr debe gran parte de su éxito a su arquitectura modular. En lugar de imponer un bloque monolítico, ofrece docenas de módulos que se pueden activar o desactivar según sea necesario. Y, sobre todo, permite a los desarrolladores crear los suyos propios. Esta es la clave para adaptar el ERP a necesidades empresariales muy específicas sin modificar el código fuente original, lo que garantiza actualizaciones sin interrupciones.
En este tutorial paso a paso, aprenderás a crear un módulo personalizado de Dolibarr desde cero. Usaremos el Generador de Módulos , la herramienta integrada de Dolibarr para la generación de código, que automatiza gran parte del trabajo tedioso. Al finalizar, tendrás un módulo completamente funcional con su propio menú, permisos, un objeto de negocio vinculado a una tabla de base de datos y traducciones.
Esta guía está dirigida a desarrolladores con conocimientos básicos de PHP. No es necesario ser un experto: explicaremos cada concepto paso a paso. Abre tu editor de código favorito, inicia tu entorno de desarrollo Dolibarr y ¡empecemos!
¿Por qué crear un módulo Dolibarr personalizado?
Antes de escribir una sola línea de código, es útil comprender qué permite hacer realmente un módulo. Un módulo de Dolibarr no es un simple script: es una extensión completa, capaz de integrarse profundamente en la aplicación.
En términos concretos, un módulo personalizado puede agregar nuevas tablas de base de datos, crear sus propias pantallas de entrada, insertar entradas de menú, agregar pestañas a los registros existentes (facturas, productos, terceros…), definir nuevos permisos, ejecutar código automáticamente ante eventos mediante disparadores o incluso inyectarse en el código existente a través de ganchos.
La principal ventaja se resume en una frase: extiendes Dolibarr sin modificar el núcleo . Tus desarrollos residen en un directorio aparte y se conservan tras las actualizaciones de versión. Esta es la diferencia fundamental entre un módulo limpio y una modificación chapucera del código fuente, que se perdería con la primera actualización.
Requisitos previos antes de comenzar
Un entorno bien preparado te ahorrará muchas frustraciones. Esto es lo que necesitas.
Conocimientos básicos
Es fundamental tener un buen dominio de PHP, así como conocimientos de SQL para tablas de datos y algo de HTML/CSS para pantallas. Se valorará positivamente el conocimiento de programación orientada a objetos, ya que los objetos de negocio de Dolibarr se basan en clases.
El entorno de desarrollo
Instala una instancia dedicada de Dolibarr para desarrollo, separada de tu entorno de producción. Usa un editor de código fácil de usar como Visual Studio Code o PhpStorm, y asegúrate de que las extensiones comunes de PHP (pdo, gd, intl, etc.) estén instaladas en tu servidor.
Habilitar el modo desarrollador
El Generador de módulos solo aparece en modo desarrollador. Abra su archivo htdocs/conf/conf.php y retire la aplicación del modo de producción agregando o modificando esta línea:
$dolibarr_main_prod = 0;
Recuerda configurar el nivel de funcionalidad en "desarrollador" en los ajustes de pantalla para desbloquear las herramientas avanzadas. Una vez configurados estos ajustes, podrás acceder a las funciones de desarrollo.
Importante: Nunca trabajes directamente en tu Dolibarr de producción. El modo desarrollador muestra información confidencial y activa herramientas que no deberían estar en un sitio web en producción. Reserva estas configuraciones para un entorno de prueba.
Comprender la arquitectura de un módulo
Un módulo de Dolibarr sigue una estructura de archivos bien definida. Comprender esta estructura te ayudará a navegar por el código generado y a saber dónde añadir tus personalizaciones.
El árbol de archivos
Un módulo externo se coloca en el directorio htdocs/custom/ . Así es como se ve la estructura de directorios típica de un módulo llamado mymodule :
htdocs/custom/mymodule/
├── core/
│ └── modules/
│ └── modMyModule.class.php (el descriptor)
├── class/ (objetos de negocio - clases CRUD)
├── sql/ (scripts de creación de tablas)
├── admin/ (la página de configuración)
├── lib/ (funciones de utilidad)
├── langs/ (archivos de traducción)
│ └── fr_FR/
└── mymodule_index.php (la página principal)
El archivo descriptor, el componente clave
El archivo modMonModule.class.php , ubicado en core/modules/ , es el núcleo del módulo. Dolibarr lee este archivo para determinar el nombre del módulo, su función, sus permisos, los menús que añade y las tablas que instala. Extiende la clase DolibarrModules . Sin este archivo, Dolibarr simplemente no reconocerá el módulo.
Paso 1: Activar el Creador de módulos
Desde la versión 9 de Dolibarr, el método recomendado para crear un módulo es usar el Generador de módulos , que viene incluido por defecto. Vaya a Inicio → Configuración → Módulos/Aplicaciones , busque "Generador de módulos" en la lista y actívelo.
Una vez activada, aparece un nuevo icono (generalmente representado por un pequeño insecto o un engranaje) en la esquina superior derecha de la pantalla. Este abre la interfaz del Generador de Módulos, a la que se accede técnicamente mediante la dirección de la herramienta de generación. Es desde esta interfaz donde ocurre toda la magia.
Paso 2: Generar el esqueleto del módulo
En la interfaz del Creador de módulos, haga clic en el botón para crear un nuevo módulo. Aparecerá una ventana donde se le solicitará información básica: el nombre del módulo (por ejemplo, MyModule), su categoría, su descripción y su editor.
Confirma y el Generador de Módulos hará la mayor parte del trabajo: copia los archivos de plantilla ubicados en htdocs/modulebuilder/template , realiza las sustituciones de cadenas necesarias y crea la estructura de directorios completa de tu módulo en htdocs/custom/monmodule/ . En pocos segundos, obtendrás un módulo válido, vacío pero reconocido inmediatamente por Dolibarr.
Consejo: El Generador de Módulos crea un archivo modulebuilder.txt en el directorio raíz del módulo. No lo elimine durante el desarrollo: permite que la herramienta continúe editando el módulo a través de la interfaz gráfica. Solo deberá eliminarlo al momento de la distribución final.
Paso 3: Personalizar el descriptor
Abre el descriptor generado en tu editor. Encontrarás muchas propiedades que ajustar. Estas son las más importantes, tal como aparecen en el constructor de la clase:
public function __construct($db)
{
$this->db = $db;
$this->numero = 500000; // identificador único del módulo
$this->rights_class = 'monmodule'; // prefijo de permisos
$this->family = 'other'; // familia de visualización
$this->name = 'MonModule';
$this->description = 'Gestión personalizada para mi negocio';
$this->version = '1.0';
$this->picto = 'generic'; // icono del módulo
}
El aspecto más importante a tener en cuenta es el número de módulo , que debe ser único para evitar conflictos con otros módulos. El Generador de Módulos suele asignar un identificador aleatorio de un rango reservado para módulos externos. Evite modificarlo arbitrariamente. La propiedad de versión se utiliza para realizar un seguimiento de las actualizaciones, y la descripción se muestra en la lista de módulos.
Paso 4: Definir permisos
Los permisos controlan quién puede hacer qué en tu módulo. Se declaran en la tabla de derechos del descriptor. Cada entrada define un identificador, una etiqueta y el tipo de acción que permite (leer, crear, eliminar, etc.).
$this->rights = array();
$r = 0;
$this->rights[$r][0] = 500001; // ID de permiso único
$this->rights[$r][1] = 'Leer registros';
$this->rights[$r][4] = 'leer';
$r++;
$this->rights[$r][0] = 500002;
$this->rights[$r][1] = 'Crear o modificar';
$this->rights[$r][4] = 'escribir';
Cuando se activa el módulo, estos permisos se guardan automáticamente en la tabla llx_rights_def . A continuación, puede asignarlos a sus usuarios y grupos desde la interfaz de administración habitual. Recuerde comprobar estos permisos en su código para cada acción sensible: es una buena práctica de seguridad básica.
Paso 5: Agregar una entrada al menú
Para que tu módulo sea accesible, necesita al menos un elemento de menú. Este se declara en la tabla de menús del descriptor. Debes especificar el tipo de menú (izquierdo o superior), su título, la URL de destino y el permiso necesario para mostrarlo.
$this->menu[$r++] = array(
'fk_menu' => 'fk_mainmenu=mymodule',
'type' => 'left',
'title' => 'Lista de elementos',
'url' => '/custom/mymodule/mymodule_list.php',
'langs' => 'mymodule@mymodule',
'perms' => '$user->rights->mymodule->read',
'position' => 100,
);
El campo de permisos garantiza que solo los usuarios autorizados vean la entrada del menú. Una vez reactivado el módulo, el menú aparecerá en la barra lateral, listo para enlazar con tus pantallas.
Paso 6: Crear un objeto de negocio y su tabla.
Este es el núcleo de un módulo que manipula datos. El Generador de Módulos permite añadir un "objeto" con tan solo unos clics, desde la pestaña correspondiente en su interfaz. Se define el nombre del objeto y la lista de sus campos (texto, número, fecha, enlace a otro objeto, etc.).
Según esta definición, la herramienta genera varios archivos a la vez: la clase DAO/CRUD en la carpeta class/ (con métodos listos para usar para crear, leer, actualizar y eliminar un registro), el script SQL para crear la tabla en sql/ , así como las páginas de lista y registro. Esto supone un ahorro de tiempo considerable.
El script SQL generado tiene este aspecto, con las columnas correspondientes a sus campos:
CREATE TABLE llx_monmodule_element (
rowid INTEGER AUTO_INCREMENT PRIMARY KEY,
ref VARCHAR(128) NOT NULL,
label VARCHAR(255),
datec DATETIME,
fk_user_creat INTEGER,
status INTEGER DEFAULT 0
) ENGINE=innodb;
Nota importante: todas las tablas de un módulo Dolibarr tienen el prefijo llx_ (o el prefijo definido durante la instalación). Siga esta convención: evita conflictos de nombres y garantiza la coherencia con el resto de la base de datos.
Paso 7: Gestionar las traducciones
Dolibarr es multilingüe, y su módulo también debe serlo. Las etiquetas se almacenan en archivos de idioma ubicados en langs/fr_FR/ . Cada archivo asocia una clave con un texto traducido, en forma de pares clave = valor:
# archivo langs/fr_FR/monmodule.lang
ModuleMonModuleName = Mi módulo
ModuleMonModuleDesc = Gestión personalizada para mi actividad
MonModuleList = Lista de elementos
NewElement = Nuevo elemento
En tu código, nunca insertes el texto directamente: llama a la clave de traducción. Dolibarr se encarga de mostrar el idioma correcto según las preferencias del usuario. Recuerda crear al menos versiones en francés e inglés de los archivos para una distribución más amplia.
Paso 8: Activar y probar el módulo.
Llegó el momento decisivo. Acceda a la lista de módulos de Dolibarr: su módulo ya aparece. Actívelo. En este punto, Dolibarr ejecuta los scripts SQL, crea las tablas, guarda los permisos e instala los menús.
A continuación, ve a la nueva entrada del menú, crea un primer registro, modifícalo y elimínalo. Verifica que los datos aparezcan correctamente en la base de datos. Si algo falla, el modo desarrollador y los registros de Dolibarr serán tus mejores aliados para diagnosticar el problema.
Consejo para la depuración: Si encuentra un error después de modificar el descriptor, desactive y vuelva a activar el módulo para forzar a Dolibarr a releer la configuración y ejecutar nuevamente los scripts de instalación. Muchos problemas se resuelven con este sencillo paso.
Para ir más allá: ganchos, disparadores y API
Una vez adquiridos los conceptos básicos, Dolibarr ofrece potentes mecanismos para integrar el módulo en profundidad.
Los ganchos
Los hooks son puntos de inyección que permiten agregar o reemplazar código en ubicaciones específicas dentro de Dolibarr, sin modificar el núcleo. Se declaran los contextos de interés mediante la propiedad `module_parts` del descriptor:
$this->module_parts = array(
'hooks' => array('invoicecard', 'thirdpartycard')
);
A continuación, se crea una clase de enlace cuyos métodos se ejecutarán automáticamente cuando Dolibarr acceda a estos contextos. Esto resulta ideal para enriquecer las pantallas existentes con información propia.
Desencadenantes
Los disparadores ejecutan código en respuesta a un evento empresarial: la validación de una factura, la creación de un tercero, la eliminación de un producto, etc. De este modo, su módulo puede reaccionar automáticamente, por ejemplo, para sincronizar datos con un sistema externo o enviar una notificación.
La API REST
Si su objeto de negocio necesita ser accesible desde fuera del sistema, el Generador de Módulos puede crear una API REST específica. Esto le permite exponer sus datos a otras aplicaciones, respetando los permisos definidos. Esta es una gran ventaja para integrar Dolibarr en su ecosistema de software.
Buenas prácticas de desarrollo
Seguir algunos principios le ayudará a evitar muchos problemas y facilitará el mantenimiento de su módulo con el tiempo:
• Nunca modifiques el kernel. Todo tu código permanece en el directorio personalizado. Esto garantiza actualizaciones sin problemas.
• Comprueba los permisos en todas partes. Antes de realizar cualquier acción delicada, verifica que el usuario tenga el derecho correspondiente.
• Escapar de los datos. Sanitizar sistemáticamente la entrada del usuario para prevenir inyecciones SQL y vulnerabilidades XSS.
• Controla las versiones de tu código. Usa Git desde el principio para realizar un seguimiento de tus cambios y colaborar sin problemas.
• Documenta y traduce. Las etiquetas claras y los archivos de idioma completos hacen que tu módulo sea utilizable por otros.
• Realice pruebas antes de distribuir. Active y desactive su módulo en una instancia limpia para validar la instalación y desinstalación.
Depuración y resolución de problemas comunes
Aunque sigas cada paso al pie de la letra, tarde o temprano te encontrarás con comportamientos inesperados. Aquí te explicamos cómo mantener el control y diagnosticar eficazmente los problemas más comunes.
Lo primero que debes hacer es habilitar los registros de Dolibarr. En el modo desarrollador, puedes aumentar el nivel de detalle de los registros para ver con precisión qué está haciendo la aplicación. La mayoría de los errores dejan un rastro claro, mucho más útil que una pantalla en blanco. Además, recuerda revisar el registro de errores de PHP, que captura las anomalías no gestionadas.
Un módulo que no aparece en la lista casi siempre indica un problema con el descriptor de archivo: un error de sintaxis de PHP, un nombre de clase que no coincide con el nombre del archivo o una ubicación incorrecta en la estructura de directorios. Verifique que el archivo tenga el nombre esperado y que se encuentre en el subdirectorio correcto.
Si las tablas no se crean al activar el módulo, revise sus scripts SQL: la falta de un punto y coma o una sintaxis incompatible con su base de datos pueden bloquear la instalación. Desactive y vuelva a activar el módulo para reiniciar el proceso una vez corregido el error.
Buen hábito: trabaja en pequeñas iteraciones. Cambia solo una cosa a la vez y luego pruébala. Cuando algo falla, sabrás inmediatamente qué cambio es el responsable; mientras que con muchos cambios el diagnóstico resulta mucho más difícil.
Preguntas frecuentes
¿Es obligatorio utilizar el Generador de Módulos?
No, puedes escribir todo manualmente copiando la plantilla del descriptor. Sin embargo, desde Dolibarr 9, el Generador de Módulos es el método recomendado: genera código limpio y conforme a las especificaciones, te ahorra tiempo valioso y reduce los errores. Posteriormente, puedes editar manualmente los archivos generados.
¿Dónde debo colocar mi módulo: en el directorio personalizado o en el directorio raíz?
Para un módulo externo, colóquelo siempre en htdocs/custom/ . El directorio raíz está reservado para los módulos destinados a convertirse en módulos oficiales del núcleo de Dolibarr. El directorio custom garantiza la separación del núcleo.
¿Mi módulo sobrevivirá a las actualizaciones de Dolibarr?
Sí, siempre y cuando respetes la regla de oro: nunca modifiques el código del kernel. Dado que tu módulo reside en su propio directorio y utiliza los mecanismos oficiales (ganchos, disparadores, descriptor), seguirá siendo compatible con las actualizaciones de versión, siempre que mantengas actualizada la API.
¿Puedo distribuir o vender mi módulo?
Por supuesto. En el mercado oficial hay muchos módulos de terceros, tanto gratuitos como de pago. Solo asegúrate de cumplir con la licencia de Dolibarr y de proporcionar documentación clara y las traducciones necesarias.
Conclusión
Crear un módulo personalizado para Dolibarr es muy sencillo. Gracias al Generador de Módulos , la estructura básica se genera en tan solo unos clics, lo que le permite personalizar el descriptor, declarar sus permisos y menús, y definir sus objetos de negocio. Siguiendo los pasos de este tutorial, ahora cuenta con una base sólida para crear extensiones personalizadas.
La principal ventaja de este enfoque reside en el respeto que se le tiene al software: todo tu trabajo permanece aislado en el directorio personalizado, protegido de las actualizaciones. Puedes adaptar Dolibarr a tus necesidades más exigentes sin comprometer jamás su viabilidad a largo plazo.
La mejor manera de progresar ahora es practicando. Inicia tu entorno de desarrollo, genera tu primer módulo, añádele un objeto y un menú, y explora gradualmente los hooks, los disparadores y la API. Cada módulo que crees te familiarizará más con la arquitectura de Dolibarr y te abrirá las puertas a un sinfín de posibilidades.