README

Laravel Modules brings a clean, zero‑config modular structure to your Laravel app. Place your modules under the project root Modules/ directory and this package will auto‑discover and wire their assets: configs, service providers, helpers, artisan commands, migrations, translations, views, Blade components, routes (web/api/console/broadcasting), schedules, listeners/events, Livewire, Filament, Nova, and more.

Sensible conventions: namespaces, view/component aliases, and route groups are derived automatically.

Fine‑grained control: enable/disable modules, control load order, and override discovery patterns from config/modules.php.

Fast by default: built‑in caching makes discovery quick in all environments.

Support Us
Documentation
Requirements
Installation
Quick start
Configuration overview
Features
Caching
Testing
Changelog
Contributing
Security Vulnerabilities
Credits
License

Support us

Creating and maintaining open-source projects requires significant time and effort. Your support will help enhance the project and enable further contributions to the Laravel community.

Sponsorship can be made through the GitHub Sponsors program. Just click the "Sponsor" button at the top of this repository. Any amount is greatly appreciated, even a contribution as small as $1 can make a big difference and will go directly towards developing and improving this package.

Thank you for considering sponsoring. Your support truly makes a difference!

Documentation

Detailed documentation, including examples and best practices, lives in the docs directory.

Index

Start here: docs/README.md

Feature guides

Requirements

PHP: ^8.1
Laravel: ^10.34.2 | ^11.29.0 | ^12.0

Installation

Install via Composer:

composer require mozex/laravel-modules

Publish the config file (optional, only if you want to tweak defaults):

php artisan vendor:publish --tag=laravel-modules-config

This will publish config/modules.php.

Quick start

By default, modules live under the project root Modules/ directory. Each module contains a conventional structure, for example:

project-root/
├── app/
├── bootstrap/
├── config/
├── database/
├── Modules/
│   ├── Blog/
│   │   ├── Config/
│   │   ├── Console/
│   │   ├── Database/
│   │   │   ├── Factories/
│   │   │   ├── Migrations/
│   │   │   └── Seeders/
│   │   ├── Filament/
│   │   ├── Lang/
│   │   ├── Listeners/
│   │   ├── Models/
│   │   ├── Policies/
│   │   ├── Providers/
│   │   ├── Resources/
│   │   │   └── views/
│   │   ├── Routes/
│   │   └── View/
│   │       └── Components/
│   └── Shop/
│       └── ...
└── vendor/

Out of the box, the package will automatically discover and register the following assets inside your modules: configs, service providers, helpers, artisan commands, migrations, translations, views, Blade components, models, factories, policies, routes, schedules, listeners/events, Livewire, Filament, and Nova resources.

Use your assets via namespaced conventions:

Views: view('blog::post.show') maps to Modules/Blog/Resources/views/post/show.blade.php
Class-based Blade components: <x-blog::post.card/> for Modules/Blog/View/Components/Post/Card.php
Anonymous Blade components (from views): <x-blog::button.primary/> for Modules/Blog/Resources/views/components/button/primary.blade.php
Routes: drop files under Modules/*/Routes/*.php and they will be loaded under sensible groups (web, api). See the Routes feature docs for customization.

Note for contributors: the test workbench lives in workbench/ and follows the same conventions (workbench/Modules/*).

Configuration overview

All options live in config/modules.php.

modules_directory: default Modules (relative to the project base path). Change where your modules are stored.
modules_namespace: default Modules\\. Change the PSR-4 base namespace for your modules.

modules: per-module activation and ordering. Example:

'modules' => [
    'Shared' => [
        'active' => true,
        'order' => 1, // lower loads earlier
    ],
],

Per-asset sections: each feature can be enabled/disabled and configured with glob patterns and other options. For example, Blade Components:
```
'blade-components' => [
    'active' => true,
    'patterns' => [
        '*/View/Components',
    ],
],
```
Configs merging priority: when 'configs.priority' => true, values from your modules override the app config; when false, app config wins and modules provide defaults.

You can disable any feature by setting 'active' => false in its section.

Features

This package discovers and wires many module assets. We’ll document them in depth, one by one. Suggested reading order:

Blade Components (class-based)
Views (namespaces, anonymous components)
Routes (groups, api/web, broadcasting, commands)
Configs (merging strategy, priority)
Migrations
Seeders
Commands
Helpers
Models & Factories
Policies
Events & Listeners
Schedules
Livewire Components
Filament (Resources, Pages, Widgets, Clusters)
Nova Resources

Caching

This package supports a single discovery cache that speeds up scanning your Modules directory. Use these commands:

Build the discovery cache:
```
php artisan modules:cache
```
Clear the discovery cache:
```
php artisan modules:clear
```

Tip: after adding, renaming, or moving module assets, clear any relevant Laravel caches and rebuild the modules discovery cache as needed.

Testing

composer test

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

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

mozex / laravel-modules

Maintainers

Details