Getting Started

Minimal Steps

Installation:

composer require devrabiul/laravel-toaster-magic
php artisan vendor:publish --provider="Devrabiul\ToastMagic\ToastMagicServiceProvider"

(Assets auto-publish on first page load.)

Add to Blade:

<head>
    {!! ToastMagic::styles() !!}
</head>
<body>
    {!! ToastMagic::scripts() !!}
</body>

First Toast:

use Devrabiul\ToastMagic\Facades\ToastMagic;
ToastMagic::success('Success!', 'Your action was completed.');

Where to Look First

Config: config/laravel-toaster-magic.php (position, theme, Livewire settings).
Facade: Devrabiul\ToastMagic\Facades\ToastMagic (core API).
Livewire: this->dispatch('toastMagic', [...]) (event-based usage).

First Use Case

Trigger a success toast after a form submission in a controller:

public function store(Request $request) {
    $request->validate([...]);
    ToastMagic::success('Saved!', 'Your data is now stored.');
    return back();
}

Implementation Patterns

Core Workflows

Controller Integration:

// Static method (quick)
ToastMagic::warning('Warning!', 'Check your inputs.', ['timeOut' => 8000]);

// Fluent method (customizable)
ToastMagic::dispatch()
    ->error('Failed', 'Something went wrong.')
    ->withOptions(['theme' => 'neon', 'positionClass' => 'toast-bottom-end']);

Livewire Integration:

// Component method
public function createUser() {
    $this->validate([...]);
    $this->dispatch('toastMagic', [
        'status' => 'success',
        'title' => 'User Created',
        'message' => 'Profile saved.',
        'options' => ['customBtnText' => 'View', 'customBtnLink' => route('profile')],
    ]);
}

JavaScript Integration:

const toast = new ToastMagic();
toast.info('Update Available', 'New version ready.', false, 'Download', '/update');

Integration Tips

Theme Consistency: Set a default theme in config and override per-toast if needed:
```
ToastMagic::success('...', '...', ['theme' => 'glassmorphism']);
```

Positioning: Use positionClass for dynamic layouts (e.g., mobile vs. desktop):

if (request()->isMobile()) {
    ToastMagic::setOption('positionClass', 'toast-bottom-start');
}

Livewire Events: Listen globally in a Livewire component:

protected $listeners = ['toastMagic' => 'handleToast'];
public function handleToast($event) {
    $this->dispatchBrowserEvent('toastMagic', $event);
}

Validation Feedback: Chain toasts with validation errors:

if ($errors->any()) {
    foreach ($errors->all() as $error) {
        ToastMagic::error('Validation Error', $error);
    }
}

Gotchas and Tips

Pitfalls

XSS Risks:
- Gotcha: Custom button links (customBtnLink) are sanitized to prevent javascript: injection.
- Fix: Only http://, https://, /, or # URLs are allowed. Invalid links default to #.
Livewire Version Mismatch:
- Gotcha: Livewire v3/v4 dispatch syntax differs slightly. Ensure livewire_version in config matches your project.
- Fix: Test in a component first:
```
$this->dispatch('toastMagic', ['status' => 'info']);
```
Caching Issues:
- Gotcha: php artisan migrate may fail if CACHE_DRIVER=database and the cache table doesn’t exist.
- Fix: The package now gracefully falls back to non-cached computation during migrations.
Message Truncation:
- Gotcha: rtrim() was corrupting messages with <br> tags (e.g., "error" → "err").
- Fix: Updated to preg_replace('/(<br>)+$/', '', $string) in all toast methods.

Debugging

Toast Not Showing?:
- Verify ToastMagic::styles() and ToastMagic::scripts() are in <head>/</body>.
- Check browser console for JS errors (e.g., missing Livewire JS).
- Ensure no ad-blockers are blocking the toast container.
Livewire Not Working:
- Confirm livewire_enabled: true in config.
- Check Livewire version (v3 or v4) matches your project.
- Listen for events in a component:
```
protected $listeners = ['toastMagic' => 'showToast'];
public function showToast($event) { dd($event); }
```

Config Quirks

Gradient Mode: Only works with default, material, or neumorphism themes.
Dark Mode: Requires theme="dark" on <body> (not a config option).
Position Classes: Must match Bootstrap toast positions.

Extension Points

Custom Themes:
- Override default themes by publishing assets:
```
php artisan vendor:publish --tag=laravel-toaster-magic-assets --force
```
- Modify resources/views/vendor/toast-magic/themes/ and recompile assets.

Event Listeners:

Extend Livewire events by adding a global listener:

Livewire::listen('toastMagic', function ($event) {
    // Log or modify events
});

Middleware:

Disable toasts for specific routes:

public function handle($request, Closure $next) {
    if (!$request->wantsJson()) {
        app()->singleton(ToastMagic::class, fn() => new class {
            public function __call($method, $args) { return null; }
        });
    }
    return $next($request);
}

Testing:

Mock the facade in PHPUnit:

$this->mock(ToastMagic::class)->shouldReceive('success')->once();

Laravel Toaster Magic Laravel Package