README

A powerful modular architecture package for Laravel applications that allows you to organize your codebase into independent, reusable modules with automatic discovery and zero configuration.

• Document for LLMs and AI code editors

• Chat with AI for This Package

• حمایت مالی از من

✨ Features

• 📦 Zero Configuration - Modules are automatically discovered and registered via composer merge plugin

• 💾 Automatic Persistence - Module enable/disable states are automatically saved and restored

• ⚡ Performance Optimized - Built-in caching and lazy loading for production use

• ⚡ (saeedvir/laravel-modular 🆚 nWidart/laravel-modules) Peak memory: Improved by 23.1% and Memory usage improved by 10.2%

• 🎨 Complete Module Structure - Controllers, models, views, routes, migrations, translations

• 🔧 Artisan Commands - Comprehensive CLI tools for module management

• 📊 Performance Monitoring - Track module discovery and operation performance

• 🐛 Debug-Aware Logging - Respects APP_DEBUG for production-friendly logs

• 🧪 Testing Support - Built-in infrastructure for module testing

• 🎯 Laravel 11 & 12 & 13 - Full support for modern Laravel versions

📋 Requirements

• PHP ^8.2 (PHP ^8.3 for Laravel 13)
• Laravel ^11.0, ^12.0, or ^13.0
• Composer

📦 Installation

Install the package via composer:

composer require saeedvir/laravel-modular

The package will automatically register itself via Laravel's package auto-discovery.

Configure composer merge plugin in your root composer.json:

{
    "autoload": {
        "psr-4": {
            "App\\": "app/",
            "Database\\Factories\\": "database/factories/",
            "Database\\Seeders\\": "database/seeders/",
            "Module\\": "modules/"
        }
    },
    "extra": {
        "merge-plugin": {
            "include": ["modules/*/composer.json"]
        }
    },
    "config": {
        "allow-plugins": {
            "wikimedia/composer-merge-plugin": true
        }
    }
}

Publish the configuration file (optional):

php artisan vendor:publish --tag=module-config

📖 For detailed installation instructions, troubleshooting, and setup guide, see:
Installation Guide

🚀 Quick Start

Create Your First Module

php artisan module:make Blog
composer dump-autoload

This creates a complete module structure:

modules/Blog/
├── app/
│   ├── Console/
│   ├── Http/
│   │   ├── Controllers/
│   │   ├── Middleware/
│   │   └── Requests/
│   ├── Models/
│   ├── Providers/
│   │   └── BlogServiceProvider.php
│   └── Services/
├── config/
│   └── config.php
├── database/
│   ├── migrations/
│   ├── seeders/
│   └── factories/
├── resources/
│   ├── views/
│   └── lang/
├── routes/
│   ├── web.php
│   └── api.php
└── composer.json

php artisan module:list

Check Module Status

php artisan module:status

Remove a Module

php artisan module:remove Blog

📖 Usage

Creating Controllers

php artisan module:controller Blog PostController

Creating Models

php artisan module:make-model Blog Post --migration --factory --seeder

This creates a model in modules/Blog/app/Models/Post.php and optionally generates the associated migration, factory, and seeder.

Alternatively, you can create models manually:

<?php

namespace Modules\Blog\Models;

use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    protected $fillable = ['title', 'content', 'slug'];
}

Adding Routes

In modules/Blog/routes/web.php:

<?php

use Illuminate\Support\Facades\Route;
use Modules\Blog\Http\Controllers\PostController;

// Routes are automatically prefixed with 'blog'
Route::get('/', [PostController::class, 'index'])->name('index');
Route::resource('posts', PostController::class);

Note: All routes are automatically prefixed with the module name (/blog/ in this case). See Routing Guide for details.

Using Views

Create views in modules/Blog/resources/views/ and load them:

return view('blog::posts.index');

Migrations

Create migrations in your module:

php artisan module:make-migration Blog create_posts_table

Run migrations:

php artisan migrate

Testing

Generate a test for your module:

php artisan module:make-test Blog PostTest --feature

Run tests for a specific module or all modules:

php artisan module:test Blog
php artisan module:test --all

🎯 Advanced Features

Module Configuration

Each module can have its own configuration file in config/config.php:

return [
    'name' => 'Blog',
    'enabled' => true,
    'version' => '1.0.0',
    // Your custom config...
];

Access module config:

config('blog.version');

Register Livewire Components in Module Service Providers

use Livewire\Livewire;
    public function boot(): void
    {
        //your codes
        
        $this->registerLivewireComponents();
    
        //your codes
    }
protected function registerLivewireComponents(): void
{
    Livewire::component('admin::user-management', \Modules\Admin\Livewire\UserManagement::class);
}

usage :

admin::livewire.admin-login

Disabling Modules

You can easily enable or disable modules using Artisan commands. These states are automatically persisted in modules/modules.json.

# Disable a module
php artisan module:disable Blog

# Enable a module
php artisan module:enable Blog

Alternatively, you can manually list modules to be disabled in config/module.php:

'disabled' => [
    'OldModule',
],

