kadevland/easy-modules

Organize your Laravel application into modules following the Clean Architecture. 30+ commands for fast modular development.

dev-main 2025-05-25 20:15 UTC

Requires

• php: ^8.2
• illuminate/console: ^12.0
• illuminate/filesystem: ^12.0
• illuminate/support: ^12.0

Requires (Dev)

• laravel/pint: ^1.0
• orchestra/testbench: ^10.0
• phpunit/phpunit: ^11.0

MIT

• Kadevland

• package
• php
• modules
• laravel
• ddd
• modular
• laravel-modules
• laravel-development
• module-generator
• laravel-package
• developer-tools
• clean-architecture
• rapid-development
• domain-driven-design
• php-package
• artisan-commands
• clean-code
• laravel-12
• easy-modules
• modular-application
• code-organization
• modular-structure
• simple-modules
• easy-setup
• scaffold-generator

README

⚠️ Development Status: This package is currently in active development (v0.3.0). While functional, some features may change before the stable release.

Easy Module is a Laravel package that enables you to organize your application using modular architecture. Generate organized, maintainable applications with automatic component registration and structured code separation. Clean Architecture configuration is provided as a ready-to-use setup.

✨ Key Features

• 🏗️ Modular Structure - Organized application architecture with configurable layers
• ⚡ Auto-Generation - Create complete modules with one command
• 🔄 Auto-Discovery - Automatic module registration and loading
• 🎯 Extensible - Add custom scaffold files and components
• 🚀 Easy to Use - Simple commands with intelligent defaults
• 🏛️ Clean Architecture Ready - Pre-configured setup for Domain, Application, Infrastructure, and Presentation layers
• 🆕 Laravel 12 Ready - Full compatibility with Laravel 12's latest features

🚀 Installation & Quick Start

Requirements

• Laravel 12+ - Built specifically for Laravel 12
• PHP 8.2+ - Required by Laravel 12
• Composer - For package management

Installation

Install via Composer:

composer require --dev kadevland/easy-modules

Publish configuration:

# Default way
php artisan vendor:publish --provider="Kadevland\EasyModules\EasyModulesServiceProvider" --tag="config"

# Using Easy Module command
php artisan easymodules:publish

# Publish with options
php artisan easymodules:publish --all      # Config & stubs
php artisan easymodules:publish --stubs    # Stubs only
php artisan easymodules:publish --force    # Force overwrite

Create your first module:

# Single module
php artisan easymodules:new Blog

# Multiple modules
php artisan easymodules:new Blog User Product

# Using aliases
php artisan emodules:new Shop
php artisan emodule:new Auth

🛠️ Commands & Generators

EasyModules provides 29 powerful commands for rapid development:

• 🔧 4 Utility commands - Module creation, publishing, module listing, flexible generation
• 🏗️3 Clean Architecture commands - Entities, services, and custom components
• 🚀 22 Laravel-compatible commands - All Laravel generators, module-aware

👉 Complete Command Reference Guide - Full documentation with examples

Quick Examples

# Create a complete blog module
php artisan easymodules:new Blog

# Generate Clean Architecture components
php artisan easymodules:make-entity Blog Post
php artisan easymodules:make-service Blog PostService

# Use familiar Laravel commands in modules
php artisan easymodules:make-model Blog Post --migration --factory

# Flexible Clean Architecture generation
php artisan easymodules:make-stub Blog UserRepository repository
php artisan easymodules:make-stub Shop OrderDTO dto
php artisan easymodules:make-stub User EmailValueObject valueobject

# List discovered modules
php artisan easymodules:list --routes

Command Aliases

All commands support these prefixes:

• easymodules: (full)
• emodules: (short)
• emodule: (shortest)

🏗️ What Gets Generated

When you run:

php artisan easymodules:new Blog

app/Modules/Blog/
├── Application/
│   ├── Actions/
│   ├── DTOs/
│   ├── Interfaces/
│   ├── Mappers/
│   ├── Rules/
│   ├── Services/
│   └── Validation/
├── Domain/
│   ├── Entities/
│   ├── Services/
│   └── ValueObjects/
├── Infrastructure/
│   ├── Casts/
│   ├── Exceptions/
│   ├── Mappers/
│   ├── Models/
│   ├── Persistences/
│   └── Services/
├── Presentation/
│   ├── Console/
│   │   └── Commands/
│   ├── Http/
│   │   ├── Controllers/
│   │   ├── Middlewares/
│   │   ├── Requests/
│   │   └── Resources/
│   ├── Mappers/
│   ├── Views/
│   │   └── Components/
│   └── resources/
│       └── views/
├── Database/
│   ├── Factories/
│   ├── Migrations/
│   └── Seeders/
├── Tests/
│   ├── Feature/
│   └── Unit/
├── Providers/
│   └── BlogServiceProvider.php
├── config/
│   └── config.php
├── routes/
│   ├── api.php
│   ├── console.php
│   └── web.php
└── lang/

