Download the PHP package thesetj/laravel-notification-foundation without Composer

laravel-notification-foundation

A foundation package for building Laravel notifications. Instead of writing toDatabase(), toFcm(), and toSms() from scratch in every notification, you populate a shared data bag using fluent setters in the constructor — the package delivers it to each active channel automatically.

Channels are registered globally in a published service provider (similar to middleware in bootstrap/app.php) and can be toggled on or off per notification instance.

Base class

Extend QueuedBaseNotification for notifications that should be queued (the common case). Extend BaseNotification directly when you need synchronous delivery — it has no ShouldQueue or Queueable.

Installation

Publish the service provider stub:

Register it in bootstrap/providers.php (Laravel 11+) or config/app.php:

The zero-override pattern

The default toDatabase(), toFcm(), and toSms() implementations read directly from what you set via the fluent API. For most notifications, no payload methods need to be written at all — the entire notification is just a constructor:

setSharedData() is merged into every active channel's payload automatically. Individual channels can add their own data on top, or rely on shared data alone. No toDatabase(), toFcm(), or toSms() methods needed.

Extending the default FCM payload

The default toFcm() builds a ready-to-send FcmMessage. To add extra fields on top of it, call parent::toFcm() and chain mergeData() — the same pattern as extending a database channel's buildPayload():

setData() and mergeData() coerce FCM data values to strings automatically (FCM requires this). Booleans become '1'/'0', numbers become their string representation, arrays and objects are JSON-encoded. String values are passed through unchanged.

Overriding a payload method

Override the full method when the default merge logic does not apply. The data bag and shared data are still available:

Per-instance channel toggling

Every registered channel — built-in or custom — automatically gets fluent toggle methods:

The default active state per channel is set in the service provider (see below).

Channel registration

Edit the published App\Providers\NotificationFoundationServiceProvider. Comment out or remove what you don't need, and add your own channels:

The third argument is the default state (true = active, false = inactive).

Channel names are normalized to lowercase, so 'myChannel' and 'mychannel' are equivalent. The convention is to use lowercase names, as shown above.

Driver binding

FcmChannel and SmsChannel delegate delivery to driver contracts. Bind your implementations in a service provider:

FCM driver

Implement FcmDriverContract. The contract's send() method receives either a single token string or an array of tokens, so it can serve as a gateway to whatever internal structure your provider requires:

SMS driver

Implement SmsDriverContract. The send() method can likewise act as a gateway — if your SMS provider supports bulk sending, add a private sendMany() and dispatch from send() based on whether $message->getTo() is a single number or a list:

FCM routing

Add routeNotificationForFcm() to your notifiable model:

SMS routing

Add routeNotificationForSms() to your notifiable model, or set the recipient directly on the message:

To set a sender ID or from-number, call from() on the message. The driver receives it via getFrom():

Testing

Call BaseNotification::flushChannelRegistry() in setUp and tearDown to reset the global channel registry between tests: