Notify Laravel Package

Getting Started

Install and publish in one pass:

composer require bpocallaghan/notify
php artisan vendor:publish --provider="Bpocallaghan\Notify\NotifyServiceProvider"

On Laravel 5.5+ the service provider and Notify facade are auto-discovered; on older versions register them in config/app.php. The publish step is not optional in practice — it drops config/notify.php, the notify::messages view, and the CSS/JS assets into public/vendor/....

Then wire the layout once. All three pieces are required, and order matters (CSS in <head>, the partial and JS before </body>):

{{-- resources/views/layouts/app.blade.php --}}
<head>
    @notifyCss
</head>
<body>
    @include('notify::messages')
    @notifyJs
</body>

First use case — the flash-then-redirect loop you will write a hundred times:

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

    notify()->success('Invoice #' . $invoice->number . ' created.');

    return redirect()->route('invoices.show', $invoice);
}

Where to look first, in order:

1. config/notify.php — defaults for timeout, animation, and the type→icon/CSS-class map.
2. resources/views/vendor/bpocallaghan/notify/messages.blade.php (after publish) — the markup you will be restyling.
3. src/Notify.php / the facade — the authoritative method signatures. This package changed argument shapes across releases, so read the source rather than trusting a blog snippet.
4. The package README for the current notify()->success(...) / ->timeout() / ->icon() surface.

Implementation Patterns

One helper method on a base controller. Do not sprinkle notify() through services and models. Keep it at the HTTP boundary where the redirect happens:

abstract class Controller
{
    protected function flash(string $type, string $message, ?int $timeout = null): void
    {
        $notification = notify()->{$type}($message);
        if ($timeout) {
            $notification->timeout($timeout);
        }
    }
}

This gives you one place to swap the package out later, which matters given its maintenance status.

Stacking messages. Calling notify() more than once in a request is the intended way to report partial success; the session payload is an array and notify::messages loops it:

notify()->success('42 rows imported.');
notify()->warning('3 rows skipped — missing SKU.');
return back();

Use this instead of concatenating everything into one string; each message renders with its own icon and timeout.

Publish the view, never the vendor file. Copy messages.blade.php into resources/views/vendor/bpocallaghan/notify/ and restyle it to your design system (Tailwind/Bootstrap classes, role="status", aria-live="polite"). That published copy is your theme layer and survives composer update. Likewise, add your own types in config/notify.php rather than editing the package's type list.

Guard non-HTML responses. The package is session + redirect shaped. Anything returning JSON, a streamed download, or an Inertia response should skip it:

if ($request->expectsJson()) {
    return response()->json(['invoice' => $invoice], 201);
}
notify()->success('Invoice created.');
return redirect()->route('invoices.index');

For Inertia you generally want shared props instead — flash to the session and read it in HandleInertiaRequests::share(), then let the frontend toast component render it. Keep this package for classic Blade pages.

Assert it in feature tests. Because it is just session state, no browser is needed:

$response->assertSessionHas('notify');
$this->followRedirects($response)->assertSee('Invoice #');

Gotchas and Tips

Silent failure is the default failure mode. If you forget @notifyCss or @notifyJs, the flash is written to the session correctly, the partial renders the markup, and nothing appears on screen — or unstyled text appears at the bottom of the page. When "notifications stopped working," check the layout include before you check the controller.

Assets 404 after deploy. The JS/CSS live in public/, so composer install --no-dev on a fresh box leaves them missing. Add the publish step to your deploy script, or copy them into your own asset pipeline (Vite/Mix) and drop the @notifyCss/@notifyJs directives in favour of your compiled bundle — that also lets you version and cache-bust them properly.

Session requirements. The flash rides on Laravel's session. Routes in the api middleware group, or any request where the session is not started, will drop notifications without an error. Same for return response()->json() after a notify() call — the flash is written but never consumed.

Timeout units. Timeouts are milliseconds, not seconds. ->timeout(5) dismisses the toast almost instantly and looks like a rendering bug. Also check whether the config default and the per-call value are additive or overriding in your version.

Unmaintained since 2020. Last release 2020-05-20. On Laravel 9+ expect friction: helper/str_* deprecations, PHP 8.1+ notices, and Blade component changes. Vendor-patch only as a stopgap; for new projects prefer spatie/laravel-flash (bare session flash) plus your own Blade component, or mckenziearts/laravel-notify if you want a maintained toast package.

Name collisions. The global notify() helper and the Notify facade alias are aggressive names. If another package registers either, you get a confusing "cannot redeclare" or a facade pointing at the wrong class. Check config/app.php aliases and any other composer require ...notify in the project.

Check the escaping. Look at how the published messages.blade.php renders the message body. If it uses {!! !!}, never pass user-controlled strings (validation messages, imported-row contents, exception messages) straight in. Escape at the call site or switch the partial to {{ }} — a flash message is still an XSS vector.

Debugging checklist when a toast vanishes: session()->has('notify') right before the redirect → is @notifyJs present exactly once (double includes break the init) → any JS error earlier on the page (the package's script often depends on jQuery being loaded first) → CSP blocking inline script injected by @notifyJs → php artisan view:clear after editing the published partial.

Extension point summary: config for types/animations/timeouts, published view for markup, published assets or your own bundle for styling, and a base-controller wrapper for the API surface. Touch nothing inside vendor/.