Getting Started

Minimal Setup

Installation:
```
composer require wvandeweyer/tall-flash
```
No additional configuration is required—just use the flash() helper.
First Use Case: In a controller or Livewire component, call:
```
flash()->success('Your action was completed!');
```
This will automatically store the message in the session and display it on the next request.
Livewire Integration: For real-time feedback, chain .livewire($this):
```
flash()->info('Livewire message!')->livewire($this);
```
Ensure your Livewire component listens for the flash event (see Implementation Patterns).
View Integration: Add the flash component to your layout (e.g., resources/views/layouts/app.blade.php):
```
@livewire('flash-notification')
```
The package provides a default Livewire component (FlashNotification) to render messages.

Implementation Patterns

Core Workflows

Controller/Route-Based Flashes: Use flash() in controllers or route closures for session-based messages:

Route::post('/submit', function () {
    flash()->warning('Form submitted!')->important();
    return redirect()->back();
});

Livewire Real-Time Feedback:

Emit Messages: Chain .livewire($this) to trigger client-side updates:

public function updateProfile()
{
    flash()->success('Profile updated!')->livewire($this);
}

Listen for Messages: In your Livewire component, add:

protected $listeners = ['flash'];

public function render()
{
    return view('livewire.your-component');
}

public function flash($message)
{
    // Handle the message (e.g., show a toast)
}

Or use the provided FlashNotification component:

@livewire('flash-notification')

Conditional Flashes: Use methods like .when(), .unless(), or .if() to control message display:
```
if ($user->isActive()) {
    flash()->info('User is active')->when($user->isAdmin());
}
```

Queueing Messages: Chain .queue() to stack multiple messages:

flash()->success('First message')->queue();
flash()->warning('Second message')->queue();

Integration Tips

Custom Views: Override the default Livewire component by publishing assets:
```
php artisan vendor:publish --tag=tall-flash
```
Modify resources/views/vendor/tall-flash/livewire-flash.blade.php.
Session Driver: Ensure your .env uses a supported session driver (e.g., file, database). The package defaults to the Laravel session.

Livewire + Alpine.js: Combine with Alpine.js for dynamic dismissals:

<div x-data="{ show: true }" x-show="show">
    @livewire('flash-notification')
</div>

Testing: Mock flashes in tests using the facade:

$this->partialMock(Flash::class, function ($mock) {
    $mock->shouldReceive('success')->andReturnSelf();
});

Gotchas and Tips

Pitfalls

Livewire Event Scope:
- Flashes emitted via .livewire($this) only work within the same Livewire component instance. If the component re-renders (e.g., due to a form submission), the flash may not persist. Use session flashes for cross-request persistence.
Session Expiration:
- Session flashes rely on Laravel’s session lifetime. If the session expires (e.g., due to SESSION_LIFETIME in .env), messages will vanish. Test with:
```
config(['session.lifetime' => 120]); // 2 minutes
```
Component Registration:
- Forgetting to include @livewire('flash-notification') in your layout will prevent messages from rendering. Verify the component is loaded after your Livewire component mounts.
Method Chaining Order:
- Chaining methods like .livewire() or .queue() must be the last in the chain. Invalid order (e.g., .livewire()->success()) will throw errors.
CSRF Conflicts:
- If using Livewire flashes in API routes or non-CSRF-protected endpoints, ensure the Livewire component’s event listeners are properly scoped to avoid CSRF token mismatches.

Debugging

Check Session Data: Dump the session to verify flashes are stored:

dd(session()->get('flash'));

Expected output:

[
    'messages' => [
        ['type' => 'success', 'message' => 'Your message', 'options' => []],
    ],
]

Livewire Event Logs: Enable Livewire logging to debug event emissions:
```
Livewire::configureLogging();
```
Check storage/logs/livewire.log for emitted events.
Clear Flashes: Manually clear flashes in tests or debugging:
```
session()->forget('flash');
```

Configuration Quirks

Default Types: The package supports success, error, warning, info, and danger. Add custom types by extending the Flash class or publishing the config:
```
php artisan vendor:publish --tag=tall-flash-config
```
Modify config/tall-flash.php to add types like:
```
'types' => [
    'custom' => 'custom-class',
],
```
Livewire Component Alias: The default Livewire component is flash-notification. Rename it in config/tall-flash.php if needed:
```
'livewire_component' => 'custom-flash',
```

Auto-Dismiss: Enable auto-dismiss for Livewire flashes by setting:

flash()->info('Auto-dismiss in 5s')->livewire($this)->autoDismiss(5000);

Extension Points

Custom Flash Classes: Create a decorator to extend functionality:

use Wvandeweyer\TallFlash\Flash;

class CustomFlash extends Flash
{
    public function customMethod()
    {
        $this->addOption('custom', true);
        return $this;
    }
}

Bind it in AppServiceProvider:

Flash::swap(CustomFlash::class);

Override Livewire Component: Publish and modify the Livewire component to add features like:
- Dark mode support.
- Animation libraries (e.g., Tailwind transitions).
- Persistent storage for dismissed messages.
Queue Integration: Extend the queue() method to support database queues or third-party services:
```
public function queue()
{
    // Custom logic (e.g., push to Redis)
    return $this;
}
```
Localization: Extend the package to support localized messages by overriding the message property in your decorator:
```
public function __construct($message = null)
{
    parent::__construct(__($message));
}
```

Tall Flash Laravel Package