Skip to main content

Modules

Super Admin โ†’ Modules shows the status of any custom modules registered on your LeadHub installation.

LeadHub ships no built-in feature modules โ€” the module system is a developer extension point that allows you to add new functionality to the platform without touching the core codebase.

What Is the Module System?โ€‹

LeadHub uses nWidart/laravel-modules to implement an HMVC (Hierarchical Model-View-Controller) architecture.

HMVC organises code into self-contained modules, each with its own routes, controllers, models, views, migrations, and service provider โ€” essentially a mini Laravel application loaded into the main app. This means:

  • You can add entirely new features (new UI sections, new API endpoints, new background jobs) without editing the core.
  • Modules can be enabled or disabled at runtime from the Super Admin panel, or via modules_statuses.json.
  • Each module is independently versioned and can declare dependencies on other modules.

Installation (already included in LeadHub)โ€‹

The package is already installed and configured in LeadHub. To verify:

composer show nwidart/laravel-modules

The module configuration is at config/modules.php and modules are stored under Modules/ in the project root.

Creating Your First Moduleโ€‹

# Scaffold a new module
php artisan module:make MyFeature

# Scaffold multiple modules at once
php artisan module:make ModuleA ModuleB ModuleC

# Scaffold without default boilerplate files (bare minimum)
php artisan module:make MyFeature --plain

After running module:make, your module is created under Modules/MyFeature/ and automatically registered.

Module Boilerplate Structureโ€‹

Modules/
  MyFeature/
    app/
      Http/
        Controllers/      # Route controllers
        Middleware/        # Module-scoped middleware
        Requests/          # Form request classes
      Models/              # Eloquent models
      Providers/
        MyFeatureServiceProvider.php   # Main service provider (auto-loaded)
        RouteServiceProvider.php       # Loads routes/web.php + routes/api.php
    config/
      config.php           # Module-level configuration
    database/
      migrations/          # Module migrations (isolated from core)
      seeders/
      factories/
    resources/
      views/               # Blade templates
      lang/                # Translation strings
      assets/              # JS/CSS (compiled via Vite)
    routes/
      web.php              # Web routes (loaded under 'web' middleware group)
      api.php              # API routes (loaded under 'api' middleware group)
    tests/                 # Feature and unit tests
    module.json            # Module metadata and dependency declaration
    composer.json          # PSR-4 autoloading for this module's namespace

Key Files Explainedโ€‹

module.jsonโ€‹

Defines the module's identity and load order:

{
    "name": "MyFeature",
    "alias": "myfeature",
    "description": "Adds custom feature X to LeadHub",
    "keywords": [],
    "priority": 0,
    "providers": [
        "Modules\\MyFeature\\Providers\\MyFeatureServiceProvider"
    ],
    "requires": []
}
  • priority โ€” controls load order; lower number loads first. Use this when your module depends on another.
  • requires โ€” list of module aliases this module depends on. LeadHub will enforce the dependency before loading.

MyFeatureServiceProvider.phpโ€‹

The entry point for your module. Register routes, middleware, views, translations, and bindings here. The scaffolded provider already calls RouteServiceProvider and registers the module's views and translations automatically.

config/config.phpโ€‹

Module-level configuration. Access it with:

config('myfeature.some_key');

Publish and override per environment using Laravel's standard config publishing.

Common Artisan Generatorsโ€‹

# 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

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

Running Migrations & Seedsโ€‹

Module migrations are kept separate from the core. Run them independently:

# Migrate all modules
php artisan module:migrate

# Migrate a specific module
php artisan module:migrate MyFeature

# Rollback
php artisan module:migrate-rollback MyFeature

# Seed
php artisan module:seed MyFeature

Enabling & Disabling Modulesโ€‹

From the command line:

php artisan module:enable MyFeature
php artisan module:disable MyFeature
php artisan module:list          # shows all modules and their status

From Super Admin โ†’ Modules: use the toggle next to each registered module.

Module status is persisted in modules_statuses.json at the project root โ€” commit this file to version control.

Multi-Tenant Considerationsโ€‹

LeadHub is multi-tenant. When building modules, keep in mind:

  • Tenant-scoped migrations: wrap module:migrate inside a tenant context if your migration creates tenant-level tables.
  • Service Provider isolation: register middleware, policies, and event listeners inside the module's service provider to avoid polluting the global scope.
  • Feature gating: combine the module enable/disable toggle with LeadHub's Plans system โ€” disable a module globally, or restrict it to specific plan tiers.