Laravel Notification Laravel Package

Getting Started

First, correct your mental model of the package. Despite the boilerplate in the repo description ("extends Laravel's native notification system", "configurable notification channels", "queued delivery"), the package title — Simple toast notifications for Laravel + Livewire + AlpineJS — is the accurate one. This is a UI layer: a Blade partial plus an Alpine store that renders transient toasts in the browser. It does not implement ShouldQueue, does not touch Notifiable, and does not route notifications through mail/SMS/database channels. Plan accordingly; if your requirement is server-side notification delivery, this is the wrong dependency.

Read these four things before writing any code, in this order:

1. composer.json — the illuminate/* and livewire/livewire constraints. This single file decides whether the package installs on your Laravel version at all.
2. src/ — the service provider (does it use package discovery or require a config/app.php edit?) and whatever class dispatches the toast.
3. resources/views/ — the toast host markup and the CSS class names it expects (likely Tailwind).
4. resources/js/ — the Alpine component. Grep it for dispatchBrowserEvent, window.livewire.emit, and $wire.emit. Those three strings tell you whether the package predates Livewire 3.

Install:

composer require f1uder/laravel-notification:1.2.1
php artisan vendor:publish --provider="F1uder\Notification\NotificationServiceProvider" --tag=notification

Then include the package's toast-host partial once, at the end of <body> in your main layout — not inside a modal, modal wrapper, or any element with transform, filter, or backdrop-filter (those create a new stacking context and will clip the toast).

First use case — the one to prove the integration on: a Livewire component that saves a form and fires a success toast.

public function save(): void
{
    $this->validate();
    $this->post->save();

    $this->dispatch('notify', message: 'Saved.', type: 'success');
}

Confirm the exact event name and argument shape by reading the Alpine listener in the published JS — the event name is the API contract, and it is not documented. If the listener is x-on:notify.window, the $this->dispatch() call is correct for Livewire 3; if it is window.addEventListener('notify') wired to dispatchBrowserEvent, you are on a Livewire 2-era package and need to bridge it (see Gotchas).

Implementation Patterns

Wrap it, don't call it directly. Three stars, a single fix changelog in May 2023, and no maintenance signal means you should treat this as vendored code with a thin seam. Create one place in your app that all callers use:

// app/Support/Toast.php
final class Toast
{
    public static function success(string $message): void
    {
        session()->flash('toast', ['type' => 'success', 'message' => $message]);
    }
}

When the package rots — and on a two-year-old dependency, it will — you replace one file instead of grepping 40 components.

Two dispatch paths, and you must pick deliberately:

The trap is the middle case: a Livewire action that dispatches the browser event and then redirects. The navigation tears down the DOM before Alpine paints the toast, and the user sees nothing. If the action ends in redirect(), use the session-flash path. This is the single most common bug with toast libraries in Livewire apps.

Centralize the toast host. One partial in layouts/app.blade.php renders every toast for every page. Do not sprinkle include tags into individual views — you will get double-rendering on layouts that nest.

Standardize variants. The package likely ships success|error|warning|info mapped to Tailwind classes. Freeze that list in a PHP enum and keep the class mapping in one place, so a design-system change is a one-file diff:

enum ToastType: string {
    case Success = 'success';
    case Error   = 'error';
    // ...
}

Testing. Toasts are request-scoped UI, so assert at the seam, not the CSS:

Livewire::test(CreatePost::class)
    ->set('title', 'Hello')
    ->call('save')
    ->assertDispatched('notify')          // client-event path
    ->assertSessionHas('toast');          // session-flash path

Asserting on the dispatched event name is also your regression guard: if you ever fork the package and rename the event, the suite fails loudly.

Do not try to push toasts from queued jobs with this package. There is no broadcasting bridge in it. If a background job needs to surface a message, write to a notifications table or a cache key and let the authenticated session poll or use Echo — separate concern, separate implementation.

Gotchas and Tips

The description is wrong, and that matters. A teammate reading the repo README will assume Notifiable, channels, and queued delivery exist. They do not. Write a one-paragraph internal note stating what the package actually does; it will save someone a wasted afternoon.

Version pinning is mandatory here. Last release 2023-05-19, changelog literally reads fix, three stars. Adopt the exact version (1.2.1), commit the lockfile, and check the diff of 1.2.0..1.2.1 before you do. composer why-not f1uder/laravel-notification 1.2.1 inside the target app is the fastest way to see what blocks it.

Laravel 11/12 will probably need a fork. A package last released in May 2023 almost certainly caps illuminate/support at ^9.0|^10.0. If so, the correct move is not --ignore-platform-reqs — it is to fork the repo, widen the constraint, run the suite, and point Composer at your fork via a VCS repository. The package is small (a provider, a Blade view, a JS file); forking costs an hour, and you own the code either way given the maintenance signal.

Livewire 3 dispatch API break. Livewire 3 renamed dispatchBrowserEvent() to dispatch() and removed $wire.emit/$emit. If the package's JS listens via Livewire.on(...) or the PHP side calls emit(), the toast will silently no-op — no error, no console warning. Bridge it with one x-on:notify.window listener in your layout rather than patching the vendor file, so a future fork of the package stays swappable.

Alpine double-init. Livewire 3 bundles Alpine. If the published partial also includes its own <script src="alpinejs"> tag, you get either a duplicate-instance error or, worse, two listeners on the same event — every toast fires twice. Check the published Blade view for an Alpine <script> tag and delete it.

wire:navigate state leak. With Livewire 3 SPA navigation, an Alpine store persists across page swaps. Toasts queued before navigation can reappear on the next page, or auto-dismiss timers can survive and clear unrelated toasts. Reset the store on livewire:navigated:

document.addEventListener('livewire:navigated', () => Alpine.store('toasts').clear());

Use wire:key in the x-for loop over active toasts. Livewire's DOM morphing will otherwise reuse nodes, producing toasts that appear frozen mid-animation or dismiss the wrong message.

XSS surface. Plain text is fine through x-text. If the package uses x-html or {!! $message !!} anywhere, any toast carrying a user-supplied string (e.g. a resource name from a form) becomes stored XSS. Grep for x-html and {!! before shipping.

Accessibility is on you. These toast libraries typically omit role="status" / aria-live="polite". Add it in your own copy of the partial, otherwise screen-reader users get nothing. Also ensure toasts pause on hover and on keyboard focus, or fast interactions get yanked mid-read.

Know your exit threshold. For a ~200-line partial plus an Alpine store, the honest calculation is: fork it, or reimplement it in 40 lines yourself. Reimplement the moment you need any of — persistence across reloads, a queue for stacking more than a few at once, aria-live regions, broadcast delivery, or a maintainer who responds to issues. Do not wait for the package to fail you first.

Octane/worker safety: toasts are client-side, so there is no long-lived-worker state to leak here. But if the service provider registers a singleton that accumulates messages in a static array, it will bleed across requests under Octane. Verify the provider's bindings are not singleton before enabling Octane in that app.