Getting Started

Minimal Steps

Install the Package:
```
composer require internachi/modular-livewire
```
No additional configuration is needed—Laravel’s package discovery auto-registers the service provider and plugin.

Organize Your Components: Place Livewire components in src/Livewire/ within your modules. Example structure:

app-modules/
├── billing/
│   └── src/
│       └── Livewire/
│           ├── InvoiceTable.php       → billing::invoice-table
│           └── Reports/
│               └── MonthlySummary.php → billing::reports.monthly-summary

Use in Blade: Reference components using the auto-generated namespace:

<livewire:billing::invoice-table />
<livewire:billing::reports.monthly-summary />

Verify Discovery: Run php artisan livewire:discover (if needed) or restart your Laravel server to ensure components are registered.

First Use Case: Adding a New Module Component

Create a new Livewire component in app-modules/users/src/Livewire/UserProfile.php.
Use it in a Blade view:
```
<livewire:users::user-profile />
```
The component is automatically registered and available for use.

Implementation Patterns

Workflows

1. Component Development Workflow

Create: Place new Livewire components in src/Livewire/ within the relevant module.
Test: Use php artisan livewire:test (if available) or manually verify in Blade.
Deploy: No additional steps required—components are auto-discovered on boot.

2. Module-Based Development

Team Ownership: Assign modules to teams (e.g., users, billing). Each team owns their src/Livewire/ components.
Isolation: Changes to users::user-profile won’t affect billing::invoice-table.

3. Blade Integration

Dynamic Component Loading: Use the module namespace to dynamically load components:

@php
$module = 'users';
$component = 'user-profile';
@endphp
<livewire:"$module::$component" />

Conditional Rendering:

@auth
    <livewire:users::user-profile />
@endauth

Integration Tips

1. With `internachi/modular`

Ensure your modules are properly registered with internachi/modular. The package extends its plugin system, so module discovery must work first.
Use php artisan modular:list to verify modules are loaded before testing Livewire components.

2. With Livewire Features

Properties and Events: Leverage Livewire’s reactivity as usual. The package only handles component registration.
```
// app-modules/users/src/Livewire/UserProfile.php
public $name;
public function save()
{
    // Logic here
}
```
Views: Place corresponding Blade views in resources/views/livewire/{module-name}/{component-name}.blade.php. Example: resources/views/livewire/billing/invoice-table.blade.php.

3. Customizing Discovery

Override Discovery Logic: If needed, publish the package’s config and extend the discovery logic:

php artisan vendor:publish --provider="InterNACHI\ModularLivewire\ModularLivewireServiceProvider"

Exclude Directories: Filter out non-Livewire classes by extending the discovery service (advanced).

4. Testing Components

Use Laravel’s Livewire testing helpers:

use Livewire\Livewire;

public function test_user_profile()
{
    Livewire::test('users::user-profile')
        ->assertSee('User Profile');
}

Mock module dependencies in tests if components rely on module-specific services.

Gotchas and Tips

Pitfalls

1. Naming Conventions

Hyphenated Module Names: If your module is named my-module, the component will register as my-module::component. Ensure Blade templates use kebab-case:
```
<livewire:my-module::component /> 
<livewire:my_module::component /> 
```
Reserved Words: Avoid module/component names that conflict with Laravel/Livewire reserved words (e.g., livewire, blade).

2. Directory Structure

Missing src/Livewire/: Components won’t be discovered if the directory doesn’t exist. Create it explicitly:
```
mkdir -p app-modules/{module}/src/Livewire/
```
Nested Directories: Subdirectories in src/Livewire/ become dot notation in the namespace:
```
src/Livewire/Reports/MonthlySummary.php → billing::reports.monthly-summary
```

3. Caching Issues

Livewire Cache: Clear Livewire’s view cache if components aren’t updating:
```
php artisan view:clear
php artisan cache:clear
```
Module Caching: If using internachi/modular’s caching, ensure modules are re-scanned after adding new components.

4. Class Autoloading

PSR-4 Conflicts: Ensure your composer.json autoloads module classes correctly. Example:
```
"autoload": {
    "psr-4": {
        "App\\Modules\\": "app-modules/"
    }
}
```
Run composer dump-autoload after adding new modules.

5. Livewire Version Mismatch

The package supports Livewire 3.x and 4.x (as of v1.1.0). Ensure your livewire/livewire version matches:
```
composer require livewire/livewire:^3.0
```

Debugging

1. Component Not Found

Check Registration: Verify the component is registered by inspecting the Livewire container:
```
dd(\Livewire\Livewire::getComponentClasses());
```
Module Loading: Ensure the module is loaded:
```
php artisan modular:list
```
Discovery Logs: Enable debug mode to see discovery logs:
```
MODULAR_LIVEWIRE_DEBUG=true
```

2. Blade Template Not Loading

View Path: Ensure the Blade view exists at resources/views/livewire/{module}/{component}.blade.php.
Namespace Mismatch: Double-check the Blade directive matches the registered namespace:
```
@livewireScripts
```
(This is auto-included by Livewire, but verify no conflicts exist.)

3. Performance Issues

Discovery Overhead: If the app is slow, profile the ModularLivewirePlugin boot time. Consider lazy-loading modules.
Large Modules: Avoid monolithic modules with hundreds of components. Split into smaller modules.

Tips

1. IDE Support

Configure your IDE (PHPStorm, VSCode) to recognize module namespaces:
- Add to settings.json (VSCode):
```
"php.validate.executablePath": "/path/to/php",
"php.validate.run": "onType",
"php.suggest.modulePrefixes": ["App\\Modules\\"]
```
- Use use App\Modules\{Module}\Livewire\{Component}; for better autocompletion.

2. Extending Functionality

Custom Registration: Override the default registration by binding a custom LivewireManager:

// app/Providers/AppServiceProvider.php
public function register()
{
    $this->app->bind(
        \InterNACHI\ModularLivewire\Contracts\LivewireManager::class,
        \App\Services\CustomLivewireManager::class
    );
}

Dynamic Components: For dynamic module loading, listen to the ModulesRegistered event:

use InterNACHI\Modular\Events\ModulesRegistered;

public function boot()
{
    event(ModulesRegistered::class, function () {
        // Re-register Livewire components if modules are loaded dynamically
    });
}

3. Migration Strategies

Gradual Adoption: Start with non-critical modules. Use feature flags to toggle between old and new registration:

// app-modules/billing/src/Livewire/InvoiceTable.php
public static function shouldRegister()
{
    return config('features.modular_livewire', false);
}

Fallback Registration: For components not auto-discovered, manually register them in a service provider:
```
Livewire::component('fallback::component', \App\Modules\Fallback\Livewire\Component::class);
```

4. Security

Module Isolation: Ensure modules are isolated to prevent component namespace collisions.

Validation: Validate component inputs in rules() to prevent XSS or invalid data:

public function rules()
{
    return [
        'name' => 'required|string|max:255',

Modular Livewire Laravel Package