Plus these files are auto-generated:

• BlogServiceProvider.php - Automatically registered with Laravel
• config/config.php - Module-specific configuration
• routes/*.php - Route files with example routes
• All folder structure following Clean Architecture principles

⚙️ Configuration & Customization

Flexible configuration in config/easymodules.php

return [
    // Module location and namespace
    'base_path' => app_path('Modules'),
    'base_namespace' => 'App\\Modules',

    // Laravel 12 auto-discovery
    'auto_discover' => true,

    // Custom paths per component
    'paths' => [
        'controller' => 'Presentation/Http/Controllers',
        'model' => 'Infrastructure/Models',
        'entity' => 'Domain/Entities',
        'service' => 'Application/Services',
        // ...
    ],

    // Custom stubs
    'stubs' => [
        'controller' => 'easymodules/controller.stub',
        'entity' => 'easymodules/entity.stub',
        // ...
    ]
];

Customizable stubs

# Publish stubs for customization
php artisan easymodules:publish --stubs

# Modify in resources/stubs/easymodules/

🔄 Laravel 12 Auto-Discovery

EasyModules integrates perfectly with Laravel 12:

✅ Automatic registration of ServiceProviders ✅ Route discovery for web, API and console ✅ Module configuration loading ✅ Asset support with Vite

# See all discovered modules
php artisan easymodules:list --routes

🧪 Testing Configuration

PHPUnit

<!-- phpunit.xml -->
<testsuites>
    <testsuite name="Feature">
        <directory suffix="Test.php">./tests/Feature</directory>
        <directory suffix="Test.php">./app/Modules/*/Tests/Feature</directory>
    </testsuite>
    <testsuite name="Unit">
        <directory suffix="Test.php">./tests/Unit</directory>
        <directory suffix="Test.php">./app/Modules/*/Tests/Unit</directory>
    </testsuite>
</testsuites>

Pest

// tests/Pest.php
uses(Tests\TestCase::class)->in('Feature', 'Unit');
uses(Tests\TestCase::class)->in('app/Modules/*/Tests/Feature');
uses(Tests\TestCase::class)->in('app/Modules/*/Tests/Unit');

🔧 Vite Integration (Laravel 12)

// vite.config.js
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import { glob } from 'glob';

const moduleAssets = [
    ...glob.sync('app/Modules/*/Presentation/resources/js/**/*.js'),
    ...glob.sync('app/Modules/*/Presentation/resources/css/**/*.css'),
];

export default defineConfig({
    plugins: [
        laravel({
            input: [
                'resources/css/app.css',
                'resources/js/app.js',
                ...moduleAssets,
            ],
            refresh: [
                'app/Modules/*/Presentation/resources/views/**',
                'app/Modules/*/routes/**',
            ],
        }),
    ],
});

🛠️ Benefits of Modular Architecture

✅ Separation of Concerns

• Domain : Pure business logic, independent
• Application : Use cases and orchestration
• Infrastructure : Persistence and external services
• Presentation : User interface and APIs

✅ Maintainability

• Code organized by functionality
• Isolated and fast tests
• Easier team development

✅ Scalability

• Add features without impact
• Independent and reusable modules
• Possibility to extract into packages

📚 Complete Documentation

• 📖 Command Guide - Complete reference for 30+ commands
• 🔧 Configuration Guide - Advanced customization
• 🏗️ Architecture Templates - Future multi-pattern feature

🤝 Contributing

Contributions are welcome! Please see contributing guide.

📝 Changelog

Please see CHANGELOG for more information on recent changes.

🔒 Security

For security issues, please email [e-mail].

📄 License

Open-source package under MIT license.

👨‍💻 Credits

• Kadevland - Creator and maintainer
• Contributors - Thank you for your contributions!

Made with ❤️ by Kadevland

⭐ Star us on GitHub if this project helps you!

Laravel Easy Modules - Your modular architecture in 30 seconds 🚀