Livewire Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require spiral-packages/livewire
   

   Ensure your composer.json meets the requirements (PHP 8.1+, Spiral 3.7+).

2. Register the Middleware Add the Livewire middleware to your Spiral application’s HTTP pipeline in config/app.php:

   'http' => [
       'middleware' => [
           // ...
           \Spiral\Livewire\Middleware\HandleLivewireRequests::class,
       ],
   ],
   

3. First Livewire Component Create a component class (e.g., app/Components/HelloWorld.php):

   namespace App\Components;
   
   use Spiral\Livewire\Component;
   
   class HelloWorld extends Component
   {
       public string $name = 'World';
   
       public function render()
       {
           return view('livewire.hello-world');
       }
   }
   

   Register it in config/livewire.php:

   'components' => [
       \App\Components\HelloWorld::class,
   ],
   

4. Blade View Create resources/views/livewire/hello-world.blade.php:

   <div>
       <h1>Hello, {{ $name }}!</h1>
       <input wire:model="name" type="text">
   </div>
   

5. Route and Use Add a route in config/routes.php:

   $router->get('/hello', \Spiral\Livewire\Livewire::class)
       ->bind('hello');
   

   Access /hello in your browser.

Key First-Use Cases

• Reactive Forms: Bind inputs to component properties (e.g., wire:model="name").
• Server-Side Logic: Move validation or heavy processing to the component class.
• Real-Time Updates: Use wire:click or wire:change for dynamic interactions without full page reloads.

Implementation Patterns

Component Lifecycle

1. Initialization Override boot() for one-time setup (e.g., fetching initial data):

   public function boot()
   {
       $this->data = Model::query()->first();
   }
   

2. Rules and Validation Use Laravel’s validation rules in rules():

   public function rules()
   {
       return [
           'name' => 'required|min:3',
       ];
   }
   

3. Event Handling Emit events with emit() for client-side JavaScript:

   public function save()
   {
       $this->validate();
       $this->emit('message', 'Saved!');
   }
   

Integration with Spiral

1. Dependency Injection Inject Spiral services into components:

   use Spiral\Core\Container;
   
   public function __construct(
       private Container $container
   ) {}
   
   public function mount()
   {
       $this->data = $this->container->get(MyService::class);
   }
   

2. Middleware and Auth Protect components with Spiral middleware (e.g., auth):

   $router->get('/dashboard', \Spiral\Livewire\Livewire::class)
       ->middleware(\Spiral\Http\Middleware\AuthMiddleware::class);
   

3. Asset Management Use Spiral’s asset pipeline for Livewire scripts/styles:

   // config/livewire.php
   'assets' => [
       'scripts' => [
           'livewire.js',
       ],
   ],
   

Workflows

1. CRUD Operations

   • Fetch data in mount().
   • Update via wire:model and save with a method.
   • Redirect or emit success messages.

2. Modals and Dialogs Use wire:click to toggle visibility and pass data via component properties.

3. Pagination Implement mount() with query parameters and use wire:model.debounce for search.

Gotchas and Tips

Pitfalls

1. Caching Issues

   • Clear Spiral’s cache (php spiral cache:clear) after adding new components.
   • Livewire’s cache is separate; use php artisan livewire:discover if needed.

2. Middleware Conflicts

   • Ensure HandleLivewireRequests is last in the pipeline to avoid premature request termination.

3. PHP 8.1+ Features

   • Use named arguments in wire:model (e.g., wire:model.live="name").
   • Avoid deprecated wire:init; use mount() instead.

Debugging

1. Logs Enable Livewire debug mode in config/livewire.php:

   'debug' => env('APP_DEBUG', false),
   

   Check Spiral logs (storage/logs/) for Livewire errors.

2. Wire:Key Conflicts Ensure wire:key is unique for dynamic components (e.g., <div wire:key="item-{{ $id }}">).

3. CSRF Tokens Spiral’s CSRF middleware must be enabled for Livewire to work. Verify in config/app.php:

   'http' => [
       'middleware' => [
           \Spiral\Http\Middleware\CsrfProtectionMiddleware::class,
       ],
   ],
   

Tips

1. Type Safety Use PHP 8.1+ typed properties and return types:

   public function getName(): string
   {
       return $this->name;
   }
   

2. Testing Test components with Spiral’s HTTP client:

   $response = $this->get('/livewire/hello');
   $response->assertLivewireLoaded('hello-world');
   

3. Performance

   • Lazy-load heavy dependencies in mount().
   • Use wire:ignore for non-reactive elements (e.g., <div wire:ignore>).

4. Extending Spiral Create custom Livewire directives by extending Spiral\Livewire\LivewireServiceProvider.

Extension Points

1. Custom Directives Register in boot():

   Livewire::directive('custom', function ($expression) {
       return "alert('{$expression}')";
   });
   

2. Global JavaScript Add to resources/js/app.js:

   document.addEventListener('livewire:init', () => {
       Livewire.on('message', (message) => alert(message));
   });
   

3. Component Factories Use Spiral’s DI container to resolve components dynamically:

   $component = $this->container->get(\App\Components\HelloWorld::class);