Pular para o conteúdo principal

Módulos

Super Admin → Módulos exibe o status de quaisquer módulos personalizados registrados na sua instalação do LeadHub.

O LeadHub não vem com módulos de funcionalidades integrados — o sistema de módulos é um ponto de extensão para desenvolvedores que permite adicionar novas funcionalidades à plataforma sem modificar o código principal.

O que é o Sistema de Módulos?​

O LeadHub utiliza o nWidart/laravel-modules para implementar uma arquitetura HMVC (Hierarchical Model-View-Controller).

O HMVC organiza o código em módulos independentes, cada um com suas próprias rotas, controllers, models, views, migrations e service provider — essencialmente uma mini aplicação Laravel carregada dentro do aplicativo principal. Isso significa que:

  • Você pode adicionar funcionalidades completamente novas (novas seções de UI, novos endpoints de API, novos jobs em segundo plano) sem editar o núcleo.
  • Os módulos podem ser habilitados ou desabilitados em tempo de execução pelo painel Super Admin, ou via modules_statuses.json.
  • Cada módulo é versionado de forma independente e pode declarar dependências de outros módulos.

Instalação (já incluída no LeadHub)​

O pacote já está instalado e configurado no LeadHub. Para verificar:

composer show nwidart/laravel-modules

A configuração do módulo está em config/modules.php e os módulos são armazenados em Modules/ na raiz do projeto.

Criando Seu Primeiro Módulo​

# Criar um novo módulo
php artisan module:make MyFeature

# Criar múltiplos módulos de uma vez
php artisan module:make ModuleA ModuleB ModuleC

# Criar sem arquivos padrão de boilerplate (mínimo necessário)
php artisan module:make MyFeature --plain

Após executar module:make, seu módulo é criado em Modules/MyFeature/ e registrado automaticamente.

Estrutura Padrão do Módulo​

Modules/
  MyFeature/
    app/
      Http/
        Controllers/      # Controllers de rotas
        Middleware/        # Middleware com escopo do módulo
        Requests/          # Classes de form request
      Models/              # Models Eloquent
      Providers/
        MyFeatureServiceProvider.php   # Service provider principal (auto-carregado)
        RouteServiceProvider.php       # Carrega routes/web.php + routes/api.php
    config/
      config.php           # Configuração no nível do módulo
    database/
      migrations/          # Migrations do módulo (isoladas do núcleo)
      seeders/
      factories/
    resources/
      views/               # Templates Blade
      lang/                # Strings de tradução
      assets/              # JS/CSS (compilados via Vite)
    routes/
      web.php              # Rotas web (carregadas sob o grupo de middleware 'web')
      api.php              # Rotas de API (carregadas sob o grupo de middleware 'api')
    tests/                 # Testes de funcionalidade e unitários
    module.json            # Metadados e declaração de dependências do módulo
    composer.json          # Autoloading PSR-4 para o namespace deste módulo

Arquivos Principais Explicados​

module.json​

Define a identidade e a ordem de carregamento do módulo:

{
    "name": "MyFeature",
    "alias": "myfeature",
    "description": "Adds custom feature X to LeadHub",
    "keywords": [],
    "priority": 0,
    "providers": [
        "Modules\\MyFeature\\Providers\\MyFeatureServiceProvider"
    ],
    "requires": []
}
  • priority — controla a ordem de carregamento; número menor carrega primeiro. Use quando seu módulo depende de outro.
  • requires — lista de aliases de módulos dos quais este módulo depende. O LeadHub irá verificar a dependência antes de carregar.

MyFeatureServiceProvider.php​

O ponto de entrada do seu módulo. Registre rotas, middleware, views, traduções e bindings aqui. O provider gerado pelo scaffold já chama RouteServiceProvider e registra as views e traduções do módulo automaticamente.

config/config.php​

Configuração no nível do módulo. Acesse com:

config('myfeature.some_key');

Publique e sobrescreva por ambiente usando a publicação padrão de configuração do Laravel.

Geradores Artisan Comuns​

# Controllers, Models, Migrations
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

Executando Migrations e Seeds​

As migrations dos módulos ficam separadas do núcleo. Execute-as de forma independente:

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

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

# Rollback
php artisan module:migrate-rollback MyFeature

# Seed
php artisan module:seed MyFeature

Habilitando e Desabilitando Módulos​

Pela linha de comando:

php artisan module:enable MyFeature
php artisan module:disable MyFeature
php artisan module:list          # exibe todos os módulos e seus status

Em Super Admin → Módulos: use o botão de alternância ao lado de cada módulo registrado.

O status dos módulos é persistido em modules_statuses.json na raiz do projeto — faça commit deste arquivo no controle de versão.

Considerações Multi-Tenant​

O LeadHub é multi-tenant. Ao criar módulos, leve em consideração:

  • Migrations com escopo de tenant: execute module:migrate dentro de um contexto de tenant se sua migration criar tabelas no nível do tenant.
  • Isolamento do Service Provider: registre middleware, policies e event listeners dentro do service provider do módulo para evitar poluir o escopo global.
  • Controle de funcionalidades: combine o toggle de habilitar/desabilitar módulo com o sistema de Planos do LeadHub — desabilite um módulo globalmente ou restrinja-o a determinados níveis de plano.

Relacionados​