Laravel Alert Laravel Package

Getting Started

Install and confirm constraints

composer require synergitech/laravel-alert
php artisan vendor:publish --provider="Synergitech\Alert\AlertServiceProvider"

Before you run this in a real app, open the package's composer.json and check the require block: v2.0.5 explicitly confirms Laravel 13, but the release note does not state whether Laravel 10–12 are still supported. Pin the version ("synergitech/laravel-alert": "^2.0") rather than floating on dev-main.

If the package registers a facade and service provider, Laravel's package discovery handles it — no manual edits to config/app.php should be needed. Confirm discovery worked:

php artisan about          # look for the package in the packages list
cat bootstrap/cache/packages.php

Where to look first

1. config/alert.php (or whatever the published config is named) — severity levels, default view, session key.
2. The published views under resources/views/vendor/... — this is what you'll actually be editing.
3. vendor/synergitech/laravel-alert/src/ — read the facade and the alert builder class first. The whole public surface is usually 4–6 methods; ten minutes of reading saves an hour of guessing.
4. The README's usage block, which normally shows the one-liner for a flash message.

First use case

The canonical use is a flashed success message after a redirect from a form submission:

// app/Http/Controllers/PostController.php
public function store(StorePostRequest $request)
{
    $post = Post::create($request->validated());

    return redirect()
        ->route('posts.show', $post)
        ->with('alert', alert()->success('Post published.'));
}

Then render it once in your layout:

{{-- resources/views/layouts/app.blade.php --}}
@include('partials.alerts')

{{-- resources/views/partials/alerts.blade.php --}}
@if (session('alert'))
    {!! session('alert')->render() !!}
@endif

Adjust the exact method names to whatever the source exposes — the important structural point is that the alert object is flashed into the session and rendered by a single shared partial. Get that loop working end-to-end before adding custom severities or views.

Implementation Patterns

Controller → redirect → layout is the primary workflow. Keep the alert construction in the controller (or a form request / action class) and the rendering in one layout partial. Resist the urge to sprinkle alerts into individual views; one render point means no duplicates.

Compose alerts at the boundary, not deep in the domain. A service class shouldn't return an alert object. Have it return a result/DTO, and let the controller translate that into alert()->success(...) or alert()->error(...). This keeps domain code testable without the session.

Validation feedback is a separate channel. Laravel already flashes $errors on a failed FormRequest. Don't also flash an "error alert" for the same failure or users see the message twice. Use the package for outcomes (created, deleted, queued, payment failed) and leave field-level errors to @error.

Stacking multiple messages. If the builder is a collection (verify in source), you can attach several before redirecting:

return redirect()->route('dashboard')
    ->with('alert', alert()
        ->success('Import finished.')
        ->warning('3 rows were skipped.'));

If it only supports one, render the partial in a loop over an array and push each alert, or extend the class (see Gotchas).

Custom views. Publish, then override in place. Match your design system's classes (Tailwind, Bootstrap, whatever) rather than fighting the default markup. Keep the partial's contract stable — one variable, one render call — so the layout never changes when the view does.

JSON / API / Inertia responses. Session flashing does nothing useful for a stateless JSON consumer. For Inertia, flash to the session as usual and pass the alert through HandleInertiaRequests::share(). For a pure API, return the message in the payload and let the client render it — don't try to make a session package do a client's job.

Testing. Alerts are session state, so assert on the session, not on rendered HTML:

$response = $this->post('/posts', [...]);
$response->assertRedirect();
$response->assertSessionHas('alert');

Then have one feature test that does $this->followingRedirects() and asserts the message text appears in the body. Those two tests together catch both "never flashed" and "flashed but never rendered" regressions.

Custom severity levels. If the config exposes a levels map, add 'critical' => 'bg-red-900' there and the corresponding builder call. If it doesn't, prefer composing from existing levels over forking the package.

Gotchas and Tips

Flash data lives exactly one request. with('alert', ...) survives the redirect and is then gone. If you render the partial twice in a layout (e.g. once in a header include and once in a body include), the second render sees an empty session and you get a silently missing message — or, worse, a package that peeks without pulling may double-render. Pick one render point.

Don't build alerts in queued jobs, console commands, or middleware without a session. There is no session in a queue worker; the object is constructed and discarded. Persist an outcome to the database or broadcast it instead.

Config and view caches lie. After php artisan vendor:publish or editing config/alert.php, run php artisan config:clear and php artisan view:clear. In production, config:cache will happily serve stale severity maps and make you think the package ignored your change.

Escape untrusted content. Fluent APIs usually output raw HTML in the render method. If any alert text interpolates user input (a name, a filename), escape it at construction time: e($user->name). Never pass a request parameter straight into alert()->success(...) if the render path emits unescaped HTML.

Facade alias collisions. Short aliases like Alert are common. If another package claims the same name you'll get a confusing "class not found" or, worse, the wrong facade. Alias it explicitly in the published config or use the fully-qualified class.

with() ordering with other redirect data. Chaining ->withErrors(...) and ->with('alert', ...) is fine, but if you call $request->session()->flash() manually and use the builder, you can end up with two keys for the same concept. Pick the builder and stick to it.

Version and framework drift. The only release note available is v2.0.5 confirming Laravel 13. That tells you nothing about v2.0.0–v2.0.4 breaking changes or how quickly the maintainer will follow Laravel 14. Pin the constraint, read the full changelog before a major bump, and add one integration test that renders an alert — that test is your early warning for any framework upgrade that breaks the package.

Debugging a missing alert. Work down the chain in order:

1. dd(session()->all()) immediately after the redirect target loads — is the key there?
2. Is the key name what the package actually uses? Check the config, not the README.
3. Is the layout partial included in the layout the response actually extends? (A stray @extends in a child view is a classic.)
4. Is view:cache stale?
5. Is the package discovered? Check bootstrap/cache/packages.php.

Extension points worth knowing. Three things to look for in the source before you fork: whether the alert class is Macroable (then alert()->macro('critical', ...) without touching vendor code), whether the view name is config-driven (then you can point to your own Blade file), and whether the service provider binds an interface (then you can swap the implementation in a test). Any one of these turns a fork into a two-line override.

Keep it non-critical-path. This is presentational sugar. If alert rendering fails, the form submission must still have succeeded — never let an exception from the alert builder abort a write that already committed. Wrap the flash in a null-safe path or build the alert after the DB transaction closes.