Livewire Doctor Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require devrabiul/livewire-doctor
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Devrabiul\LivewireDoctor\LivewireDoctorServiceProvider"
   

2. First Command Run a full scan of your Livewire components:

   php artisan livewire:doctor:scan
   

   This generates a report in storage/logs/livewire-doctor.log and outputs a summary in the terminal.

3. Quick Fixes Use the fix command to auto-correct common issues:

   php artisan livewire:doctor:fix
   

   Confirm changes when prompted.

First Use Case

Debugging a Livewire component that fails silently

• Run php artisan livewire:doctor:scan to identify missing assets, invalid directives, or property mismatches.
• Use php artisan livewire:doctor:fix to auto-correct issues like:
  • Unregistered assets (e.g., missing @js, @vite directives).
  • Undefined properties in public arrays.
  • Inconsistent wire:model bindings.

Implementation Patterns

Daily Workflow Integration

1. Pre-Commit Hook Add to .git/hooks/pre-commit (or use Laravel Pint/Forge):

   php artisan livewire:doctor:scan --quiet
   

   Exit with error if critical issues are found.

2. CI/CD Pipeline Run in GitHub Actions/Laravel Forge:

   - name: Livewire Doctor Scan
     run: php artisan livewire:doctor:scan --format=json > livewire-report.json
   

   Parse the JSON output to block merges if issues exceed thresholds.

3. Onboarding New Developers Include in README.md:

   ## Livewire Best Practices
   Run `php artisan livewire:doctor:scan` to auto-detect and fix common issues.
   

Common Patterns

• Asset Management Use livewire:doctor:scan --assets to flag missing @js, @vite, or @push directives. Fix with:

  php artisan livewire:doctor:fix --assets
  

• Property Validation Detect public properties not declared in $rules or $listen:

  php artisan livewire:doctor:scan --properties
  

• Component Dependencies Check for orphaned components (unused or circular dependencies):

  php artisan livewire:doctor:scan --components
  

Integration Tips

• Laravel Forge Add a cron job to run weekly scans:

  * * * * * cd /path/to/project && php artisan livewire:doctor:scan --quiet --email=team@example.com
  

• Laravel Telescope Extend Telescope to log LivewireDoctor findings:

  LivewireDoctor::extend(function ($report) {
      Telescope::logs()->create([
          'message' => 'LivewireDoctor: ' . $report->summary(),
          'level' => 'info',
      ]);
  });
  

• Custom Rules Extend the scanner in app/Providers/LivewireDoctorServiceProvider.php:

  LivewireDoctor::extend(function ($scanner) {
      $scanner->addRule(new class implements LivewireDoctorRule {
          public function check(Component $component) {
              // Custom logic (e.g., check for deprecated methods)
          }
      });
  });
  

Gotchas and Tips

Common Pitfalls

1. False Positives

   • Issue: The scanner flags @js directives in Blade files that are dynamically generated (e.g., via JavaScript).
   • Fix: Exclude paths in config/livewire-doctor.php:

     'excluded_paths' => [
         'resources/views/vendor/*',
     ],
     

2. Overzealous Fixes

   • Issue: livewire:doctor:fix may overwrite manual changes (e.g., custom property names).
   • Fix: Run in dry mode first:

     php artisan livewire:doctor:fix --dry-run
     

3. Performance

   • Issue: Large projects may slow down during scans.
   • Fix: Limit scope:

     php artisan livewire:doctor:scan --path=app/Http/Livewire/Admin
     

4. Vite/Laravel Mix Conflicts

   • Issue: @vite directives are misinterpreted if Vite is misconfigured.
   • Fix: Ensure vite.config.js includes Livewire assets:

     export default defineConfig({
         build: {
             assetsDir: 'assets',
             manifest: true,
         },
         plugins: [
             laravel({
                 input: ['resources/js/app.js', 'resources/css/app.css'],
                 refresh: true,
             }),
         ],
     });
     

Debugging Tips

• Verbose Output Enable debug mode for detailed logs:

  php artisan livewire:doctor:scan --verbose
  

• Custom Log Path Override the log path in .env:

  LIVEWIREDOC_LOG_PATH=storage/logs/livewire-custom.log
  

• Rule-Specific Debugging Isolate rule failures:

  php artisan livewire:doctor:scan --rule=assets
  php artisan livewire:doctor:scan --rule=properties
  

Extension Points

1. Custom Rules Implement Devrabiul\LivewireDoctor\Contracts\LivewireDoctorRule:

   namespace App\Rules;
   
   use Devrabiul\LivewireDoctor\Contracts\LivewireDoctorRule;
   use Livewire\Component;
   
   class CustomRule implements LivewireDoctorRule {
       public function check(Component $component) {
           if ($component->hasMethod('deprecatedMethod')) {
               return 'Method `deprecatedMethod` is obsolete. Use `newMethod` instead.';
           }
           return null;
       }
   }
   

   Register in LivewireDoctorServiceProvider:

   LivewireDoctor::addRule(new \App\Rules\CustomRule());
   

2. Post-Scan Hooks Listen to scan events:

   LivewireDoctor::listen('scanned', function ($report) {
       // Send Slack notification, update database, etc.
   });
   

3. Fix Customization Override fix logic for specific rules:

   LivewireDoctor::extendFixes(function ($fixer) {
       $fixer->on('missing_asset', function ($component, $asset) {
           // Custom fix logic (e.g., prepend a namespace)
           return "@js({...})";
       });
   });
   

Configuration Quirks

• Excluding Directories Use glob patterns in config/livewire-doctor.php:

  'excluded_paths' => [
      'app/Http/Livewire/Tests/*',
      'vendor/*',
  ],
  

• Case Sensitivity The scanner respects filesystem case sensitivity. On Linux/macOS, ensure component names match exactly (e.g., UserProfile vs userprofile).

• Livewire 3 Migration If using Livewire 3, set:

  'livewire_version' => '3',
  

  in the config to avoid false positives for v2-specific rules.