Modules Laravel Package

Getting Started

Install the package with Composer:

composer require caffeinated/modules

If your Laravel version does not auto-discover the provider, register it in config/app.php:

Caffeinated\Modules\Providers\ModulesServiceProvider::class,

and add the facade alias if you plan to use it:

'Module' => Caffeinated\Modules\Facades\Module::class,

Publish the package config:

php artisan vendor:publish --provider="Caffeinated\Modules\Providers\ModulesServiceProvider"

Confirm the exact provider class and publish tag inside vendor/caffeinated/modules if your version differs. The first place to look after publishing is config/modules.php: it controls the modules path (normally Modules/), namespace, and discovery behavior. Then inspect the generated Modules/ directory.

The fastest first use case is a throwaway module:

php artisan module:make Blog
php artisan module:list

This scaffolds a module with a module.json manifest, a service provider, routes, controllers, views, migrations, and seeders. Add a route in Modules/Blog/Routes/web.php, a controller in Modules/Blog/Http/Controllers, return view('blog::index') from a generated view, run php artisan module:migrate blog, and hit the route. That single loop—scaffold, route, migrate, view—is the core day-to-day workflow. Run composer dump-autoload if newly generated classes are not resolving.

Implementation Patterns

Treat modules as business-capability slices, not as a replacement for Laravel’s normal app/ structure. Good candidates are Blog, Billing, Shop, Admin, or Reporting; poor candidates are “Models”, “Controllers”, or “Helpers”. Keep the host app thin and let each module own its HTTP layer, routes, views, migrations, and domain services.

A typical module layout looks like this:

Modules/Blog/
  module.json
  Providers/BlogServiceProvider.php
  Http/Controllers/
  Http/Requests/
  Models/
  Routes/web.php
  Routes/api.php
  Resources/views/
  Resources/lang/
  Database/Migrations/
  Database/Seeds/
  Config/config.php

Use the generated module service provider as the module’s composition root. Register its routes, views, translations, config merging, and container bindings there. Keep the host application’s providers focused on cross-cutting concerns.

Day-to-day conventions:

• Namespacing: classes live under Modules\Blog\...; views are referenced as blog::index; translations as blog::messages.welcome.
• Routing: apply web or api middleware explicitly inside the module route files. If you add an API module, define its prefix and middleware in the module’s route group rather than assuming the app-level RouteServiceProvider handles it.
• Migrations and seeders: use php artisan module:migrate blog and php artisan module:seed blog. In deployment scripts, loop over enabled modules or run the module commands explicitly rather than assuming a global migrate command covers everything.
• Enable/disable as environment flags: module:enable blog and module:disable blog are backed by the module manifest. This is useful for turning whole feature slices on or off per environment. Guard host code with Module::isEnabled('blog') when a module is optional.
• Cross-module communication: avoid reaching directly into another module’s Eloquent models. Expose a service class, contract, or domain event. If several modules need shared utilities, create a small Core or Shared module rather than creating hidden coupling.
• Facade integration: use Module::all(), Module::enabled(), or Module::isEnabled('blog') to build navigation, register permissions, or conditionally boot optional integrations.
• Load order: if one module depends on another’s bindings or routes, control ordering through the manifest’s order field and keep dependencies explicit.
• Assets: keep source assets inside the module and publish them with module:publish blog (or the equivalent publish command in your version). Re-publish after changes.

For testing, test module internals as unit tests and test integration through the host application as feature tests. In test setups, register module migration paths or run module migrations during bootstrap, and clear module-related caches between tests so discovery state does not leak.

Gotchas and Tips

• Version compatibility is the first risk. The last release was March 2021, so confirm the illuminate/* constraints in the package’s composer.json before adopting it. Treat Laravel 8 as the likely practical ceiling; Laravel 9+ may require a fork or a different package.
• The project is not actively maintained. The opportunity score is low for a reason. Budget for forking or compare against nwidart/laravel-modules if you need a long-lived modular architecture.
• Cache invalidation causes most “disappearing module” bugs. After enabling, disabling, or adding a module, run php artisan config:clear, php artisan route:clear, php artisan view:clear, and composer dump-autoload as appropriate. Do not debug discovery while config or route caches are warm.
• module.json is the source of truth. Manual edits and merge conflicts can silently change enabled state across environments. Prefer the Artisan commands and review manifest diffs in code review.
• Names and casing must agree. A module folder Blog, namespace Modules\Blog, slug blog, and view namespace blog:: all need to line up. Case-sensitive Linux filesystems expose sloppy casing immediately.
• Migrations are not table-prefixed automatically. Namespace table names by module, for example blog_posts, to avoid collisions. Rollback order matters when modules reference each other’s tables.
• Disabling a module does not remove its classes from the autoloader. Host code can still instantiate a class from a disabled module. Guard optional integrations with Module::isEnabled() and avoid hard dependencies on disabled slices.
• Config merging is explicit. If config('blog.some_key') returns null, the module config was not merged in the service provider, or the config cache is stale. Use mergeConfigFrom in the module provider.
• Asset publishing can overwrite customizations. Back up or version-control published public assets before re-running publish commands.
• Facade and provider registration errors are easy to misdiagnose. “Class ‘Module’ not found” usually means the alias is missing or the provider was not registered. On newer Laravel versions, double registration can duplicate routes or bindings.
• Debug with the package’s own visibility tools. Use php artisan module:list to inspect state, and php artisan tinker with Module::all() or Module::isEnabled('blog') to confirm discovery. Check bootstrap/cache and provider registration order when behavior differs between local and production.
• Extension points are limited by the package’s age. You can publish config to change module paths and namespaces, override generated stubs where supported, and bind custom implementations in module providers. Keep a thin host-level provider for anything that must span modules, and avoid relying on undocumented internals that will make a future fork harder.