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.1.0 2026-06-27 02:52 UTC

Requires

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

Requires (Dev)

• brianium/paratest: ^7.20
• doctrine/coding-standard: ^14.0
• friendsofphp/php-cs-fixer: ^3.94
• infection/infection: ^0.33.3
• larastan/larastan: ^3.9
• mockery/mockery: ^1.6
• orchestra/testbench: ^10.0 || ^11.0
• phpbench/phpbench: ^1.7
• 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-laravel: ^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
Console commands	Console/Commands/	Auto-registered via withCommands()
Scheduled tasks	Console/schedule.php	Auto-registered via withCommands()
Event listeners	Listeners/	Auto-registered via withEvents()
Views	Resources/views/	Auto-registered in ModuleServiceProvider
Translations	Resources/lang/	Auto-registered in ModuleServiceProvider
Routes	Http/routes.php	Discovered; you wire them in bootstrap/app.php

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

Service providers work exactly as they do in a standard Laravel app: register them in bootstrap/providers.php. The package does not auto-discover module providers, so you keep full control over their registration order.

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. Modules::routePaths() discovers them for you; you wire the result into withRouting() in bootstrap/app.php (as shown above). Routing stays explicit, exactly like standard Laravel - the package just saves you from listing each module's route file by hand.

Requirements

• PHP ^8.3
• Laravel ^12.0 || ^13.0

Testing

composer test                # PHPUnit suite in parallel via Paratest
composer test:coverage       # suite with Clover coverage output
composer test:mutation       # Infection mutation gate (min MSI 90)
composer test:mutation:full  # full mutation suite without thresholds
composer check               # static analysis and lint via qlty
composer format              # format via qlty
composer smells              # duplication / complexity smells via qlty
composer bench               # PHPBench suite for the hot paths
composer bench:ci            # PHPBench with CI artifact dump
composer bench:smoke         # single-rev pass to verify every subject runs

Changelog

See CHANGELOG.md for a list of notable changes.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for guidelines on branching, commits, code quality, and pull requests.

Security

If you discover a security vulnerability, please report it responsibly. See SECURITY.md for the disclosure policy and contact details.

License

Licensed under the Apache License, Version 2.0.