Laravel Modular Lite

A lightweight, zero-ceremony Modular Architecture package for Laravel applications. Designed for developers who want the organizational benefits of feature-based modules without the cognitive overhead of complex enterprise abstractions.

[!TIP] Building an Enterprise Application?
If you are building large-scale, complex enterprise platforms (ERP, CRM, Banking, Multi-domain systems) requiring strict Domain-Driven Design (DDD) 4-layer boundaries, CQRS (Actions/Queries/Data), and architectural testing, check out our flagship enterprise package:
👉 hatchyu/laravel-modular (composer require hatchyu/laravel-modular)

🎯 Design Philosophy: Stay Close to Laravel

If you are building an MVP, SaaS, eCommerce store, or internal tool, you don't always need 7 architectural layers (Domain Model, Contract, Repository, DTO, Action, Request, Resource, Controller) for a simple database record.

Laravel Modular Lite gives you:

• 🚀 Familiar Laravel Structure: Put your Models, Controllers, Requests, Resources, and Services in clean module folders.
• ⚡ Compiled Module Discovery: Eliminate runtime filesystem scanning in production with compiled manifest caching (php artisan module:cache).
• 🛠️ Frictionless CRUD: Generate an entire vertical CRUD slice (Model, Migration, Factory, Requests, Resource, Controller, Routes, and Tests) in a single command.
• 🩺 Self-Healing Diagnostics: Built-in php artisan module:doctor to verify PSR-4 mappings, check route syntax, and repair missing directories automatically with --fix.
• 🔌 Module Enable / Disable: Toggle modules on or off dynamically without deleting code (php artisan module:enable / module:disable).
• 🕸️ Dependency Graph & Topological Booting: Declare dependencies in module.json. Prerequisite modules boot before dependent ones automatically.
• 🛡️ Fail-Safe Dependency Guardrails: Runtime checks and CLI guardrails prevent broken states when dependencies are disabled or missing.
• 🔄 Safe Module Renaming: Rename modules and refactor namespaces, routes, views, providers, and other modules' dependency declarations.
• 🔒 Security Hardened: Path traversal immunity, migration table name sanitization, and strict regex module validation.

📂 Module Structure

When you create a module with php artisan module:make Shop, it generates a clean, conventional directory tree:

modules/
└── Shop/
    ├── Controllers/
    │   └── Api/
    │       └── ShopController.php
    ├── Models/
    │   └── Product.php
    ├── Requests/
    │   ├── StoreProductRequest.php
    │   └── UpdateProductRequest.php
    ├── Resources/
    │   └── ProductResource.php
    ├── Services/
    │   └── CheckoutService.php
    ├── Database/
    │   ├── Migrations/
    │   ├── Factories/
    │   └── Seeders/
    ├── Routes/
    │   ├── web.php
    │   └── api.php
    ├── Views/
    │   └── index.blade.php
    ├── Providers/
    │   └── ShopServiceProvider.php
    └── Tests/
        └── Feature/

📦 Installation

Install the package via Composer:

composer require hatchyu/laravel-modular-lite

Add the modules PSR-4 namespace to your root composer.json:

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

Then regenerate Composer's autoloader:

composer dump-autoload

(Optional) Publish the configuration file:

php artisan vendor:publish --tag="modular-lite-config"

🔌 Module Lifecycle & Dependencies

Every module includes a lightweight module.json manifest located at modules/{ModuleName}/module.json (auto-generated by php artisan module:make):

{
    "name": "Shop",
    "description": "Shop module",
    "version": "1.0.0",
    "enabled": true,
    "dependencies": [
        "Inventory",
        "Customers"
    ],
    "priority": 0
}

Enabling & Disabling Modules

Easily disable modules during maintenance or feature rollout without altering codebase structure:

# Enable a module
php artisan module:enable Shop

# Disable a module
php artisan module:disable Shop

When disabled, all of the module's routes, providers, migrations, views, config, and commands are automatically excluded from the application lifecycle.

Topological Boot Ordering

When modules declare dependencies, Laravel Modular Lite automatically sorts them topologically using Kahn's algorithm so that prerequisite modules (e.g., Inventory) are registered and booted before dependent modules (e.g., Shop).

How Disabled or Missing Dependencies Are Handled

If a module depends on another module that is disabled or missing:

1. At Application Boot Time: If Shop is active but depends on disabled Inventory, the system raises an explicit, actionable exception:

   ModuleDependencyException: Module [Shop] depends on module [Inventory], but [Inventory] is currently disabled. Enable it using: php artisan module:enable Inventory
   

2. At CLI Level (Dependency Protection):
   • Protection Against Breaking Dependents: You cannot disable a prerequisite module if active modules depend on it:

     $ php artisan module:disable Inventory
     Active module(s) [Shop] depend on [Inventory].
     ERROR: Cannot disable module [Inventory] because active module [Shop] depends on it. Use --force to disable anyway.
     

   • Validation on Enable: Enabling a module validates that all required dependencies are present and enabled:

     $ php artisan module:enable Shop
     WARN: Module [Shop] depends on disabled module(s): Inventory.
     ERROR: Please enable prerequisite modules first or use --force to override.
     

3. Health Diagnostics (php artisan module:doctor): Displays module status and flags disabled or missing dependencies directly in the health table.

🚀 Usage & Artisan Commands

1. Module Management

# Scaffold a new module (creates directory tree & module.json)
php artisan module:make Shop

# Enable or disable a module
php artisan module:enable Shop
php artisan module:disable Shop

# List all discovered modules, status (Enabled/Disabled), and dependencies
php artisan module:list

# Safely rename a module and propagate new name across other modules' dependencies
php artisan module:rename Shop Marketplace

# Diagnose module health and auto-repair missing directories
php artisan module:doctor --fix

2. Instant CRUD Generation

Generate an entire vertical slice in one command:

php artisan module:make-crud Shop Product
# or shortcut:
php artisan module:crud Shop Product

This generates:

1. Models/Product.php
2. Database/Migrations/xxxx_create_products_table.php
3. Database/Factories/ProductFactory.php
4. Requests/StoreProductRequest.php & UpdateProductRequest.php
5. Resources/ProductResource.php
6. Controllers/Api/ProductController.php (pure Eloquent queries)
7. Tests/Feature/ProductControllerTest.php
8. Appends Route::apiResource('products', ProductController::class); to Routes/api.php

3. Granular Generators

# Model (supports -m, -c, -r, -f, -s, -a options)
php artisan module:make-model Shop Product -a

# Controller (supports --api and --resource)
php artisan module:make-controller Shop ProductController --api

# Requests & Resources
php artisan module:make-request Shop StoreProductRequest
php artisan module:make-resource Shop ProductResource

# Business Service
php artisan module:make-service Shop DiscountService

# Migrations & Seeders
php artisan module:make-migration Shop create_discounts_table
php artisan module:make-seeder Shop ProductSeeder
php artisan module:seed Shop

# Pest / PHPUnit Test
php artisan module:make-test Shop ProductTest

⚡ Production Optimization

In production environments, avoid scanning the filesystem on every request by compiling a discovery manifest:

php artisan module:cache

To clear the compiled cache:

php artisan module:clear

(Integrated with native php artisan optimize and php artisan optimize:clear).

⚖️ When to Choose Lite vs Enterprise

🧪 Testing

composer test

🎨 Code Style

composer format:check
composer format

📄 License

The MIT License (MIT). Please see License File for more information.