Flare Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require alizharb/flare
   npm install @alizharb/flare
   

   Publish assets (if customizing):

   npm run dev
   

2. Register the Livewire Component Add to your Livewire component:

   use AlizHarb\Flare\Facades\Flare;
   
   public function mount() {
       Flare::init();
   }
   

3. First Toast Trigger a notification in a Livewire method:

   public function createUser() {
       Flare::success('User created successfully!');
       // or: Flare::error('Failed to create user.');
   }
   

Where to Look First

• Documentation: GitHub README for API reference and examples.
• Themes: /resources/views/vendor/flare/ for built-in themes (default, dark, and gradient).
• Blade Directive: @flare for rendering toasts in Blade views.

First Use Case

Replace session()->flash() or manual JavaScript alerts with Flare in a Livewire form submission:

public function submitForm() {
    if ($this->validate()) {
        Flare::success('Form submitted!');
        // Proceed with logic...
    } else {
        Flare::error('Validation failed.');
    }
}

Implementation Patterns

Core Workflows

1. Livewire Integration

   • Initialize Flare in mount() to ensure toasts persist across component updates.
   • Use Flare::queue() to defer notifications (e.g., after AJAX calls):

     public function asyncAction() {
         $this->dispatch('flare:queue', type: 'success', message: 'Async task started');
     }
     

2. Real-Time Updates

   • Pair with Laravel Echo/Pusher for server-sent toasts:

     // In a Livewire component
     public function broadcastToast() {
         broadcast(new ToastBroadcast('New message!'))->toOthers();
     }
     

3. Theming

   • Override themes by publishing assets:

     php artisan vendor:publish --tag=flare-themes
     

   • Customize via CSS variables (e.g., --flare-primary in /resources/css/flare.css).

4. Conditional Toasts

   • Use Flare::when() for dynamic triggers:

     Flare::when($user->saved, 'success', 'User saved!')
         ->when($user->errors, 'error', 'Validation failed');
     

Integration Tips

• Livewire Actions: Dispatch toasts from non-Livewire contexts (e.g., Blade buttons):

  <button wire:click="$emit('flare:queue', {type: 'info', message: 'Action triggered'})">
      Click Me
  </button>
  

• Validation Feedback: Replace addError() with Flare for user-friendly messages:

  $this->validate([
      'email' => 'required|email',
  ], [
      'email.required' => Flare::error('Email is required!'),
  ]);
  

• Queue Notifications: For background jobs, use Flare::queue() with a job:

  public function process() {
      Flare::queue('Processing started...');
      // Job logic...
      Flare::queue('Processing complete!');
  }
  

Gotchas and Tips

Pitfalls

1. Toast Persistence

   • Toasts may disappear on Livewire component refresh if not initialized in mount(). Always call Flare::init() early.
   • Fix: Use Flare::persist() for critical notifications:

     Flare::success('Critical alert')->persist();
     

2. Theme Conflicts

   • Custom CSS may override Flare’s styles. Scope your styles to avoid collisions:

     .flare-custom { /* Target only Flare elements */
         --flare-bg: #333;
     }
     

3. Real-Time Lag

   • Server-sent toasts (via broadcasts) may delay if Pusher/Laravel Echo is misconfigured.
   • Debug: Check browser console for ECHO_START events and network tab for WebSocket activity.

4. Duplicate Toasts

   • Rapid Flare::queue() calls may stack notifications. Use Flare::clear() to reset:

     Flare::clear()->success('New notification');
     

Debugging

• Inspect Queue: Log queued toasts in app/Providers/AppServiceProvider:

  Flare::onQueue(function ($type, $message) {
      \Log::debug("Flare queued: [$type] $message");
  });
  

• Check Assets: Ensure @alizharb/flare is included in resources/js/app.js:

  import '@alizharb/flare';
  

Extension Points

1. Custom Toast Types Extend the Toast class to add icons/actions:

   Flare::extend('custom', function ($message) {
       return Flare::toast($message)
           ->icon('⚡')
           ->action('Dismiss', 'flare:dismiss');
   });
   

2. Database Storage Store toasts in a database for persistence across sessions:

   Flare::useStorage(app(\AlizHarb\Flare\Storage\DatabaseStorage::class));
   

3. Localization Override messages in config/flare.php:

   'messages' => [
       'success' => [
           'default' => 'Operation completed!',
           'en' => 'Success!',
           'es' => '¡Éxito!',
       ],
   ],
   

4. Accessibility Ensure ARIA attributes are present. Extend the Toast class:

   Flare::extend('a11y', function ($message) {
       return Flare::toast($message)
           ->attr('role', 'alert')
           ->attr('aria-live', 'polite');
   });