Laravel Modules Livewire Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require mhmiton/laravel-modules-livewire
   php artisan vendor:publish --tag=modules-livewire:config
   

   • Verify config/modules-livewire.php exists in your project.

2. First Use Case: Create a Single File Component (SFC) for a module:

   php artisan module:make-livewire sfc.post.create Core --sfc
   

   • This generates:
     • A Livewire SFC in Modules/Core/Resources/views/livewire/sfc.post.create.blade.php.
     • A corresponding class in Modules/Core/App/Livewire/SfcPostCreate.php.
     • Auto-registers the component for the Core module.

3. Usage in Blade:

   @livewire('core::sfc.post.create')
   

   • The core:: prefix ensures the component is namespaced to the module.

Implementation Patterns

Workflows

1. Component Creation:

   • Use --sfc for Single File Components (recommended for simplicity).
   • Omit --sfc for traditional class-based Livewire components.
   • Example for class-based:

     php artisan module:make-livewire post.create Core
     

2. Module-Specific Registration:

   • Components are automatically registered under the module’s namespace (e.g., core::sfc.post.create).
   • No manual Livewire service provider configuration needed.

3. Reusing Components Across Modules:

   • Use the :: syntax to reference components from other modules:

     @livewire('admin::user.profile')
     

4. Configuration:

   • Customize the config/modules-livewire.php file to:
     • Change the default view path (e.g., livewire → components).
     • Adjust the component naming convention (e.g., kebab-case vs. snake_case).

5. Integration with Laravel Modules:

   • Leverage module-specific routes, middleware, and policies:

     // Modules/Core/Routes/web.php
     Route::get('/posts/create', fn () => view('core::pages.posts.create'))
          ->middleware(['auth', 'verified']);
     

   • Embed Livewire components in module-specific views:

     <!-- Modules/Core/Resources/views/pages/posts/create.blade.php -->
     @livewire('core::sfc.post.create')
     

6. Testing:

   • Test components in isolation using Livewire’s testing utilities:

     public function test_post_creation()
     {
         $this->livewire(SfcPostCreate::class)
              ->set('title', 'Test Post')
              ->call('save')
              ->assertEmitted('postCreated');
     }
     

   • Use module-specific test helpers if available.

Integration Tips

1. Asset Management:

   • Place module-specific CSS/JS in Modules/{Module}/Resources/assets/ and compile with Laravel Mix or Vite.
   • Use @stack directives in SFCs to load module-specific assets:

     @push('core-scripts')
         <script src="{{ asset('modules/core/js/post.js') }}"></script>
     @endpush
     

2. Shared Logic:

   • Create base Livewire classes in a shared module (e.g., Shared) and extend them in other modules:

     // Modules/Shared/App/Livewire/BaseComponent.php
     class BaseComponent extends Component {
         public function authorize() {
             return auth()->check();
         }
     }
     

     // Modules/Core/App/Livewire/SfcPostCreate.php
     class SfcPostCreate extends BaseComponent { ... }
     

3. Dynamic Component Loading:

   • Use the module() helper to dynamically resolve module paths:

     $module = module('Core');
     $viewPath = $module->getPath().'/Resources/views/livewire/sfc.post.create.blade.php';
     

4. Livewire Events:

   • Dispatch module-scoped events to avoid naming collisions:

     $this->dispatch('core-post-created', data: ['id' => $post->id]);
     

   • Listen in parent components or Blade:

     @script
         Livewire.on('core-post-created', (data) => {
             console.log('Post created:', data);
         });
     @endscript
     

5. Middleware:

   • Apply module-specific middleware to Livewire components:

     // Modules/Core/Http/Middleware/EnsureCoreUser.php
     public function handle($request, Closure $next) {
         if (!$request->user()->isCoreUser()) {
             abort(403);
         }
         return $next($request);
     }
     

     // Modules/Core/App/Livewire/SfcPostCreate.php
     public function middleware() {
         return [EnsureCoreUser::class];
     }
     

Gotchas and Tips

Pitfalls

1. Component Naming Collisions:

   • Avoid using the same component name (e.g., sfc.post.create) across modules.
   • Fix: Use descriptive names or prefixes (e.g., core.post.create vs. admin.post.create).

2. View Path Resolution:

   • If views aren’t found, verify:
     • The --sfc flag was used (or the component is in the correct class-based path).
     • The module is published (php artisan module:publish Core).
   • Debug: Check config/modules-livewire.php for custom view paths.

3. Livewire Component Not Auto-Registering:

   • Ensure the module is booted (e.g., php artisan module:boot Core).
   • Fix: Manually register the component in AppServiceProvider if needed:

     Livewire::component('core::sfc.post.create', \Modules\Core\App\Livewire\SfcPostCreate::class);
     

4. Asset Loading Issues:

   • Module-specific assets (CSS/JS) may not load if:
     • The module isn’t published.
     • Mix/Vite isn’t configured to include module paths.
   • Fix: Extend mix.js()/mix.css() to include module paths:

     mix.js('Resources/assets/js/app.js', 'public/js')
          .js('Modules/Core/Resources/assets/js/post.js', 'public/modules/core/js');
     

5. Testing Quirks:

   • Livewire components may fail tests if:
     • The module isn’t bootstrapped in the test environment.
     • Mock data isn’t properly seeded.
   • Fix: Use Module::bootForTesting() in tests:

     use Modules\Core\Module;
     
     public function setUp(): void {
         parent::setUp();
         Module::bootForTesting('Core');
     }
     

6. Caching:

   • Clear Livewire and module caches after changes:

     php artisan view:clear
     php artisan cache:clear
     php artisan module:clear-compiled
     

Debugging Tips

1. Log Component Registration:

   • Add debug logs in vendor/mhmiton/laravel-modules-livewire/src/ModuleLivewireServiceProvider.php to verify registration:

     Log::debug('Registering Livewire component:', ['name' => $name, 'class' => $class]);
     

2. Check Published Config:

   • Verify config/modules-livewire.php matches your expectations:

     'view_path' => 'livewire', // Default: 'livewire'
     'component_namespace' => 'modules', // Default: 'modules'
     

3. Inspect Blade Directives:

   • Use @dd to debug the @livewire directive’s resolved component:

     @php
         dd(\Livewire::getComponentClass('core::sfc.post.create'));
     @endphp
     

4. Livewire Wire:Log:

   • Enable Livewire’s built-in logging:

     php artisan livewire:log
     

   • Check storage/logs/livewire.log for component lifecycle events.

Extension Points

1. Custom Component Factories:

   • Extend the component creation logic by publishing and modifying the stubs:

     php artisan vendor:publish --tag=modules-livewire:stubs
     

   • Edit stubs in resources/stubs/livewire/ to add custom logic (e.g., auto-injecting traits).

2. Dynamic Module Loading:

   • Override the ModuleLivewireServiceProvider to lazy-load modules:

     public function register()
     {
         if (!$this->app->runningInConsole()) {
             $this->loadModules();
         }
     }
     

3. Hybrid Components:

   • Combine SFCs and class-based components by:
     • Using SFCs for simple components.
     • Using class-based components for complex logic with traits/mixins.

4. API Integration:

   • Extend Livewire components to interact with module-specific APIs:

     // Modules/Core/App/Live