README

A lightweight, convention-driven modular architecture package for Laravel. Replaces the standard app/ directory with a modules/ directory where each subdirectory is a self-contained module following standard Laravel conventions.

Modules are auto-discovered at boot time and cached for performance. All standard Laravel conventions work inside each module — there is no new API to learn.

How It Works

Each subdirectory under modules/ is a self-contained module with its own models, controllers, routes, commands, listeners, events, observers, policies, and more:

modules/
├── Foundation/              # Core framework module
│   ├── Console/             # Commands and schedule
│   └── Providers/           # Service providers
└── Billing/                 # Example domain module
    ├── Events/
    ├── Http/
    │   ├── Controllers/
    │   ├── Requests/
    │   ├── Resources/
    │   └── routes.php
    ├── Listeners/
    ├── Models/
    ├── Observers/
    └── Policies/

What Gets Discovered

Everything else — controllers, requests, resources, events, observers, policies, models, jobs, mail, notifications — works via PSR-4 autoloading. No registration required.

Artisan Commands

module:make Billing creates:

modules/Billing/
├── Console/Commands/
├── Http/
│   ├── Controllers/
│   ├── Requests/
│   └── routes.php
├── Listeners/
└── Models/

Module Caching

Module paths are cached to bootstrap/cache/modules.php and integrated into Laravel's optimize / optimize:clear lifecycle:

php artisan optimize        # Includes module:cache
php artisan optimize:clear  # Includes module:clear

Installation

composer require sinemacula/laravel-modules

1. Edit bootstrap/app.php

Replace the default Laravel application with the modular variant:

<?php

use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;
use SineMacula\Laravel\Modules\Application;
use SineMacula\Laravel\Modules\Configuration\Modules;

Modules::setBasePath(dirname(__DIR__));

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        api      : Modules::routePaths(),
        health   : '/health',
        apiPrefix: '',
    )
    ->withMiddleware(function (Middleware $middleware): void {})
    ->withExceptions(function (Exceptions $exceptions): void {})
    ->create();

2. Update your autoload mapping

In your application's composer.json, point the PSR-4 autoload at the modules/ directory:

{
    "autoload": {
        "psr-4": {
            "App\\": "modules/"
        }
    }
}

Then run composer dump-autoload.

3. Create the modules/ directory

Create a modules/ directory at your project root and add your first module:

mkdir -p modules/Foundation/Providers

4. Wire up routing

Each module defines its own routes in Http/routes.php. These are automatically discovered and passed to withRouting() as shown in the bootstrap/app.php example above.

Requirements

• PHP ^8.3
• Laravel ^13.0

Testing

composer test
composer test-coverage
composer check

Contributing

Contributions are welcome via GitHub pull requests.

Security

If you discover a security issue, please contact Sine Macula directly rather than opening a public issue.

License

Licensed under the Apache License, Version 2.0.