sinemacula/laravel-modules

A lightweight, convention-driven modular architecture package for Laravel - auto-discovers modules as directories with zero manifests, zero boilerplate, and nothing new to learn.

v1.0.1 2026-04-05 02:21 UTC

Requires

• php: ^8.3
• laravel/framework: ^13.0

Requires (Dev)

• brianium/paratest: ^7.20
• doctrine/coding-standard: ^14.0
• friendsofphp/php-cs-fixer: ^3.94
• larastan/larastan: ^3.9
• mockery/mockery: ^1.6
• orchestra/testbench: ^11.0
• phpstan/extension-installer: ^1.4
• phpstan/phpdoc-parser: ^2.3
• phpstan/phpstan: ^2.1
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0
• phpstan/phpstan-strict-rules: ^2.0
• phpunit/phpunit: ^12.5
• sinemacula/coding-standards: ^1.0
• slevomat/coding-standard: ^8.28
• squizlabs/php_codesniffer: ^4.0

Apache-2.0

• Ben Carey

• modules
• laravel
• modular
• architecture
• sine macula

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

Convention	Module Path	How It's Loaded
Routes	Http/routes.php	Passed to withRouting(api: ...)
Console commands	Console/Commands/	Glob-based via withCommands()
Scheduled tasks	Console/schedule.php	Glob-based via withCommands()
Event listeners	Listeners/	Glob-based via withEvents()
Views	Resources/views/	Registered in ModuleServiceProvider
Translations	Resources/lang/	Registered in ModuleServiceProvider
Service providers	Providers/	Loaded via withProviders()

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

Artisan Commands

Command	Description
module:make {name}	Scaffold a new module with the standard directory structure
module:list	List all discovered modules and their paths
module:cache	Cache discovered module paths for faster resolution
module:clear	Clear the cached module paths

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.