Laravel Modular Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require alizharb/laravel-modular
   php artisan modular:install
   

   This sets up autoloading, Vite integration, and default paths.

2. Create First Module:

   php artisan make:module Blog
   

   This generates a fully structured module with:

   • module.json (configuration)
   • composer.json (isolated dependencies)
   • package.json (frontend dependencies)
   • Standard Laravel directories (app/, resources/, etc.)

3. Generate Resources:

   php artisan make:model Post --module=Blog -mcf
   php artisan make:controller API/PostController --module=Blog --api
   

First Use Case: Isolated Feature Development

Use the --module flag with any make: command to scaffold resources inside a module:

php artisan make:controller Admin/PostController --module=Blog --resource

This creates modules/Blog/app/Http/Controllers/Admin/PostController.php.

Implementation Patterns

Core Workflows

1. Modular Artisan Commands: Override any Laravel make: command by adding --module=ModuleName:

   php artisan make:policy PostPolicy --module=Blog
   

2. Dependency Management:

   • Define module dependencies in module.json:

     {
       "dependencies": ["Auth", "Database"]
     }
     

   • Sync dependencies to root composer.json:

     php artisan modular:sync
     

3. Asset Pipeline:

   • Use modular_vite() in Blade:

     @vite(['resources/js/app.js', modular_vite('Blog')])
     

   • Link module assets:

     php artisan modular:link
     

4. Database Operations:

   php artisan modular:migrate Blog --fresh
   php artisan modular:seed Blog
   

Integration Tips

• Service Providers: Register module-specific providers in modules/ModuleName/app/Providers/ModuleNameServiceProvider.php.
• Middleware: Define in module.json:

  "middleware": {
    "web": ["Modules\\Blog\\Http\\Middleware\\VerifyBlogUser"]
  }
  

• Events: Dispatch module-specific events:

  event(new \Modules\Blog\Events\PostPublished());
  

• Testing: Run module tests:

  php artisan modular:test Blog
  

Vite Integration

1. Create vite.modular.js:

   export const modularLoader = {
     inputs: () => [
       'modules/**/resources/js/*.js',
       'modules/**/resources/css/*.css'
     ],
     refreshPaths: () => [
       'modules/**/resources/js/*.js',
       'modules/**/resources/css/*.css'
     ]
   };
   

2. Update vite.config.js:

   import { modularLoader } from './vite.modular.js';
   

Gotchas and Tips

Pitfalls

1. Circular Dependencies:

   • Detect with:

     php artisan modular:check
     

   • Resolve by restructuring module.json dependencies.

2. Autoloading Issues:

   • Ensure "Modules\\": "modules/" exists in composer.json.
   • Run:

     composer dump-autoload
     php artisan modular:cache
     

3. Missing Module Registration:

   • Verify ModuleServiceProvider is registered in config/app.php under providers.
   • Run:

     php artisan modular:debug ModuleName
     

4. Blade Directives Not Working:

   • Ensure @moduleEnabled directives are used in Blade files within the resources/views directory of the module or root.

Debugging Tips

• Module Discovery:

  php artisan modular:list --tree
  

• Configuration: Publish config:

  php artisan vendor:publish --tag="modular-config"
  

  Customize paths, stubs, or composer defaults.

• Performance:

  • Cache discovery:

    php artisan modular:cache
    

  • Disable merge-plugin after syncing dependencies:

    php artisan modular:sync
    

Extension Points

1. Custom Stubs: Override default stubs by placing them in modules/ModuleName/stubs/.

2. Dynamic Module Activation: Enable/disable modules at runtime:

   php artisan module:enable Blog
   php artisan module:disable Store
   

3. Hooks Integration: Use Laravel Hooks for extensibility:

   Hook::add('blog.post.published', function () {
       // Run after post is published
   });
   

4. Filament/Livewire: Integrate with Modular Filament or Modular Livewire for admin panel or frontend component support.

Configuration Quirks

• Case-Insensitive Config: Access module config with either:

  config('Blog::settings.key');
  config('blog::settings.key');
  

• Default Module Path: Override in config/modular.php:

  'paths' => [
      'modules' => base_path('packages'),
  ],
  

Pro Tips

• Isolated Development: Use php artisan modular:npm Blog install to manage frontend dependencies per module.

• Zero-Downtime Deployments: Leverage modular:cache to avoid autoload regeneration during deployments.

• Standalone Modules: Export modules as Composer packages:

  php artisan modular:export Blog --path=packages/blog