README

A lightweight Laravel package for generating self-contained application modules with Laravel's native structure.

Requirements

PHP 8.3+
Laravel 13

Installation

Install the package with Composer:

composer require arsham-sh/laravel-modular

Laravel automatically discovers the package service provider.

Usage

Create a module

Create a module with:

php artisan module:make Auth

When the command is run interactively, it asks how much should be generated and provides these presets:

basic - controllers, models, and API routes
normal - database-backed CRUD with controllers, models, database, and API routes
advanced - normal plus form requests, a service, feature tests, and unit tests
all - advanced plus resources, policies, middleware, a console command, and all supported components

The generator also creates the module configuration, service provider, and module.json metadata automatically.

You can select a preset directly:

php artisan module:make Auth --preset=basic
php artisan module:make Auth --preset=normal
php artisan module:make Auth --preset=advanced
php artisan module:make Auth --preset=all

--basic is a backward-compatible alias for --preset=basic.

For non-interactive environments, use the normal preset:

php artisan module:make Auth --no-prompts

If the command is executed in a non-interactive environment without an explicit preset, it also falls back to the normal preset.

Select components explicitly

For custom module layouts, generate only the components you need:

php artisan module:make Auth \
    --components=controllers \
    --components=models \
    --components=routes

Supported components are:

controllers
requests
models
services
resources
policies
database
routes
middleware
console
feature-tests
unit-tests
traits

Component dependencies are resolved automatically. For example, controllers require models and routes, while services, resources, policies, and database generation require models. Feature tests require routes, and unit tests require services and models.

Generate a controller

Create a controller inside an existing module:

php artisan module:make-controller Auth User

For a resource-style controller:

php artisan module:make-controller Auth User --resource

The --resource option generates index, store, show, update, and destroy methods.

Controllers generated by this command use the shared Modules\Shared\App\Traits\HttpResponses response helper.

Generated Module Structure

A generated module follows Laravel's familiar application structure:

Modules/
└── Auth/
    ├── App/
    │   ├── Console/
    │   ├── Http/
    │   │   ├── Controllers/
    │   │   ├── Middleware/
    │   │   ├── Requests/
    │   │   └── Resources/
    │   ├── Models/
    │   ├── Policies/
    │   ├── Providers/
    │   ├── Services/
    │   └── Traits/
    ├── Config/
    │   └── config.php
    ├── Database/
    │   ├── Factories/
    │   └── Migrations/
    ├── Routes/
    │   └── api.php
    ├── Tests/
    │   ├── Feature/
    │   └── Unit/
    └── module.json

Only the selected components are generated.

Config/config.php, the module service provider, and module.json are created for every module.

The generated route file uses Laravel's API resource routing:

Route::apiResource('auths', AuthController::class);

The generated model uses a simple name attribute by default. Database generation adds a migration and factory for that model.

Module Loading

Generated modules are discovered from Modules/*/module.json by the package service provider.

Enabled modules have their namespace registered and their module service provider loaded automatically.

A module can be disabled by setting its enabled value to false in module.json:

{
    "name": "Auth",
    "enabled": false
}

Development

Install the package dependencies with:

composer install

The package is intended to be installed into a Laravel application.

For local development, a consuming Laravel application should live outside the package repository when using Composer's path repository.

For example:

GitHub/
├── laravel-modular/
└── test-module/

Then the consuming application's composer.json can use:

"repositories": [
    {
        "type": "path",
        "url": "../laravel-modular"
    }
]

Install the local package with:

composer require arsham-sh/laravel-modular:@dev

Do not place the consuming Laravel application inside the laravel-modular repository. Composer cannot install the package into a directory contained within its own source.

Philosophy

Laravel Modular keeps modules close to Laravel's native conventions while giving each module its own namespace, configuration, routes, provider, and optional application components.

The generator is explicit:

Interactive usage lets you choose a preset.
Scripts can select a preset directly.
Custom workflows can select individual components.
Component dependencies are resolved automatically.
Non-interactive execution uses the normal preset unless another preset or component selection is provided.

No third-party modular architecture package is required.

License

Laravel Modular is open-sourced software licensed under the MIT license.

arsham-sh / laravel-modular

Package info

Security

Statistics