Livewire V4 Patch Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev s1k3/livewire-v4-patch
   php artisan vendor:publish --provider="LivewireV4\LivewireV4PatchServiceProvider"
   

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

2. First Use Case: Convert a single class component to MFC:

   php artisan convert-class-to:mfc app/Livewire/MyComponent.php
   

   • Check the output in resources/views/components/my-component.blade.php (or your configured mfc_component_path).

3. Quick Check:

   • Run php artisan list to see the new command.
   • Validate the generated MFC structure matches your expectations (e.g., props, methods, and views).

Implementation Patterns

Core Workflow

1. Batch Conversion: Use the command in a loop for all class components:

   find app/Livewire -name "*.php" | xargs -I {} php artisan convert-class-to:mfc {}
   

   • Exclude directories via excluded_directories in config (e.g., ['tests', 'stubs']).

2. Integration with Livewire v4:

   • Replace use Livewire\Component; with use Livewire\Component; (if needed) in generated MFCs.
   • Update mount() to public function mount() if using dependency injection.

3. Asset Management:

   • Enable create_js/create_css in config to auto-generate:

     'create_js' => true,
     'create_css' => true,
     

   • Files are created in resources/js/components/ and resources/css/components/ (adjust paths if needed).

4. Partial Conversions:

   • Use --partial flag to convert only specific methods/views:

     php artisan convert-class-to:mfc MyComponent.php --partial
     

   • Manually edit the generated MFC to retain custom logic.

5. Testing:

   • Test converted components in a staging environment first.
   • Use php artisan livewire:discover to validate MFC registration.

Gotchas and Tips

Pitfalls

1. Namespace Conflicts:

   • Generated MFCs use resources/views/components/{kebab-case}.blade.php.
   • Ensure no naming collisions with existing Blade files (e.g., user-profile vs. user_profile).

2. State Management:

   • Class component public $property becomes public $property; in MFCs.
   • Gotcha: Reactive properties (public $reactiveProp) may need manual adjustment if using Alpine.js or custom logic.

3. Asset Paths:

   • Hardcoded asset paths (e.g., href="{{ asset('css/app.css') }}") in class components break in MFCs.
   • Fix: Use @vite() or @asset() directives in Blade templates.

4. Method Overrides:

   • Class component render() methods are converted to Blade views.
   • Gotcha: Custom render() logic (e.g., PDF generation) won’t work—move to a separate method.

5. Dependency Injection:

   • Constructor injection in class components (public function __construct(Foo $foo)) may not convert cleanly.
   • Tip: Use mount() for dependencies in MFCs:

     public function mount(Foo $foo) { ... }
     

Debugging

1. Dry Run:

   • Use --dry-run to preview changes without writing files:

     php artisan convert-class-to:mfc MyComponent.php --dry-run
     

2. Log Output:

   • Enable verbose mode for conversion details:

     php artisan convert-class-to:mfc MyComponent.php --verbose
     

3. Config Validation:

   • Ensure class_component_path and mfc_component_path are correct.
   • Tip: Use absolute paths in config to avoid issues:

     'class_component_path' => base_path('app/Http/Livewire'),
     

Extension Points

1. Custom Templates:

   • Override the Blade template engine used for MFC generation by publishing and modifying:

     php artisan vendor:publish --tag="livewire-v4-patch-templates"
     

   • Edit resources/views/vendor/livewire-v4-patch/mfc.blade.php.

2. Post-Conversion Hooks:

   • Add a service provider to run logic after conversion:

     LivewireV4Patch::afterConversion(function ($componentName) {
         // Example: Auto-register the MFC in a config file
     });
     

3. Emoji Support:

   • Enable emoji: true for fun but avoid in production:

     'emoji' => env('APP_ENV') === 'local',
     

4. Global CSS:

   • Set global_css: true to output CSS in a single file (e.g., resources/css/app.css).
   • Caution: May cause style conflicts in large apps.

Performance Tips

1. Batch Processing:

   • For large codebases, process components in chunks to avoid memory issues:

     find app/Livewire -name "*.php" | head -n 20 | xargs -I {} php artisan convert-class-to:mfc {}
     

2. Exclude Tests:

   • Always exclude test directories:

     'excluded_directories' => ['tests', 'stubs', 'Livewire/Testing'],
     

3. Backup First:

   • Backup your app/Livewire directory before bulk conversions:

     cp -r app/Livewire app/Livewire.backup