Laravel Livewire4 Toaster Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require haxneeraj/laravel-livewire4-toaster
   

2. Publish config (optional):

   php artisan vendor:publish --provider="Haxneeraj\Livewire4Toaster\Livewire4ToasterServiceProvider"
   

3. Add Alpine directive to your main layout (e.g., resources/views/layouts/app.blade.php):

   <script>
       document.addEventListener('alpine:init', () => {
           Alpine.data('toaster', () => ({
               toasts: [],
               // ... (see README for full Alpine script)
           }));
       });
   </script>
   

4. First toast in a Livewire component:

   use Haxneeraj\Livewire4Toaster\Traits\HasToaster;
   
   class MyComponent extends Component {
       use HasToaster;
   
       public function save() {
           $this->success('Data saved successfully!');
       }
   }
   

First Use Case

Trigger a toast from a Livewire component method:

public function deleteItem() {
    try {
        $this->delete($item);
        $this->success('Item deleted!', ['position' => 'top-right']);
    } catch (\Exception $e) {
        $this->error('Failed to delete: ' . $e->getMessage());
    }
}

Implementation Patterns

Core Workflows

1. Component Integration:

   • Use the HasToaster trait in any Livewire component for method-based toasts (success(), error(), etc.).
   • Example:

     class UserProfile extends Component {
         use HasToaster;
     
         public function updateProfile() {
             if ($this->validate()) {
                 $this->success('Profile updated!', [
                     'duration' => 5000,
                     'queue' => true,
                 ]);
             }
         }
     }
     

2. Controller/Service Layer:

   • Use the facade (Toast::info('Message')) or helper (toast('warning', 'Message')) for non-Livewire contexts.
   • Example in a controller:

     use Haxneeraj\Livewire4Toaster\Facades\Toast;
     
     public function store(Request $request) {
         $validated = $request->validate([...]);
         Toast::success('Resource created!', ['position' => 'bottom-left']);
         return redirect()->back();
     }
     

3. Event-Driven Dispatch:

   • Dispatch toasts from anywhere using Livewire’s dispatch():

     $this->dispatch('toast', type: 'success', message: 'Event-triggered toast!');
     

   • Listen in Alpine:

     x-on:toast.window="toaster.addToast($event.detail.type, $event.detail.message)"
     

4. Queue Management:

   • Enable queue mode to prevent toast overlap:

     $this->info('Processing...', ['queue' => true]);
     $this->warning('Next step', ['queue' => true]);
     

   • Configure default queue behavior in config/livewire4-toaster.php:

     'queue' => [
         'enabled' => true,
         'max_at_once' => 1,
     ],
     

5. Dynamic Toasts:

   • Pass variables or closures for dynamic content:

     $this->success('User <strong>' . $user->name . '</strong> created.', [
         'html' => true,
     ]);
     

Integration Tips

• Blade Integration: Include the Alpine script in your root layout or a shared partial:

  @livewireScripts
  @stack('scripts')
  <script src="{{ asset('js/livewire4-toaster.js') }}"></script>
  

• Tailwind/CSS Customization: Extend the default styles by overriding Alpine’s toaster data:

  Alpine.data('toaster', () => ({
      // Override default classes
      toastClasses: {
          success: 'bg-green-500 text-white',
          error: 'bg-red-500 text-white',
          // ...
      }
  }));
  

• Livewire 4 Compatibility: Ensure your Livewire components extend Livewire\Component (not Livewire\Livewire). For older Livewire 3 components, use the livewire:ignore directive on the Alpine script.

Gotchas and Tips

Pitfalls

1. Alpine Initialization:

   • Issue: Toasts not appearing.
   • Fix: Ensure the Alpine toaster script runs after Livewire’s Alpine initialization. Wrap it in alpine:init or place it in a @stack('scripts') section loaded last.
   • Debug: Check browser console for Alpine is not defined errors.

2. Duplicate Toasts:

   • Issue: Identical toasts stack when duplicate: 'suppress' is set.
   • Fix: Use duplicate: 'replace' to overwrite duplicates or adjust the duplicateCheck duration in config:

     'duplicate' => [
         'check' => 1000, // Check for duplicates every 1 second
         'method' => 'suppress',
     ],
     

3. Queue Conflicts:

   • Issue: Toasts in queue mode disappear unexpectedly.
   • Fix: Ensure max_at_once in config matches your use case (e.g., max_at_once: 3 for 3 concurrent toasts).

4. Livewire 4 dispatch():

   • Issue: Toasts not triggering via dispatch().
   • Fix: Verify the event name matches exactly (toast in this package). Example:

     $this->dispatch('toast', type: 'info', message: 'Hello!');
     

5. CSS Conflicts:

   • Issue: Toasts inherit unwanted styles (e.g., from Tailwind).
   • Fix: Use !important in Alpine’s toastClasses or scope styles with a unique class:

     toastClasses: {
         container: 'livewire-toaster-container',
         toast: 'livewire-toaster',
     }
     

     Then add CSS:

     .livewire-toaster-container { position: fixed; z-index: 9999; }
     

Debugging

• Log Dispatch Events: Add a temporary listener to debug dispatched events:

  window.addEventListener('toast', (e) => {
      console.log('Toast event:', e.detail);
  });
  

• Check Config: Validate config/livewire4-toaster.php for typos or incorrect paths (e.g., position values must match Alpine’s logic).

Extension Points

1. Custom Toast Types: Add new toast types by extending Alpine’s toaster data:

   Alpine.data('toaster', () => ({
       toastTypes: {
           ...defaultTypes,
           custom: {
               icon: '✨',
               classes: 'bg-purple-500',
           },
       },
   }));
   

   Then use in PHP:

   $this->toast('custom', 'This is a custom toast!');
   

2. Progress Bar Customization: Override the progress bar template in Alpine:

   progressBarTemplate: `
       <div class="w-full h-1 bg-blue-500 transition-all"></div>
   `,
   

3. Server-Side Logic: Extend the trait to add component-specific logic:

   use Haxneeraj\Livewire4Toaster\Traits\HasToaster;
   
   class MyComponent extends Component {
       use HasToaster {
           HasToaster::toast as private __toast;
       }
   
       public function toast($type, $message, $options = []) {
           $options['position'] = 'bottom-right'; // Force position
           return $this->__toast($type, $message, $options);
       }
   }
   

4. Testing: Mock toasts in PHPUnit:

   $component->expectsToDispatch('toast')
       ->with(['type' => 'success', 'message' => 'Test']);
   $component->success('Test');
   

Config Quirks

• Position Values: Must match Alpine’s logic (top-right, top-left, bottom-right, bottom-left). Custom positions require Alpine updates.
• Duration Units: Values in config are in milliseconds (e.g., 5000 = 5 seconds).
• Queue Behavior: Setting queue: true globally in config affects all toasts unless overridden per-call.