README

Laravel Modular is a modern modular architecture package for Laravel 11, 12, and 13. It gives large Laravel applications clean module boundaries without replacing Laravel's native development experience.

The core idea is simple: keep writing Laravel code, but scope it to modules when the domain needs separation.

php artisan make:module Blog
php artisan make:model Post --module=Blog -mcf
php artisan make:controller Api/PostController --module=Blog --api
php artisan modular:doctor

No parallel framework. No mandatory custom generator vocabulary. No app-level stub culture. Just native Laravel commands, module-aware paths, production diagnostics, and an architecture that can grow with your application.

Why Laravel Modular

Most modular packages ask teams to learn a second command language and a package-specific structure. Laravel Modular takes the opposite approach: it keeps Laravel familiar and makes the module boundary invisible until you need to inspect, cache, export, migrate, or validate it.

• Native command parity: Laravel make:* commands support --module, including common flags such as -mcf, --api, and --resource.
• Production diagnostics: modular:doctor, modular:status, modular:debug, modular:graph, and modular:why make module state inspectable.
• Boost-aware: ships Laravel Boost guidelines and a development skill so AI agents understand the package.
• Cache freshness: discovery cache metadata tracks manifest hashes and detects stale module state.
• Dependency graph safety: supports topological boot ordering, dependency checks, conflicts, and capabilities.
• Migration path: modular:import-nwidart helps teams evaluate migration from nwidart/laravel-modules.
• Package-ready modules: modules include Composer metadata and can be exported with modular:export.

Quick Start

Install the package:

composer require alizharb/laravel-modular

Preview the installer:

php artisan modular:install --dry-run

Install and configure the application:

php artisan modular:install

Create a module:

php artisan make:module Blog

Generate native Laravel resources inside the module:

php artisan make:model Post --module=Blog -mcf
php artisan make:request StorePostRequest --module=Blog
php artisan make:policy PostPolicy --module=Blog --model=Post
php artisan make:test PostFeatureTest --module=Blog

Inspect and validate:

php artisan modular:list
php artisan modular:status
php artisan modular:doctor
php artisan modular:test Blog

Generated Structure

Laravel Modular keeps the module layout close to a Laravel application:

modules/
└── Blog/
    ├── module.json
    ├── composer.json
    ├── package.json
    ├── app/
    │   ├── Http/
    │   ├── Models/
    │   ├── Providers/
    │   └── Console/
    ├── config/
    ├── database/
    │   ├── factories/
    │   ├── migrations/
    │   └── seeders/
    ├── resources/
    │   ├── views/
    │   ├── lang/
    │   └── assets/
    ├── routes/
    │   ├── web.php
    │   └── api.php
    └── tests/
        ├── Feature/
        └── Unit/

Module Manifest

module.json is the source of truth for module metadata:

{
  "name": "Blog",
  "namespace": "Modules\\Blog\\",
  "provider": "Modules\\Blog\\Providers\\BlogServiceProvider",
  "version": "1.2.0",
  "requires": [],
  "conflicts": [],
  "provides": ["publishing"],
  "removable": true,
  "disableable": true
}

The manifest is validated by modular:doctor, exposed through JSON diagnostics, and included in cache freshness checks.

Daily Commands

# Discovery and diagnostics
php artisan modular:list
php artisan modular:status
php artisan modular:status --json
php artisan modular:doctor
php artisan modular:doctor --json
php artisan modular:doctor --fix
php artisan modular:debug Blog --json

# Dependency understanding
php artisan modular:check
php artisan modular:graph
php artisan modular:graph --format=dot
php artisan modular:why Blog

# Database and tests
php artisan modular:migrate Blog
php artisan modular:migrate Blog --rollback --step=2
php artisan modular:seed Blog
php artisan modular:test Blog

# Production
php artisan modular:cache
php artisan modular:refresh
php artisan modular:sync

# Package workflows
php artisan modular:export Blog --path=packages/blog
php artisan modular:import-nwidart --dry-run

Laravel Boost

Laravel Modular ships first-class Laravel Boost resources:

• resources/boost/guidelines/core.blade.php
• resources/boost/skills/laravel-modular-development/SKILL.md

After installing Laravel Boost in an application, run:

php artisan boost:install

If Laravel Modular was installed after Boost, rediscover package resources:

php artisan boost:update --discover

Boost-aware agents will learn to use native make:* --module commands, respect module boundaries, validate module.json, run diagnostics, and avoid introducing custom scaffolding systems.

Production Workflow

Run Laravel's normal optimization commands, then cache modular discovery:

composer install --no-dev --optimize-autoloader
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan modular:cache

If deployment may reuse an older discovery cache:

php artisan modular:refresh

modular:cache stores module metadata, statuses, discovered resources, manifest hashes, dependency hashes, provider lists, and a cache timestamp. modular:doctor warns when cached module manifests no longer match disk.

CI Recipe

name: modular-quality

on:
  pull_request:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'
          coverage: none

      - run: composer install --no-interaction --prefer-dist --ansi

      - run: php artisan modular:doctor --json

      - run: php artisan modular:check

      - run: php artisan test

Laravel Modular vs nwidart/laravel-modules

Both packages solve real problems. nwidart/laravel-modules is mature, widely known, and has a large command surface. Laravel Modular is for teams that want module architecture while staying closer to native Laravel.

Area	Laravel Modular	nwidart/laravel-modules
Generator style	Native make:* --module=Blog	Package-specific module:* commands
AI support	Laravel Boost guidelines and skill included	Not first-class
Diagnostics	doctor, status, debug, graph, why	More traditional module management
Cache freshness	Manifest hash metadata and stale cache checks	Configurable cache
Migration	modular:import-nwidart dry-run/import flow	Not applicable
Philosophy	Laravel-native code inside module boundaries	Module package abstraction
Production posture	JSON diagnostics, cache metadata, lifecycle events	Mature ecosystem and broad usage

See Comparison and Migration From nwidart.

Migration From nwidart

Preview first:

php artisan modular:import-nwidart --dry-run

Import one module from a custom source:

php artisan modular:import-nwidart Blog --from=NwidartModules

Then validate:

php artisan modular:doctor
php artisan modular:graph
php artisan modular:test Blog

Ecosystem

Laravel Modular is intentionally lean. Optional ecosystem packages can add focused integrations without making the core package heavy:

Package	Purpose
Laravel Hooks	Extensibility and hook workflows
Laravel Modular Filament	Filament integration for modules
Laravel Modular Livewire	Livewire discovery and registration
Laravel Themer	Theme management

Documentation

• Installation
• Architecture
• Commands
• Command Parity
• Deployment
• Laravel Boost
• Migration From nwidart
• Performance
• Comparison
• Roadmap

Security

Please review SECURITY.md for supported versions and vulnerability reporting.

Contributing

Contributions are welcome. Please review CONTRIBUTING.md before opening a pull request.

License

The MIT License (MIT). Please see LICENSE.md for more information.