Notifications Laravel Package

Getting Started

Start in the docs shipped with v1.5.0 — Developer/Index (routing + on-demand notifications) and Testing/Index — then open these three files in the package: NotificationDispatcherInterface, the Notifiable route resolution trait, and a channel implementation (mail is the reference).

Minimal wiring:

1. composer require agencelex/notifications (TYPO3 13.4 / 14 supported; DDEV + SQLite used by the package's own test suites).
2. Define a notification with via() returning channel keys and a to<Channel>() payload method.
3. Make your record Notifiable: implement routeNotificationFor<Channel>() per channel (or use HasRouteNotificationForMail for email).
4. Dispatch through NotificationDispatcherInterface.

First use case — notify someone with no database record (contact form, invite, admin alert):

$dispatcher
    ->route('mail', '[email protected]')          // returns AnonymousNotifiable
    ->notify(new WelcomeNotification($payload));

For multi-channel fan-out use routes(['mail' => ..., 'slack' => ...]). This is the biggest day-to-day win in 1.5: you no longer need a throwaway model just to send a notification.

Implementation Patterns

Convention-based routing. The sender calls routeNotificationFor($channel, $notification) before every delivery, which resolves routeNotificationFor<Channel>(). The method name is built from the channel key in UpperCamelCase, with -, _ and spaces as separators: channel my-channel → routeNotificationForMyChannel(), channel SlackChannel → routeNotificationForSlackChannel(). Implement one method per channel a notifiable can receive.

Channel identity. Channels with getName() are keyed by that name; channels without it are now keyed by short class name (SlackChannel, not Lex\Notifications\Channels\SlackChannel). Align via() returns with the key that actually exists on the channel class.

Anonymous notifiables. Treat route()/routes() as the entry point for anything ad hoc. Wrap it in a small application service (e.g. ContactNotifier) so controllers never touch the dispatcher directly, and so on-demand routing stays testable.

Database channel. routeNotificationFor('database') returns true rather than null, so the database channel is never skipped. Notifiables that only persist in-app notifications need no route method at all.

Email. HasRouteNotificationForMail now requires only getEmail(); getFirstName()/getLastName() are optional and routeNotificationForMail() accepts an optional Notification argument. This is the cheapest path for models that only store an address.

Custom dispatchers. If you decorate or replace the dispatcher, implement channel(), route() and routes() — the interface now declares all three. Prefer decorating the stock dispatcher and delegating, rather than reimplementing routing.

Testing. Mirror the package's own setup: unit tests for each routeNotificationFor<Channel>() return value plus one functional test per channel against SQLite. Assert the skipped case explicitly — see below.

Gotchas and Tips

• Silent skips are the new failure mode. A channel is skipped whenever routeNotificationFor($channel, $notification) returns empty. Nothing throws. If mail "works in dev but not in prod," check the route method's return value before anything else. Add a log line in your dispatcher decorator when a channel is skipped.
• Every custom channel needs a route method. Notifiables must implement routeNotificationFor<Channel>() for each custom channel they can be notified through. Missing method = skipped delivery, not an error.
• Channel key rename breaks via(). Any via() entry using a fully-qualified class name for a channel without getName() must switch to the short class name. Grep via() for \\ and fix those first.
• === null checks on the database route will break. It now returns true. Use falsy checks instead.
• Method-name derivation is strict. Keys containing -, _ or spaces are camel-cased — a channel named slack-notifications expects routeNotificationForSlackNotifications(). A typo in the casing means a skipped channel with no diagnostic.
• Custom dispatcher implementations fatal-error until channel(), route() and routes() are added. Ship that in the same deploy as the upgrade.
• Mail signature change. routeNotificationForMail() takes an optional Notification; if you override it, keep the parameter optional and nullable-compatible so existing callers don't break. The getLastName()-without-getFirstName() fatal is fixed, but verify any subclass overriding both.
• Debugging route resolution: temporarily call $dispatcher->route($channel, $notifiable) (or the notifiable method directly) in tinker/a test and inspect the value — it is the exact value the sender sees.
• Pinning: 1.5.0 carries three breaking changes; if you cannot audit channel keys and route method names immediately, pin to ^1.4 and schedule the migration.