README

The Plug-and-Play Engine for Laravel Modules.

Introduction

Laravel Modules Plus is a zero-configuration enhancement designed to transform your modules into truly self-contained, autonomous units. By extending the provided AbstractModuleServiceProvider, your modules instantly become Plug-and-Play: they automatically handle their own resource registration, factory resolution, and data seeding without any manual boilerplate in the main application.

Why use this package?

Module Autonomy: Modules become self-configuring "mini-packages". Drop a module into any project, and its logic is instantly alive.
Standardized Structure: Enforces a clean, consistent convention across all modules, making your codebase predictable and enterprise-ready.
Zero-Config Discovery: Automatic registration of Routes, Policies, Observers, and Events based on simple folder conventions.
Agnostic Factory Resolution: Automatically resolves Eloquent factories for modular models. Keep your models clean and free of package-specific traits.
Dynamic Seeding: Effortlessly manage data population with helpers that discover seeders across your entire modular ecosystem.
Full Command Integration: All original nWidart/laravel-modules commands are fully supported and aware of the Environment Control patch.
AI-Enhanced Development: Includes a built-in Laravel Boost Skill to help AI agents build and maintain your modules correctly.
Contextual Flexibility: Optionally separate resources (Migrations, Seeders) into specific contexts like Tenant or Central for complex architectures.

Support us

We invest a lot of resources into creating best in class open source packages. You can support us by sponsoring us on GitHub.

Installation

Install the package via composer:

composer require victormgomes/laravel-modules-plus

(Optional) Publish the configuration and stubs:

php artisan modules-plus:install

Update your config/modules.php to use the new Activator:

'activator' => 'env',
'activators' => [
    'env' => [
        'class' => \Victormgomes\ModulesPlus\Activators\EnvActivator::class,
    ],
],

Usage

1. Activating Modules

Manage module activation directly via your .env file, keeping your modules_statuses.json out of version control:

APP_MODULES_ENABLED=Auth,User,Chat,Billing

All standard commands (e.g., php artisan module:list, module:migrate) will respect this setting automatically. Commands like php artisan module:enable {name} will now update your .env file directly.

2. Standard Plug-and-Play Structure

By extending AbstractModuleServiceProvider, the following resources are discovered and registered automatically (respecting any custom paths defined in your modules.php configuration):

Routes: routes/api.php and routes/web.php are loaded with standard middleware.
Config: Automatically merges {module}/config/{module}.php into the global configuration.
Views: Loads views from resources/views/ using the {module}:: namespace.
Translations: Loads lang files from resources/lang/ (including JSON).
Migrations: All migrations in database/migrations/ are loaded by default.
Factories: Factories in database/factories/ are automatically resolved for modular models.
Seeders: All seeders in database/seeders/ can be dynamically retrieved for seeding.
Policies: app/Policies/UserPolicy.php is automatically linked to app/Models/User.php.
Observers: app/Observers/UserObserver.php is automatically linked to app/Models/User.php.
Events/Listeners: Automatically discovers listeners in the app/Listeners/ directory.
Console Commands: Automatically registers all commands in app/Console/Commands/.
View Components: Registers components in app/View/Components/.
Livewire: Automatically registers components in the Livewire/ directory.

3. Contextual Discovery (Advanced)

For more complex architectures (like Multi-Tenancy), the package allows you to silo resources into sub-contexts:

Contextual Migrations: Place migrations in database/migrations/Tenant to load them only in specific database contexts.
Contextual Seeders: Use subfolders like database/seeders/Tenant/ and retrieve them using the SeederPaths helper:

use Victormgomes\ModulesPlus\Support\SeederPaths;
use Victormgomes\ModulesPlus\Support\TenantSeeders;

// Get seeders for any custom context
$seeders = SeederPaths::get('MyContext');

// Or use the built-in Tenant helper
$seeders = TenantSeeders::getSeeders();

$this->call($seeders);

AI Agent Integration (Laravel Boost)

This package includes a dedicated Laravel Boost Skill. When installed, it helps AI agents (like Gemini CLI, Cursor, or Claude) understand the modular architecture, respect folder conventions, and generate correct plug-and-play code.

To install the skill in your project:

php artisan boost:install

Then select victormgomes/laravel-modules-plus from the third-party skills list.

Configuration

After publishing the configuration via php artisan modules-plus:install, you can customize the following in config/modules-plus.php:

custom_stubs: When enabled, the package uses internal optimized stubs that follow the AbstractModuleServiceProvider pattern.
paths: Define additional folder conventions for resource discovery that are not present in the default nWidart/laravel-modules configuration.

Testing

composer test

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Credits

License

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

victormgomes / laravel-modules-plus

Maintainers

Package info

Fund package maintenance!

Statistics

Security