Download the PHP package hatchyu/laravel-modular without Composer

Laravel Modular

The Architectural Backbone for Enterprise Laravel Applications

Laravel Modular is a high-performance, zero-boilerplate Domain-Driven Design (DDD) 4-Layer Modular Architecture and Pragmatic CQRS framework engineered for senior developers and enterprise teams building large-scale, mission-critical software.

Whether you are architecting an ERP, CRM, Banking platform, Healthcare system, or Multi-domain enterprise SaaS, this package delivers the strict architectural guardrails, automated boundary enforcement, and production-optimized tooling needed to scale your modular monolith with total confidence.

[!TIP] Looking for a Simpler Modular Setup?
If you are building standard CRUD apps, MVPs, small-to-medium SaaS, or websites and want feature modularity without the ceremony of DDD layers, CQRS actions, and repository interfaces, check out our lightweight Laravel-native companion package:
👉 hatchyu/laravel-modular-lite (composer require hatchyu/laravel-modular-lite)

Key Features

• 🚀 Zero-Boilerplate Auto-Discovery: Automatically discovers module configs, service providers, routes (web.php & api.php), database migrations, and namespaced views.
• 🏛️ DDD 4-Layer Architecture: Cleanly partitions modules into Domain/, Application/, Interface/, Infrastructure/, and Database/.
• ⚡ Zero Runtime Filesystem Scanning: Built-in php artisan module:cache compiles full discovery manifests, completely eliminating runtime filesystem syscalls in production.
• 🛠️ Full-Featured Artisan CLI: Generators for Domain Models, Policies, Enums, Events, CQRS Actions (writes), Queries (reads), DTOs (Data), Rules, Services, Thin Controllers, Requests, Resources, Jobs, Tests, Migrations, and Seeders.
• 🗂️ Nested Sub-Namespace Support: Seamlessly generate components into subdirectories (e.g. V1/CreateOrderAction, Api/V2/OrderController, Relations/OrderItem).
• 🔄 Overwrite Protection & --force: Standard --force option across all generator commands.
• 🏭 Smart Factory Guesser: Automatically resolves Eloquent model factories located inside Modules\{Module}\Database\Factories.
• 🩺 Diagnostic Health Checks: php artisan module:check validates PSR-4 mappings, directory permissions, and service provider readiness.
• 🔌 Module Enable / Disable & Manifests: Toggle individual modules on or off dynamically (php artisan module:enable / module:disable) via local module.json manifests.
• 🕸️ Topological Dependency Boot Graph: Declare module dependencies ("dependencies": ["Billing"]). Boots modules in strict topological order (Kahn's algorithm), guaranteeing dependencies are ready before dependents boot.
• 🛡️ Fail-Safe Dependency Guardrails: Runtime protection and CLI guardrails prevent broken states when dependencies are disabled or missing, with actionable repair instructions.
• 🔄 Safe Module Renaming Propagation: php artisan module:rename refactors directories, namespaces, providers, seeders, views, and updates dependency declarations across all other modules.
• 🧩 Non-Invasive & Standards-Compliant: Adheres to modern PHP 8.4+ and strict typing standards without vendor lock-in.

Architecture Blueprint (DDD 4-Layer)

Each module (modules/{ModuleName}/) is structured into four explicit architectural layers plus database and delivery files:

Standard Module Namespaces

Installation

Install the package via Composer:

1. Configure PSR-4 Autoloading

Add "Modules\\": "modules/" to your application's composer.json file under autoload.psr-4:

Then regenerate the Composer autoload files:

2. Publish Configuration (Optional)

This creates config/modular.php:

Module Lifecycle & Dependency Management

Every module can contain a local module.json manifest located at modules/{ModuleName}/module.json (automatically generated when running php artisan module:make):

Enabling & Disabling Modules

You can toggle modules on or off without deleting files or altering git history:

Disabled modules are completely excluded from service provider registration, route loading, database migrations, command discovery, view namespaces, and configuration merging.

Dependency Resolution & Topological Booting

When modules declare dependencies in module.json:

• Topological Boot Order: The system resolves the dependency graph using Kahn's algorithm so prerequisite modules (e.g. Billing) always boot before dependent modules (e.g. Order).
• Circular Dependency Detection: Detects any circular dependency loops (e.g. A -> B -> A) and throws an explicit ModuleDependencyException identifying the loop.

How Disabled or Missing Dependencies Are Handled

When a module depends on another module that is disabled or missing, the system handles it with clarity and safety:

1. At Application Boot Time: If Order is enabled but depends on disabled Billing, ModuleRegistry::enabled() halts execution with an actionable exception:

   If the dependency does not exist in the codebase:

2. At CLI Level (Safe Protection):

   • Preventing Accidental Breakage: If you attempt to disable a module that other active modules depend on, the command halts:

   • Enabling Prerequisite Validation: If you attempt to enable a module whose prerequisites are disabled, it guides you to enable the dependencies first:
3. In Health Diagnostics (php artisan module:doctor): Displays the status of every module and flags any missing or disabled dependencies in the health inspection table.

Safe Module Renaming

Rename any module safely across your entire codebase:

This single command:

1. Moves the directory from modules/Order to modules/Sales.
2. Renames OrderServiceProvider.php to SalesServiceProvider.php and OrderDatabaseSeeder.php to SalesDatabaseSeeder.php.
3. Refactors PHP namespaces, class names, view namespaces (order:: to sales::), and route prefixes across all module files.
4. Updates "name": "Sales" in the module's module.json.
5. Cross-module propagation: Scans all other modules in modules/ and updates any "dependencies" arrays containing "Order" to "Sales".
6. Flushes and rebuilds the module discovery cache.

Artisan CLI Commands

All generator commands support nested sub-namespaces (e.g. V1/CreateOrderAction) and {--force} to overwrite existing files.

Scaffolding a Complete Module

Scaffold an entire DDD 4-layer module:

Domain Layer Generators

Application Layer Generators (CQRS & Use-Cases)

Interface Layer Generators (Delivery)

Infrastructure Layer Generators

Database Layer Generators

Test Generators

Inspection, Diagnostics & Optimization Commands

Production Deployment Optimization

In production environments, add php artisan module:cache to your deployment pipeline:

This compiles all module discovery paths, routes, and presence flags into bootstrap/cache/modules.php, eliminating filesystem scanning completely.

Testing & Quality

Run the test suite using Pest:

Check code formatting using Pint:

License

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