Laravel Modular Development

You are helping with a Laravel application that uses internachi/modular for modular architecture. Modules live in app-modules/ and follow Laravel package conventions.

Module Structure

The structure of app-modules mimics a standard Laravel application, where what typically would be found in app is found in src:

app-modules/
  {module-name}/
    composer.json # PSR-4 autoload, Laravel provider discovery
    src/
      Providers/
      Models/
      Http/
    tests/
      Feature/
      Unit/
    routes/
      {module-name}-routes.php
    resources/
    database/
      migrations/
      factories/
      seeders/

Creating a New Module

When asked to create a new module:

1. Check if internachi/modular is installed:

   composer show internachi/modular
   

   If not installed, install it first:

   composer require internachi/modular
   

2. Check the modular namespace:

   • Check for config/app-modules.php
   • If present, get the modules_vendor value from that file
   • If not, assume the vendor name is “modules”

3. Create the module:

   php artisan make:module {module-name} --no-interaction
   

4. Register with Composer:

   composer update {module-vendor}/{module-name}
   

5. Sync modules

   php artisan modules:sync
   

Adding Components to a Module

Use the --module flag with Laravel’s make commands:

Module Conventions

Namespacing

• Default namespace: {ModuleVendor}\{ModuleName}\
• Example: Modules\Billing\Models\Invoice

composer.json Format

{
    "name": "{module-vendor}/{module-name}",
    "require": {},
    "autoload": {
        "psr-4": {
            "{ModuleVendor}\\{ModuleName}\\": "src/"
        }
    },
    "extra": {
        "laravel": {
            "providers": [
                "{ModuleVendor}\\{ModuleName}\\Providers\\{ModuleName}ServiceProvider"
            ]
        }
    }
}

Routes

• By convention, module routes are in routes/{module-name}-routes.php
• By convention, module route names are prefixed with the module name (eg. billing::dashboards.index)
• If necessary, break into separate files as needed (eg. routes/{module-name}-api.php)
• Routes are auto-discovered—no need to register them

Migrations

• Place in database/migrations/
• Auto-discovered by Laravel’s migrator
• Run with php artisan migrate

Factories

• Place in database/factories/
• Auto-loaded for factory() calls
• Namespace: {ModuleVendor}\{ModuleName}\Database\Factories

Tests

• Place in tests/Feature/ and tests/Unit/
• Run module tests: php artisan test app-modules/{module-name}/tests
• All module tests can be run using the Modules testsuite configuration that is auto-generated by the modules:sync command

Cross-Module Dependencies

• Import models/services from other modules directly
• Example: use Modules\Billing\Models\Invoice;
• Keep dependencies minimal and unidirectional when possible

Available Commands

# List all modules
php artisan modules:list

# Sync phpunit.xml and IDE configs
php artisan modules:sync

# Cache module configs
php artisan modules:cache

# Clear module cache
php artisan modules:clear

# Run module seeders
php artisan db:seed --module={module-name}

Best Practices

1. One domain per module – Group related functionality together
2. Minimal cross-dependencies – Modules should be loosely coupled
3. Follow Laravel conventions – Use standard directory structure within modules (treat src like app)

When Processing Arguments

If $ARGUMENTS contains:

• Just a module name (e.g., “billing”): Create the module or list what can be added
• Module + component (e.g., “billing model Invoice”): Create that specific component
• “list”: Show existing modules with php artisan modules:list