Laravel Toasts Laravel Package

## Getting Started

### Minimal Setup
1. **Install via Composer**:
   ```bash
   composer require islamalsayed/laravel-toasts

2. Publish assets (if customizing):

   php artisan vendor:publish --provider="IslamAlsayed\LaravelToasts\LaravelToastsServiceProvider" --tag="toasts-assets"
   

3. Publish config (optional, for customization):

   php artisan vendor:publish --provider="IslamAlsayed\LaravelToasts\LaravelToastsServiceProvider" --tag="toasts-config"
   

4. Include the JS in your layout (automatically loaded via service provider by default):

   @toastsScripts
   

First Use Case: Basic Toast

Blade Template:

@toast('Success!', 'Your action was completed.', 'success')

Livewire Component:

use IslamAlsayed\LaravelToasts\Facades\Toast;

public function save()
{
    // ...
    Toast::success('Success!', 'Your action was completed.');
}

Implementation Patterns

Core Workflows

1. Standard Toasts

• Blade Macro:

  @toast('Title', 'Message', 'type', ['position' => 'top-right'])
  

  Types: success, error, danger, warning, info.

• Facade Usage:

  Toast::info('Info Title', 'Info message', ['duration' => 5000]);
  

2. Message-Only Toasts

@toast('Message-only content', null, 'warning', ['mode' => 'message-only'])

Toast::warning('Message-only content', null, ['mode' => 'message-only']);

3. Livewire Integration

Dispatching from Livewire:

use IslamAlsayed\LaravelToasts\Facades\Toast;

public function deleteItem()
{
    // ...
    Toast::dispatch('Item deleted', 'The item was removed successfully.', 'success');
}

Listening in Livewire:

protected $listeners = ['toast' => 'handleToast'];

public function handleToast($message, $title, $type)
{
    Toast::make($title, $message, $type);
}

4. Confirmation Dialogs

@confirm('Delete Item?', 'Are you sure you want to delete this item?', 'deleteItem')

Toast::confirm('Delete?', 'This action cannot be undone.', 'deleteItem');

5. Custom Icons/Emojis

@toast('Custom Icon', 'Message with 🚀 emoji.', 'success', ['icon' => '🚀'])

Toast::success('Custom Icon', 'Message with <i class="fas fa-rocket"></i> icon.', [
    'icon' => '<i class="fas fa-rocket"></i>'
]);

6. Pinned Toasts

Toast::info('Important Notice', 'This will not auto-dismiss.', ['pinned' => true]);

7. Action Buttons

Toast::success('Action Required', 'Click to retry.', [
    'actions' => [
        ['text' => 'Retry', 'callback' => 'retryAction']
    ]
]);

8. JavaScript API (Client-Side)

// Trigger from JS
LaravelToast.success('JS Toast', 'Triggered via JavaScript API.');

// Listen for events
document.addEventListener('toast:show', (e) => {
    console.log('Toast shown:', e.detail);
});

Integration Tips

Blade Directives

• Use @toast and @confirm in Blade templates for quick, declarative notifications.
• Pass arrays as the 4th parameter for advanced options (e.g., ['position' => 'bottom-left', 'duration' => 3000]).

Livewire Best Practices

• Dispatch from Livewire methods to ensure toasts appear after state updates.
• Listen for toasts in parent components if using nested Livewire.
• Use Toast::dispatch() for cross-component communication.

Asset Customization

• Publish assets to override default CSS/JS:

  php artisan vendor:publish --tag="toasts-assets"
  

• Modify resources/css/toasts.css and recompile assets if needed.

RTL/LTR Handling

• The package auto-detects RTL/LTR based on the page direction.
• For Arabic content, ensure your Blade templates use {{ __('messages.key') }} or similar for translation.

Configuration

• Publish the config file to customize:

  php artisan vendor:publish --tag="toasts-config"
  

• Adjust defaults like default_duration, positions, or icons.

Gotchas and Tips

Pitfalls

1. Livewire Event Conflicts:

   • If using Toast::dispatch(), ensure the event name (toast) doesn’t conflict with other Livewire events.
   • Fix: Use a unique event name or namespace:

     Toast::dispatch('my-app.toast');
     

2. Asset Loading Issues:

   • If toasts don’t appear, verify @toastsScripts is included in your layout.
   • Fix: Manually include the JS:

     <script src="{{ asset('vendor/laravel-toasts/js/toasts.js') }}"></script>
     

3. RTL Styling Glitches:

   • Arabic text might misalign if custom CSS overrides default RTL styles.
   • Fix: Inspect the toast container and ensure direction: rtl is applied to the correct elements.

4. Pinned Toast Z-Index:

   • Pinned toasts might be hidden behind other elements.
   • Fix: Adjust the z-index in the published CSS:

     .toast.pinned {
         z-index: 99999 !important;
     }
     

5. Livewire Hydration Conflicts:

   • Toasts triggered during Livewire hydration might not render.
   • Fix: Use wire:ignore on the toast container or trigger toasts after hydration:

     protected $listeners = ['toast' => 'handleToast' => self::ignoreSelf()];
     
     public function mount()
     {
         $this->dispatch('toast', data: ['title' => 'Mounted', 'message' => 'Ready.']);
     }
     

Debugging

1. Check Console for Errors:

   • Open browser dev tools (F12) and look for JS errors related to LaravelToast.

2. Verify Toast Events:

   • Listen for toast:show events in JS to debug payloads:

     document.addEventListener('toast:show', (e) => console.log(e.detail));
     

3. Inspect Network Requests:

   • Ensure Livewire events are firing correctly (look for laravel-toasts in the Network tab).

4. Test in Isolation:

   • Create a minimal Blade template with just the toast directive to rule out conflicts:

     @toast('Test', 'Is this working?', 'success')
     

Tips

1. Dynamic Toast Content:

   • Use Blade variables in toasts:

     @toast("{{ $user->name }}", 'Profile updated successfully.', 'success')
     

2. Conditional Toasts:

   • Show toasts based on logic:

     if ($this->success) {
         Toast::success('Operation completed', 'Check your inbox.');
     }
     

3. Custom Toast Templates:

   • Extend the toast template by publishing assets and overriding the Blade view:

     php artisan vendor:publish --tag="toasts-views"
     

   • Modify resources/views/vendor/toasts/toast.blade.php.

4. Localization:

   • Translate toast messages using Laravel’s translation system:

     @toast(__('toasts.success.title'), __('toasts.success.message'), 'success')
     

5. Performance:

   • For frequent toasts (e.g., real-time updates), batch them or use a queue:

     Toast::queue('New message', 'Content here.', 'info');
     

6. Dark Mode Support:

   • Customize the CSS for dark mode by targeting .dark classes:

     .dark .toast {
         background-color: #333;
         color: #fff;
     }
     

7. Accessibility:

   • Ensure toasts are ARIA-compliant by adding role="alert" to the toast container:

     <div class="toast" role="alert" aria-live="assertive">
     

8. Testing:

   • Test toasts in PHPUnit