Download the PHP package protibimbok/laramod without Composer

Laramod

Explicit modules for Laravel.

A module is a class. What it provides is declared by the contracts that class implements, and modules are listed by hand in one file. There is no auto-discovery, no manifest, no cache to rebuild and no per-module composer.json.

Requirements

• PHP 8.3+
• Laravel 13

Installation

laramod:init is safe to run again at any time. It:

• creates the Modules/ directory and bootstrap/modules.php,
• publishes config/laramod.php,
• adds "Modules\\": "Modules/" to the PSR-4 autoloading in composer.json and runs composer dump-autoload,
• adds Modules/*/Tests/Unit and Modules/*/Tests/Feature to the test suites in phpunit.xml,
• tells you how to set up the Vite plugin when the application has a Vite config.

composer.json and phpunit.xml are edited as text, so the rest of the file stays as you wrote it. When the expected place is not found, the command prints the line to add by hand instead.

Creating a module

The command also lists the module in bootstrap/modules.php:

Directories that hold classes are StudlyCase (Http, Models, Database, Tests), everything else is lowercase (config, lang, resources, routes, ai-workflow).

The stubs can be customised after php artisan vendor:publish --tag=laramod-stubs.

Registering modules

bootstrap/modules.php returns the module classes. The order of the list is the order the modules are wired in. A module from a Composer package is added to the same list.

Modules can also be registered from the register() method of any service provider:

What a module can provide

A module gains a capability by implementing its contract from Laramod\Contracts. Nothing is looked up on disk: a module without ProvidesViews has no views, whatever its directories contain.

A path a module returns is relative to its path(): 'resources/views'. An absolute path is taken as it is.

Views, translations and components use the module name as their namespace:

Anonymous components live in resources/views/components, class components in the module's View\Components namespace.

Routes

Module routes must point to controller actions, never closures, so route:cache keeps working. Once the routes are cached, the route methods of the modules are not called at all.

Config

Generated modules merge their config under modules.<name>:

The prefix keeps a module called Auth, Cache or Mail away from the framework's own config. A module is free to return another key.

Seeders

ProvidesSeeders is for the data a module cannot work without. Demo and test data stay ordinary seeders that the application registers and calls itself.

Module seeders only run where you ask for them, for example in DatabaseSeeder:

Seeder::runSeeders() runs the seeders of every module in the order the modules are wired, Seeder::runSeeders('blog') those of one module. Both are silent. For Laravel's usual console output, hand the classes to the seeder yourself with $this->call(Seeder::seeders());.

Generators

Every generator of the framework accepts --module (the make:*-table commands do not: they publish the framework's own migrations, which no module owns):

Files are created inside the module with the module's namespace, including everything a command creates along the way (make:model -mfs keeps the migration, factory and seeder in the module). Without the option the commands behave exactly as they do in a stock application.

Laravel finds factories by naming convention, which does not reach into a module, so the generators link them explicitly: the model gets #[UseFactory(PostFactory::class)] and the factory gets protected $model = Post::class;.

Generated view names are namespaced (view('blog::components.alert')), and models, enums, traits, interfaces and scopes always go to Models, Enums, Concerns, Contracts and Models/Scopes.

Only the application's own modules are written to. --module fails for a module in vendor, or outside the application as a symlinked path repository is, and what such a module provides is published instead.

A generator from another package supports the option once it uses the Laramod\Console\Concerns\TargetsModule trait, provided it extends Laravel's GeneratorCommand.

Publishing

Installed modules are read-only, so what they provide can be copied into the application with the stock vendor:publish:

A module only has the tags for what it provides. Published views and translations override the module's, published config wins key by key, and published migrations keep their file names, so they never run twice.

Vite

laramod-vite-plugin builds the entries the modules declare, reloads the page when module views or routes change and adds an @<module> alias for every module.

A module declares its entries relative to itself and loads them the same way, so a view works wherever the module is installed:

Modules::vite() returns what @vite returns. In Vite's manifest an entry is named by its path from the project root, Modules/Blog/resources/js/app.js or vendor/acme/blog/resources/js/app.js, and the application's own views may use that path with the stock @vite directive. Loading an entry the module does not declare is an error, because the dev server would serve it while the build would not contain it.

The JavaScript of an installed module can only import npm packages the application has installed itself.

AI workflow

A module carries its guidance for AI agents in its own ai-workflow directory: README.md is the entry point and workflows/*.md hold step-by-step guides. There are no AGENTS.md or CLAUDE.md files inside modules.

With Laravel Boost, select protibimbok/laramod when boost:install lists third-party guidelines. The application's agent is then told to run laramod:list --json and to read a module's workflow before changing the module or using its classes. An application can override the guidance of an installed module with vendor:publish --tag=blog-ai.

Commands

Configuration

config/laramod.php:

Testing

License

Laramod is open-sourced software licensed under the MIT license.