Saltar al contenido principal

Módulos

Super Admin → Modules muestra el estado de cualquier módulo personalizado registrado en su instalación de LeadHub.

LeadHub no incluye módulos de funcionalidades integrados — el sistema de módulos es un punto de extensión para desarrolladores que permite añadir nuevas funcionalidades a la plataforma sin modificar el núcleo del código.

¿Qué es el sistema de módulos?​

LeadHub utiliza nWidart/laravel-modules para implementar una arquitectura HMVC (Hierarchical Model-View-Controller).

HMVC organiza el código en módulos autocontenidos, cada uno con sus propias rutas, controladores, modelos, vistas, migraciones y proveedor de servicios — esencialmente una mini aplicación Laravel cargada dentro de la aplicación principal. Esto significa:

  • Puede añadir funcionalidades completamente nuevas (nuevas secciones de interfaz, nuevos endpoints de API, nuevos trabajos en segundo plano) sin editar el núcleo.
  • Los módulos pueden habilitarse o deshabilitarse en tiempo de ejecución desde el panel de Super Admin, o mediante modules_statuses.json.
  • Cada módulo tiene versión independiente y puede declarar dependencias de otros módulos.

Instalación (ya incluida en LeadHub)​

El paquete ya está instalado y configurado en LeadHub. Para verificarlo:

composer show nwidart/laravel-modules

La configuración del módulo se encuentra en config/modules.php y los módulos se almacenan en Modules/ en la raíz del proyecto.

Creación de su primer módulo​

# Generar un nuevo módulo
php artisan module:make MyFeature

# Generar múltiples módulos a la vez
php artisan module:make ModuleA ModuleB ModuleC

# Generar sin archivos de estructura predeterminados (mínimo necesario)
php artisan module:make MyFeature --plain

Después de ejecutar module:make, su módulo se crea en Modules/MyFeature/ y se registra automáticamente.

Estructura del módulo generado​

Modules/
  MyFeature/
    app/
      Http/
        Controllers/      # Controladores de rutas
        Middleware/        # Middleware con alcance de módulo
        Requests/          # Clases de solicitud de formulario
      Models/              # Modelos Eloquent
      Providers/
        MyFeatureServiceProvider.php   # Proveedor de servicios principal (cargado automáticamente)
        RouteServiceProvider.php       # Carga routes/web.php + routes/api.php
    config/
      config.php           # Configuración a nivel de módulo
    database/
      migrations/          # Migraciones del módulo (aisladas del núcleo)
      seeders/
      factories/
    resources/
      views/               # Plantillas Blade
      lang/                # Cadenas de traducción
      assets/              # JS/CSS (compilado mediante Vite)
    routes/
      web.php              # Rutas web (cargadas bajo el grupo de middleware 'web')
      api.php              # Rutas API (cargadas bajo el grupo de middleware 'api')
    tests/                 # Pruebas de funcionalidad y unitarias
    module.json            # Metadatos del módulo y declaración de dependencias
    composer.json          # Autocarga PSR-4 para el espacio de nombres de este módulo

Descripción de los archivos clave​

module.json​

Define la identidad del módulo y el orden de carga:

{
    "name": "MyFeature",
    "alias": "myfeature",
    "description": "Adds custom feature X to LeadHub",
    "keywords": [],
    "priority": 0,
    "providers": [
        "Modules\\MyFeature\\Providers\\MyFeatureServiceProvider"
    ],
    "requires": []
}
  • priority — controla el orden de carga; un número menor se carga primero. Úselo cuando su módulo dependa de otro.
  • requires — lista de alias de módulos de los que depende este módulo. LeadHub verificará la dependencia antes de cargar.

MyFeatureServiceProvider.php​

El punto de entrada de su módulo. Registre rutas, middleware, vistas, traducciones y enlaces aquí. El proveedor generado automáticamente ya invoca RouteServiceProvider y registra las vistas y traducciones del módulo de forma automática.

config/config.php​

Configuración a nivel de módulo. Acceda a ella con:

config('myfeature.some_key');

Publique y anule por entorno utilizando la publicación de configuración estándar de Laravel.

Generadores de Artisan más comunes​

# Controladores, Modelos, Migraciones
php artisan module:make-controller MyController MyFeature
php artisan module:make-model MyModel MyFeature
php artisan module:make-migration create_my_table MyFeature

# Requests, Middleware, Policies
php artisan module:make-request StoreMyRequest MyFeature
php artisan module:make-middleware CheckSomething MyFeature
php artisan module:make-policy MyPolicy MyFeature

# Jobs, Events, Listeners, Mail
php artisan module:make-job ProcessSomething MyFeature
php artisan module:make-event SomethingHappened MyFeature
php artisan module:make-listener HandleSomething MyFeature
php artisan module:make-mail WelcomeMail MyFeature

# Comandos Artisan
php artisan module:make-command MyCommand MyFeature

Ejecución de migraciones y semillas​

Las migraciones de los módulos se mantienen separadas del núcleo. Ejecútelas de forma independiente:

# Migrar todos los módulos
php artisan module:migrate

# Migrar un módulo específico
php artisan module:migrate MyFeature

# Revertir
php artisan module:migrate-rollback MyFeature

# Semilla
php artisan module:seed MyFeature

Habilitación y deshabilitación de módulos​

Desde la línea de comandos:

php artisan module:enable MyFeature
php artisan module:disable MyFeature
php artisan module:list          # muestra todos los módulos y su estado

Desde Super Admin → Modules: use el interruptor junto a cada módulo registrado.

El estado del módulo se persiste en modules_statuses.json en la raíz del proyecto — confirme este archivo en el control de versiones.

Consideraciones multi-inquilino​

LeadHub es multi-inquilino. Al desarrollar módulos, tenga en cuenta:

  • Migraciones con alcance de inquilino: envuelva module:migrate dentro de un contexto de inquilino si su migración crea tablas a nivel de inquilino.
  • Aislamiento del proveedor de servicios: registre middleware, políticas y escuchas de eventos dentro del proveedor de servicios del módulo para evitar contaminar el ámbito global.
  • Control de funcionalidades: combine el interruptor de habilitación/deshabilitación del módulo con el sistema de Planes de LeadHub — deshabilite un módulo globalmente, o restrínjalo a niveles de plan específicos.

Relacionado​