Note: The persistent state in modules.json takes precedence over the config/module.php's disabled array.

Performance Optimization

The package includes built-in caching:

# Cache module discovery
php artisan module:cache

# Pre-calculate and optimize module discovery (recommended for production)
php artisan module:optimize

Debug Mode

When APP_DEBUG=true, the package logs:

• Module discovery events
• Cache operations
• Module creation/deletion
• Performance metrics

When APP_DEBUG=false (production), only errors are logged.

🛠️ Available Commands

⚙️ Configuration

The config/module.php file provides extensive configuration options:

return [
    // Module storage path
    'path' => base_path('modules'),
    
    // Disabled modules
    'disabled' => [],
    
    // Caching
    'cache' => [
        'enabled' => env('MODULE_CACHE_ENABLED', true),
        'key' => 'laravel_modular_cache',
        'lifetime' => 86400, // 24 hours
    ],
    
    // Auto-register routes
    'auto_register_routes' => true,
    
    // Custom stubs path
    'stubs_path' => null,
];

📚 Documentation

• Installation Guide - Complete installation and setup
• Routing Guide - Module routing and automatic prefixing ⭐
• Debug Logging - Debug mode and logging configuration
• Performance Optimization - Performance tips and caching
• Enhancement Summary - Feature enhancements and improvements

🆚 Comparison with nWidart/laravel-modules

Both packages provide modular architecture for Laravel, but with different approaches:

Laravel Modular (This Package)

Philosophy: Zero-configuration with native Composer integration

✅ Advantages:

• Zero Configuration - Uses wikimedia/composer-merge-plugin for automatic autoloading
• Native Composer - Works with standard Composer workflows
• Automatic Discovery - No manual registration needed
• Performance Focused - Built-in caching and performance monitoring
• Debug-Aware Logging - Respects APP_DEBUG for production
• Simpler Structure - Standard Laravel conventions
• Less Overhead - Minimal abstraction layer
• Composer-First - Each module has its own composer.json

Best For:

• Projects that prefer Composer-native solutions
• Teams familiar with standard Laravel structure
• Applications requiring high performance
• Projects with frequent module changes

nWidart/laravel-modules

Philosophy: Feature-rich with extensive abstisan commands

✅ Advantages:

• More Commands - Extensive artisan command set
• Asset Management - Built-in asset publishing
• Module Status - Enable/disable modules dynamically
• Established - Mature package with large community
• More Features - Additional abstractions and helpers

Best For:

• Projects needing extensive CLI tools
• Applications with complex module management needs
• Teams wanting more built-in features

Feature Comparison

When to Choose Laravel Modular

Choose this package if you:

• ✅ Want zero-configuration setup
• ✅ Prefer native Composer workflows
• ✅ Need optimal performance
• ✅ Like standard Laravel conventions
• ✅ Want minimal overhead
• ✅ Use composer dump-autoload workflow

When to Choose nWidart/laravel-modules

Choose nWidart if you:

• ✅ Need extensive artisan commands
• ✅ Want built-in asset management
• ✅ Require dynamic module enable/disable
• ✅ Prefer feature-rich solutions
• ✅ Need established community support

Migration from nWidart

Migrating is straightforward:

1. Module structure is similar (both use MVC)
2. Routes and views work the same way
3. Main difference is autoloading (Composer vs custom)
4. Our Installation Guide covers setup

Both packages are excellent choices - pick based on your project's needs! 🎯

🧪 Testing

composer test

🤝 Contributing

Please see CONTRIBUTING for details on how to contribute to this project.

📝 Changelog

Please see CHANGELOG for more information on what has changed recently.

🔒 Security

If you discover any security-related issues, please email saeed.es91@gmail.com instead of using the issue tracker.

👥 Credits

• saeed
• All Contributors

📄 License

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

💡 Examples

Blog Module Example

// Controller
namespace Modules\Blog\Http\Controllers;

use Modules\Blog\Models\Post;

class PostController extends Controller
{
    public function index()
    {
        $posts = Post::latest()->paginate(10);
        return view('blog::posts.index', compact('posts'));
    }
}

// Model
namespace Modules\Blog\Models;

use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    protected $fillable = ['title', 'content', 'slug', 'published_at'];
    protected $casts = ['published_at' => 'datetime'];
}

// Route
Route::prefix('blog')->group(function () {
    Route::resource('posts', PostController::class);
});

🌟 Why Laravel Modular?

• Scalability: Organize large applications into manageable modules
• Reusability: Share modules across projects
• Maintainability: Clear separation of concerns
• Team Collaboration: Teams can work on different modules independently
• Performance: Optimized for production with caching and lazy loading
• Modern: Built for Laravel 11 & 12 with PHP 8.2+

📊 Performance

• Module Discovery: ~15-20ms (cached)
• Autoloading: Native composer PSR-4 (optimal performance)
• Memory Usage: Minimal overhead with lazy loading
• Production Ready: Designed for high-traffic applications

Built with ❤️ for the Laravel community

If you find this package helpful, please consider giving it a ⭐ on GitHub!