Tail Alert Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require ab01faz101/tail-alert
   

2. Publish the config (optional, but recommended for customization):

   php artisan vendor:publish --provider="Ab01faz101\TailAlert\TailAlertServiceProvider"
   

3. Include the Livewire script in your layout (e.g., resources/views/layouts/app.blade.php):

   @livewireScripts
   @tailalertScripts
   

4. First use case: Trigger an alert in a Livewire component:

   use Ab01faz101\TailAlert\Facades\TailAlert;
   
   public function save()
   {
       TailAlert::success('Data saved successfully!');
       // or
       TailAlert::error('Failed to save data.');
   }
   

Implementation Patterns

Core Workflow

1. Triggering Alerts: Use the TailAlert facade to dispatch alerts from any Livewire component:

   TailAlert::info('This is an informational message.');
   TailAlert::warning('This is a warning message.');
   TailAlert::error('Something went wrong!');
   TailAlert::success('Operation completed successfully.');
   

2. Customizing Alerts: Pass an array for additional options (e.g., duration, position, or custom icon):

   TailAlert::success('Custom alert', [
       'duration' => 5000, // 5 seconds
       'position' => 'top-right',
       'icon' => '✨',
   ]);
   

3. Conditional Alerts: Combine with Livewire's reactivity to show alerts based on state:

   public $showSuccessAlert = false;
   
   public function submitForm()
   {
       if ($this->validate()) {
           $this->showSuccessAlert = true;
           TailAlert::success('Form submitted!');
       } else {
           TailAlert::error('Validation failed.');
       }
   }
   

4. Integration with Livewire Events: Dispatch alerts in response to Livewire events:

   protected $listeners = ['alertTriggered' => 'handleAlert'];
   
   public function handleAlert($message)
   {
       TailAlert::info($message);
   }
   

5. Dynamic Alerts in Blade: Display alerts in your Livewire component's Blade view:

   @if(session()->has('status'))
       @php
           TailAlert::info(session('status'));
       @endphp
   @endif
   

Advanced Patterns

1. Queueing Alerts: Use Livewire's wire:ignore to queue alerts for batch processing:

   <div wire:ignore>
       @foreach($pendingAlerts as $alert)
           {{ $alert }}
       @endforeach
   </div>
   

2. Theming: Override Tailwind classes in the published config (config/tail-alert.php):

   'classes' => [
       'container' => 'max-w-md mx-auto',
       'success' => 'bg-green-500 text-white',
       'error' => 'bg-red-500 text-white',
   ],
   

3. Localization: Extend the package's language support by publishing and modifying the language file:

   php artisan vendor:publish --tag=tail-alert-lang
   

4. Custom Alert Types: Extend the TailAlert facade to support additional types (e.g., TailAlert::custom('Type', 'Message')):

   // In a service provider or helper
   if (!method_exists(\Ab01faz101\TailAlert\Facades\TailAlert::class, 'custom')) {
       \Ab01faz101\TailAlert\Facades\TailAlert::macro('custom', function ($message, $options = []) {
           return $this->dispatch('alert', [
               'type' => 'custom',
               'message' => $message,
               'options' => $options,
           ]);
       });
   }
   

Gotchas and Tips

Common Pitfalls

1. Missing @tailalertScripts: Forgetting to include @tailalertScripts in your layout will result in alerts not rendering. Fix: Ensure the script is included in your main layout file.

2. Alerts Not Showing: If alerts don’t appear, check:

   • The Livewire component is properly mounted.
   • No JavaScript errors are blocking the script.
   • The TailAlert facade is correctly namespaced (use Ab01faz101\TailAlert\Facades\TailAlert;).

3. Conflicting Tailwind Classes: Custom Tailwind classes in the config may conflict with your project’s existing styles. Tip: Use unique class names or inspect the generated HTML to debug.

4. Livewire Component Isolation: Alerts triggered in a child Livewire component may not appear if the parent component’s script isn’t loaded. Fix: Ensure the parent component includes @livewireScripts and @tailalertScripts.

Debugging Tips

1. Check the Network Tab: Look for failed requests or blocked scripts in your browser’s DevTools (Network tab).

2. Inspect Generated HTML: Open the browser’s DevTools (Elements tab) to verify the alert DOM structure is correct.

3. Log Dispatch Events: Add a temporary dd() or Log::debug() to confirm the alert is being dispatched:

   TailAlert::success('Debug message');
   // Check Laravel logs for: "TailAlert dispatched: success"
   

4. Disable Caching: If alerts work in development but not production, clear caches:

   php artisan view:clear
   php artisan cache:clear
   

Extension Points

1. Custom Alert Templates: Override the Blade template by publishing and modifying:

   php artisan vendor:publish --tag=tail-alert-views
   

   Edit resources/views/vendor/tail-alert/alert.blade.php.

2. Add Animation: Extend the package to support animations by modifying the published JS:

   php artisan vendor:publish --tag=tail-alert-scripts
   

   Edit public/vendor/tail-alert/js/tail-alert.js.

3. Server-Side Alerts: Combine with Laravel’s session flash data for alerts that persist across requests:

   session()->flash('status', 'This alert will persist!');
   // In your Livewire component:
   public function mount()
   {
       if (session()->has('status')) {
           TailAlert::info(session('status'));
           session()->forget('status');
       }
   }
   

4. Dark Mode Support: Ensure your Tailwind config supports dark mode and update the alert classes in config/tail-alert.php:

   'classes' => [
       'dark' => 'dark:bg-gray-800 dark:text-white',
   ],