Alert Laravel Package

Getting Started

vinkla/alert is a thin session-flash wrapper that renders Bootstrap alert markup. Treat it as a convenience helper rather than infrastructure — everything it does can be reproduced with session()->flash() and a Blade partial.

Install

composer require vinkla/alert

On Laravel 5.5+ package discovery registers Vinkla\Alert\AlertServiceProvider and the Alert facade automatically. On older versions add them to config/app.php:

Vinkla\Alert\AlertServiceProvider::class,

'Alert' => Vinkla\Alert\Facades\Alert::class,

Publish config/views

php artisan vendor:publish --provider="Vinkla\Alert\AlertServiceProvider"

Where to look first

1. config/alert.php — controls which view/markup flavor is rendered. Confirm whether it targets Bootstrap 3 or 4, because that determines whether you need to override the view.
2. vendor/vinkla/alert/resources/views/ — the actual alert partial. This is the single most important file: it tells you the exact HTML, the close-button attributes, and whether the message is escaped.
3. src/Alert.php — the flash key used in the session and the list of level methods. Check this before writing test assertions.

First use case — flash a message before a redirect (Post/Redirect/Get):

use Vinkla\Alert\Facades\Alert;

public function store(StoreInvoiceRequest $request)
{
    Invoice::create($request->validated());

    Alert::success('Invoice saved.');

    return redirect()->route('invoices.index');
}

Then render it once, in your layout:

{{-- resources/views/layouts/app.blade.php --}}
@include('alert::bootstrap')

That single include covers every page, which is the intended workflow.

Implementation Patterns

Global layout include. Put the include above your @yield('content') or immediately after the navbar. Rendering per-page is the most common cause of "the alert never shows up" — the partial must be present in the first view after the redirect, not a later one.

Facade vs. helper. Both are equivalent; pick one and stay consistent. The facade is clearer in service classes and easier to fake in tests:

Alert::success('Saved.');
Alert::error('Payment declined.');
alert()->info('Heads up.');   // global helper, if the package registers one

Custom levels. Useful for Bootstrap's other contextual classes (primary, secondary, dark). Verify the method signature in src/Alert.php; typically it is a generic message($text, $level) alongside the four named helpers.

Validation errors stay separate. Do not push $errors through the alert helper. Laravel's $errors bag is already shared on redirect; mixing the two means you lose @error directives and old() repopulation. Use alerts for outcome messages, $errors for field messages.

Service-layer usage. Because it is session-backed, only call it from HTTP-adjacent code (controllers, form requests, actions invoked by a controller). Wrapping it behind an interface is worthwhile if you plan to replace it:

interface Notifier {
    public function success(string $message): void;
}

class FlashNotifier implements Notifier
{
    public function success(string $message): void
    {
        Alert::success($message);
    }
}

Multiple messages. If you need to stack alerts on one page, confirm whether the underlying implementation flashes a single array or an array of arrays. If single, either collapse to one message or bypass the helper:

session()->flash('alerts', [
    ['level' => 'success', 'message' => 'Saved.'],
    ['level' => 'warning', 'message' => 'Quota at 90%.'],
]);

JSON / Inertia / Livewire. Session flashes do not appear in JSON responses. For XHR endpoints, return the message in the payload and let the front end render it. Inertia shares flashes through HandleInertiaRequests, but only if the flash key survives — verify against the package's key. Livewire components re-render without a redirect, so a session()->flash() inside a component will not surface until the next full request; dispatch a browser event instead.

Testing. Assert on the session immediately after the action, before following the redirect:

$response = $this->post('/invoices', $payload);

$response->assertRedirect('/invoices');
$response->assertSessionHas('alert'); // confirm the exact key in src/Alert.php

Gotchas and Tips

It is archived. Last release was February 2019, so its illuminate/support constraint almost certainly stops at Laravel 5.x/6.x. On Laravel 9+ Composer will refuse to install it. Your options, in order: (1) don't add it to new projects, (2) fork and widen the constraint — the code surface is tiny, so this is realistic, (3) replace it.

Replacement is ten lines. If you inherit a codebase using it, migrating away is cheap:

session()->flash('alert', ['level' => 'success', 'message' => 'Invoice saved.']);

@if (session('alert'))
    <div class="alert alert-{{ session('alert.level') }} alert-dismissible fade show" role="alert">
        {{ session('alert.message') }}
        <button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="Close"></button>
    </div>
@endif

Bootstrap 5 markup. The package predates Bootstrap 5. Its close button will use data-dismiss (v3/v4) rather than data-bs-dismiss (v5), and btn-close instead of the close/× pattern. Result: alerts render but cannot be dismissed. Fix by publishing and overriding the view, or by swapping the include for your own partial.

Single-alert overwrite. Most implementations of this style store one flash payload, so Alert::success('A') followed by Alert::error('B') means the user only ever sees B. Verify before relying on stacking.

Session and middleware. Alerts need a started session. Controller actions on api routes, or anything outside the web group, silently drop them. The same applies to queued jobs and console commands.

Flash lifetime is one request. If your redirect chain has an extra hop, or an intermediate route redirects again, the alert is consumed before the user sees it. The partial must live in the layout that renders the final response.

Escaping. Read the package view to see whether it emits {{ $message }} or {!! $message !!}. If unescaped, never pass user-controlled text — flashed exception messages or request input become an XSS vector. Prefer e() at the call site or override the view with escaped output.

Config caching. After publishing or editing config/alert.php, run php artisan config:clear (and config:cache in production). A stale cached config pointing at a view you have since overridden produces confusing "view not found" or "old markup" symptoms.

View override precedence. Publishing views to resources/views/vendor/alert/ lets you replace the package partial without touching vendor/. This is the preferred extension point — cleaner than editing vendor files and safer than replacing the include globally.

Facade name collisions. The Alert alias conflicts with popular SweetAlert-style packages that register the same alias or an alert() global helper. If Composer reports a duplicate class or your IDE resolves to the wrong one, use the fully-qualified Vinkla\Alert\Facades\Alert everywhere or drop the alias entirely.

Debugging checklist when nothing renders: is the partial in the layout for the redirected page → is the calling route in the web group → does the session key match what the partial reads → is the config cached → does the markup match your Bootstrap major version.