README

Frontier Module

Modular architecture for Laravel applications — A companion package to the Frontier Laravel Starter Kit that enables organizing large applications into self-contained, reusable modules.

✨ Features

📦 Modular Organization — Break large apps into logical, self-contained modules
🔄 Auto-Discovery — Commands, migrations, factories, policies, and Blade components work automatically
🛠️ Familiar Tooling — Use standard php artisan make:* commands with --module flag
📋 Laravel Conventions — Follows standard Laravel patterns you already know
🚀 Lightweight — Minimal overhead, powered by InterNACHI/Modular
📤 Extractable — Modules can become separate Composer packages later
✅ Strict Types — All classes use declare(strict_types=1)
🧪 Pest Testing — Modern testing framework included

📋 Requirements

Requirement	Version
PHP	8.2+
Laravel	10.x, 11.x, or 12.x

🚀 Installation

composer require frontier/module

Laravel will auto-discover the service provider. No additional configuration required.

Optional: Publish Configuration

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

📖 Quick Start

Create a Module

# Create a new module
php artisan make:module user-management

# Update Composer (required after creating modules)
composer update modules/user-management

This scaffolds:

app-modules/
└── user-management/
    ├── composer.json
    ├── src/
    │   └── Providers/
    ├── tests/
    ├── routes/
    ├── resources/
    └── database/

Generate Components

Use standard Laravel make:* commands with --module:

php artisan make:model User --module=user-management
php artisan make:controller UserController --module=user-management
php artisan make:migration create_users_table --module=user-management
php artisan make:request CreateUserRequest --module=user-management

Sync Configuration

# Sync phpunit.xml, PhpStorm settings, etc.
php artisan modules:sync

📁 Module Structure

app-modules/
└── my-module/
    ├── composer.json           # Module's Composer configuration
    ├── src/
    │   ├── Models/             # Eloquent models
    │   ├── Http/
    │   │   ├── Controllers/    # HTTP controllers
    │   │   ├── Middleware/     # Module-specific middleware
    │   │   └── Requests/       # Form requests
    │   ├── Providers/          # Service providers
    │   ├── Console/Commands/   # Artisan commands
    │   ├── Jobs/               # Queue jobs
    │   ├── Events/             # Event classes
    │   ├── Listeners/          # Event listeners
    │   └── Services/           # Business logic services
    ├── tests/
    │   ├── Feature/
    │   └── Unit/
    ├── routes/
    │   ├── web.php
    │   └── api.php
    ├── resources/
    │   ├── views/
    │   └── lang/
    └── database/
        ├── migrations/
        ├── seeders/
        └── factories/

💡 Usage Examples

Module Routes

app-modules/user-management/routes/api.php

<?php

declare(strict_types=1);

use Illuminate\Support\Facades\Route;
use Modules\UserManagement\Http\Controllers\UserController;

Route::prefix('api/users')->middleware(['api', 'auth:sanctum'])->group(function () {
    Route::get('/', [UserController::class, 'index']);
    Route::post('/', [UserController::class, 'store']);
    Route::get('/{user}', [UserController::class, 'show']);
});

Module Controller

<?php

declare(strict_types=1);

namespace Modules\UserManagement\Http\Controllers;

use Illuminate\Http\JsonResponse;
use Modules\UserManagement\Services\UserService;

class UserController
{
    public function __construct(
        private readonly UserService $userService
    ) {}

    public function index(): JsonResponse
    {
        return response()->json([
            'data' => $this->userService->getAllUsers()
        ]);
    }
}

Blade Components

Components are auto-registered with module namespace:

// app-modules/dashboard/src/View/Components/StatCard.php
namespace Modules\Dashboard\View\Components;

use Illuminate\View\Component;

class StatCard extends Component
{
    public function __construct(
        public string $title,
        public string|int $value
    ) {}

    public function render()
    {
        return view('dashboard::components.stat-card');
    }
}

{{-- Usage --}}
<x-dashboard::stat-card title="Users" :value="$count" />

Translations

// app-modules/user-management/resources/lang/en/messages.php
return [
    'welcome' => 'Welcome, :name!',
];

// Usage
__('user-management::messages.welcome', ['name' => $user->name]);

🔧 Artisan Commands

Module Management

Command	Description
`php artisan make:module <name>`	Create a new module
`php artisan modules:list`	List all modules
`php artisan modules:sync`	Sync project configs
`php artisan modules:cache`	Cache module discovery
`php artisan modules:clear`	Clear module cache

Supported Make Commands

All Laravel make:* commands support --module:

php artisan make:controller UserController --module=my-module
php artisan make:model User --module=my-module
php artisan make:migration create_users_table --module=my-module
php artisan make:request CreateUserRequest --module=my-module
php artisan make:resource UserResource --module=my-module
php artisan make:policy UserPolicy --module=my-module
php artisan make:event UserCreated --module=my-module
php artisan make:listener SendEmail --module=my-module
php artisan make:job ProcessUser --module=my-module
php artisan make:command ImportUsers --module=my-module
php artisan make:factory UserFactory --module=my-module
php artisan make:seeder UserSeeder --module=my-module
php artisan make:test UserTest --module=my-module

Database Seeding

php artisan db:seed --module=my-module
php artisan db:seed --class=UserSeeder --module=my-module

🎯 When to Use Modules

✅ Use Modules When:

Scenario	Benefit
Large applications (50+ models)	Better organization
Multiple domains	Separate bounded contexts
Team development	Independent workstreams
Potential extraction	Easy to extract as packages

❌ Stick to Traditional Structure When:

Scenario	Reason
Small apps (< 20 models)	Overhead not worth it
Simple CRUD apps	No clear domain boundaries
Rapid prototyping	Speed over organization

⚙️ Configuration

Custom Namespace

Edit config/app-modules.php:

return [
    'modules_namespace' => 'App\\Modules',  // Default: 'Modules'
    'modules_path' => base_path('app-modules'),
];

Production Caching

# Add to deployment script
php artisan modules:cache

🛠️ Development

Running Tests

composer test

Code Linting

composer lint        # Fix code style with Pint
composer lint:test   # Check code style

Rector Refactoring

composer rector      # Apply automated refactorings
composer rector:dry  # Preview changes without applying

🔗 Frontier Ecosystem

Package	Purpose
frontier/frontier	Laravel Starter Kit
frontier/module	Modular architecture
frontier/action	Action pattern
frontier/repository	Repository pattern

📚 Documentation

For comprehensive documentation including advanced examples, inter-module communication patterns, and best practices, see AI_GUIDE.md.

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

📄 License

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

👨‍💻 Author

Mohamed Khedr
Email: 0xkhdr@gmail.com

Made with ❤️ for the Laravel community

frontier / module

Maintainers

Details