Alert Laravel Package

Getting Started

Install via Composer:

composer require bpocallaghan/alert

On Laravel 5.5+ the service provider and Alert facade alias are auto-discovered. On older versions, register Bpocallaghan\Alert\AlertServiceProvider in config/app.php and add the alias:

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

In a controller, flash a message before redirecting:

public function store(Request $request)
{
    // ... persist

    alert()->success('Record saved successfully.');

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

In your layout, render the alerts exactly once — typically just inside the container near the top of the body:

{!! Alert::render() !!}

Where to look first after install:

1. vendor/bpocallaghan/alert/src/ — the main Alert class for the public API and the Blade view used for rendering.
2. The published config (php artisan vendor:publish --provider="Bpocallaghan\Alert\AlertServiceProvider") — session key, view path, and any defaults.
3. The Blade view — this is where Bootstrap markup and alert classes live, and it's the easiest thing to override.

The first real use case is the classic post-redirect-get flow: validate, persist, flash, redirect, and let the layout render the message on the next request.

Implementation Patterns

Helper vs. Facade. Both are first-class; pick one per codebase and stick to it.

alert()->success('Saved.');
Alert::error('Something went wrong.');

Message types. The conventional four map to Bootstrap contextual classes:

alert()->success('...');
alert()->info('...');
alert()->warning('...');
alert()->error('...');   // usually maps to Bootstrap "danger"

Some versions accept a title as a second argument — check the signature in src/Alert.php before relying on it:

alert()->success('Your changes have been saved.', 'Success');

Service-layer flashing. Rather than scattering alert() calls through controllers, flash from the place that knows the outcome and keep controllers thin:

class RecordService
{
    public function create(array $data): Record
    {
        $record = Record::create($data);
        alert()->success('Record created.');
        return $record;
    }
}

Be careful with this once you add queue jobs or API endpoints — flashing to the session in a queued context does nothing useful.

Rendering location. Render in the app layout, not in individual views, so every page inherits alerts. If you use multiple layouts (admin, auth, public), add {!! Alert::render() !!} to each one. Alternatively, include the package view directly if you prefer the include-style:

@include('alert::alert')

Custom markup. The fastest way to support Bootstrap 4/5, Tailwind, or your own design system is to copy the package view into resources/views/vendor/alert/ and point the config at it, or to override the view entirely. Keep the session data contract intact (type + message) and change only the markup.

Multiple alerts in one request. Check whether the underlying implementation appends to an array or overwrites a single entry. If it overwrites, wrap your own thin layer:

Alert::success('First');
Alert::info('Second');

and confirm both render — otherwise flash an array manually under your own session key.

Validation feedback. For form flows, prefer Laravel's built-in $errors bag for field-level errors and reserve this package for the human-readable summary ("Please fix the highlighted fields."). Don't duplicate the same message in both systems.

API / Livewire. Session flashing does not travel to JSON responses. For Inertia or Livewire, either read the flashed key from the shared props/session, or skip this package and return the message in the response payload.

Gotchas and Tips

• Nothing renders unless you render it. The single most common "the package is broken" issue is a missing {!! Alert::render() !!} in the layout that the current view extends.
• Flashed data is consumed once. Rendering twice in one request/page means the second call gets nothing. If you have a partial and a layout both rendering alerts, remove one.
• Use unescaped output carefully. {!! !!} is required for the alert HTML, which means a user-supplied message passed straight through is an XSS vector. Escape or sanitize anything derived from user input before flashing.
• Bootstrap class drift. The shipped view targets a specific Bootstrap major version. On Bootstrap 5, alert-danger is still fine but dismissible markup changed (data-bs-dismiss vs data-dismiss). Override the view rather than patching vendor files.
• Config caching. After publishing and editing config, run php artisan config:clear in development and config:cache in deploy. A stale cached config pointing at the old view path produces confusing "view not found" errors.
• Session driver matters. With the array driver (common in some test setups) nothing survives the redirect. Use file, database, or redis for real flash behavior, and assert on the session key in feature tests rather than on rendered HTML.
• Debugging. Inspect session()->get('alert') (or whatever key is defined in the config) right before the redirect and again in the receiving request. That isolates whether the problem is flashing or rendering.
• Naming collisions. If you also use another flash-message package, both will try to own the session and the layout. Keep one system per project or use distinct session keys.
• Extension points. The practical customization surface is: the published config, the published/overridden Blade view, and a small wrapper class around the facade if you need extra types (e.g., alert()->danger(), alert()->primary()). Avoid editing vendor/ directly — you'll lose changes on composer update.
• AJAX redirects. If a form is submitted via Axios/fetch, the redirect (and therefore the flash) is followed by the browser, not the JS caller. You'll typically need to reload the page or handle the message client-side.
• Pinned dependency. Last release was mid-2024; verify it against your Laravel version in CI before committing to it, and check composer.json constraints in the package rather than assuming compatibility with the newest Laravel major.