Flasher Livewire Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require php-flasher/flasher-livewire
   

   Publish the config (optional):

   php artisan vendor:publish --provider="PHPFlasher\FlasherLivewire\FlasherLivewireServiceProvider"
   

2. First Use Case: Trigger a flash message in a Livewire component:

   use PHPFlasher\FlasherLivewire\Facades\Flasher;
   
   public function save()
   {
       // Trigger a success flash message
       Flasher::success('Your data has been saved!');
   
       // Redirect or return to a Livewire component
       return redirect()->route('your.route');
   }
   

3. Displaying Flash Messages: Add the Flasher component to your Livewire component's view:

   <livewire:flasher />
   

Key Files to Review

• config/flasher.php: Customize default flash message types (success, error, etc.).
• resources/views/vendor/flasher-livewire/flasher.blade.php: Override default UI.

Implementation Patterns

Core Workflows

1. Triggering Flash Messages:

   • Use Flasher::success(), Flasher::error(), etc., in Livewire component methods or controllers.
   • Pass additional data (e.g., icons, duration):

     Flasher::success('Saved!', [
         'icon' => 'check-circle',
         'duration' => 5000,
     ]);
     

2. Conditional Flashing:

   • Check if a flash message exists before displaying:

     if (Flasher::has('success')) {
         Flasher::success()->getMessage();
     }
     

3. Livewire Component Integration:

   • Extend the Flasher component to customize behavior:

     use PHPFlasher\FlasherLivewire\Flasher;
     
     class CustomFlasher extends Flasher
     {
         public function render()
         {
             return view('livewire.custom-flasher');
         }
     }
     

4. Queueing Flash Messages:

   • Store flash messages in the session and retrieve them in Livewire components:

     // In a controller or Livewire component
     session()->flash('flasher', ['type' => 'success', 'message' => 'Hello!']);
     
     // In Livewire component
     public function mount()
     {
         if (session()->has('flasher')) {
             $this->flash = session('flasher');
         }
     }
     

Integration Tips

• Livewire Redirects: Ensure flash messages persist after redirects by using redirect()->with() or session()->flash().

  return redirect()->route('dashboard')->with('flasher', ['type' => 'success', 'message' => 'Done!']);
  

• Custom Flash Types: Extend the Flasher facade to support custom types:

  Flasher::extend('warning', function ($message, $options = []) {
      return ['type' => 'warning', 'message' => $message, ...$options];
  });
  

• Testing: Mock the Flasher facade in tests:

  $this->mock(Flasher::class)->shouldReceive('success')->once()->with('Test message');
  

Gotchas and Tips

Common Pitfalls

1. Session Binding:

   • Flash messages rely on the session. Ensure your Livewire components are bound to the session (default behavior).
   • If using wire:ignore, flash messages may not render. Wrap the Flasher component in wire:key:

     <div wire:key="flasher-{{ now() }}">
         <livewire:flasher />
     </div>
     

2. Duplicate Messages:

   • Flash messages are stored in the session and cleared after retrieval. If a message appears multiple times, check for:
     • Multiple livewire:flasher components in the view.
     • Session data not being cleared properly (e.g., due to middleware or custom session drivers).

3. Livewire Component Lifecycle:

   • Flash messages may not persist if the Livewire component re-renders before the session is read. Use mount() or hydrate() to ensure messages are captured:

     public function mount()
     {
         $this->flash = session('flasher');
         session()->forget('flasher');
     }
     

4. CSRF and Middleware:

   • If flash messages disappear after authentication (e.g., login), ensure the flasher session key is preserved across middleware. Use session()->reflash() or session()->put('flasher', session('flasher')) in middleware.

Debugging Tips

• Check Session Data: Dump the session to verify flash messages are stored:

  dd(session()->all());
  

• Override Views: Debug UI issues by overriding the default view (resources/views/vendor/flasher-livewire/flasher.blade.php).

• Clear Cached Views: If changes to the flasher view aren’t reflected, clear the view cache:

  php artisan view:clear
  

Extension Points

1. Custom Flash Drivers: Extend the Flasher class to support alternative storage (e.g., database, cache):

   use PHPFlasher\FlasherLivewire\Contracts\FlasherContract;
   
   class DatabaseFlasher implements FlasherContract
   {
       public function success($message, $options = [])
       {
           // Custom logic to store in database
       }
   }
   

2. Livewire Events: Trigger flash messages via Livewire events:

   // In a Livewire component
   $this->dispatch('flash-success', message: 'Event triggered!');
   
   // In another component or blade view
   <script>
       window.addEventListener('flash-success', (e) => {
           @this.call('triggerFlasher', e.detail.message, 'success');
       });
   </script>
   

3. Localization: Localize flash messages by extending the Flasher facade:

   Flasher::setLocale('es');
   Flasher::success('¡Mensaje guardado!');
   

4. Animation: Add animations by customizing the flasher.blade.php view:

   <div x-data="{ show: true }" x-show="show" x-transition
        x-init="setTimeout(() => show = false, 3000)"
        class="transition-opacity duration-300">
       {{ $message }}
   </div>