Laramodule Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require hexters/laramodule
   

   Publish the package configuration and migrations:

   php artisan vendor:publish --provider="Hexters\Laramodule\LaramoduleServiceProvider" --tag="config"
   php artisan vendor:publish --provider="Hexters\Laramodule\LaramoduleServiceProvider" --tag="migrations"
   php artisan migrate
   

2. First Module Creation: Generate a new module with:

   php artisan module:make Blog
   

   This creates a Modules/Blog directory with default structure (controllers, routes, views, etc.).

3. Registering a Module: Add the module to config/laramodule.php under the modules array:

   'modules' => [
       'Blog' => [
           'enabled' => true,
           'path' => base_path('Modules/Blog'),
       ],
   ],
   

4. First Use Case: Define a route in Modules/Blog/Routes/web.php:

   Route::get('/posts', 'BlogController@index');
   

   Access it via /blog/posts (or your configured module prefix).

Implementation Patterns

Module Structure & Workflows

1. Modular Routing:

   • Use Route::module('Blog') prefix in module-specific route files to auto-prefix routes with the module name.
   • Example:

     Route::module('Blog')->get('/posts', 'BlogController@index');
     

   • Routes are automatically loaded from Modules/{Module}/Routes/web.php and Modules/{Module}/Routes/api.php.

2. Service Providers:

   • Each module can have its own service provider (Modules/{Module}/Providers/{Module}ServiceProvider.php).
   • Register bindings in the provider’s boot() method:

     public function boot()
     {
         $this->app->bind('BlogService', function () {
             return new BlogService();
         });
     }
     

3. Views & Assets:

   • Views are stored in Modules/{Module}/Resources/views.
   • Use @include('modules::{Module}::partials.header') to reference module-specific views.
   • Publish module assets with:

     php artisan module:publish-assets Blog
     

4. Database & Migrations:

   • Migrations are stored in Modules/{Module}/Database/Migrations.
   • Run module-specific migrations with:

     php artisan module:migrate Blog
     

   • Seeders follow the same pattern (Modules/{Module}/Database/Seeders).

5. Dependency Injection:

   • Inject module services into controllers:

     public function __construct(BlogService $blogService) {
         $this->blogService = $blogService;
     }
     

6. Module Activation/Deactivation:

   • Toggle modules via the laramodule:enable/laramodule:disable commands:

     php artisan laramodule:enable Blog
     php artisan laramodule:disable Blog
     

   • Check module status in config/laramodule.php or via the Module facade:

     if (Module::isEnabled('Blog')) { ... }
     

7. Middleware:

   • Apply module-specific middleware in Modules/{Module}/Http/Kernel.php:

     protected $middleware = [
         \App\Http\Middleware\VerifyBlogAuth::class,
     ];
     

8. Events & Listeners:

   • Dispatch module-specific events:

     event(new \Modules\Blog\Events\PostCreated($post));
     

   • Register listeners in the module’s service provider.

Gotchas and Tips

Common Pitfalls

1. Route Prefix Conflicts:

   • Ensure module route prefixes (e.g., /blog/posts) don’t clash with global routes.
   • Use Route::module('Blog')->prefix('custom-prefix') to override defaults.

2. Namespace Collisions:

   • Modules auto-load with their namespace (e.g., Modules\Blog\Http\Controllers\BlogController).
   • Avoid naming conflicts by using unique module names and consistent naming conventions.

3. Caching Issues:

   • Clear Laravel caches after adding/removing modules:

     php artisan cache:clear
     php artisan config:clear
     php artisan route:clear
     

4. Service Provider Loading Order:

   • Module service providers are loaded alphabetically. Use explicit ordering in config/app.php if dependencies exist between modules.

5. View Path Resolution:

   • If views aren’t found, verify the views path in Modules/{Module}/composer.json:

     "extra": {
         "laravel": {
             "views": "Resources/views"
         }
     }
     

6. Database Transactions:

   • Module migrations run in batches. Use php artisan module:migrate Blog --seed to run migrations + seeders together.

7. Testing Modules:

   • Mock module dependencies in tests:

     $this->app->instance(\Modules\Blog\Services\BlogService::class, MockBlogService::class);
     

Debugging Tips

1. Check Module Status:

   php artisan laramodule:list
   

   Lists all modules and their enabled/disabled status.

2. Route Debugging: Use php artisan route:list to verify module routes are registered. Filter by module:

   php artisan route:list | grep blog
   

3. Service Binding Issues:

   • Check if the service provider is registered in config/app.php under providers.
   • Use php artisan package:discover to refresh service providers.

4. View Debugging:

   • Enable Laravel’s debug mode (APP_DEBUG=true in .env) to catch missing view errors.
   • Verify view paths with:

     php artisan view:clear
     

Extension Points

1. Custom Module Commands: Extend the package by creating custom commands in app/Console/Commands and binding them to the module’s service provider.

2. Module Events: Listen for module lifecycle events (e.g., ModuleEnabled, ModuleDisabled) in your app’s event listeners.

3. Dynamic Module Loading: Use the Module facade to dynamically load module configurations:

   $moduleConfig = Module::config('Blog');
   

4. API for Module Management: Build an admin panel to manage modules via the Hexters\Laramodule\Contracts\ModuleRepository interface.

5. Override Default Behaviors: Bind interfaces in your app’s service provider to replace default implementations (e.g., ModuleRepository).