netflex/notifications
A Laravel package for building and dispatching notifications across multiple channels, offering a clean API for defining notification classes, queueing delivery, and customizing message templates with seamless integration into Laravel's notification system.
netflex/notifications is a read-only subtree split of the Notifications component inside netflex/framework. That single fact shapes everything else: you install it via Composer, but you do not send PRs here and you should not expect a meaningful README or issue tracker on this repo. Treat it as a published slice of a monorepo.
First steps, in order:
composer.json in the package to see the exact netflex/framework constraint it was split from. Pin your application's framework version to match — these components are versioned in lockstep and mismatches are the most common source of weird failures.src/ end to end. It is small. Identify the base Notification class, the Notifiable trait/interface, the channel contracts (via(), per-channel to*() methods), and the dispatcher/queue integration. The source is the documentation here.netflex/framework) and the Netflex platform docs for the human-facing guide, changelog, and configuration keys. Anything you'd normally file as an issue belongs there.First use case: transactional notification on a domain event. A customer's order changes state; you want an email now and an SMS for the urgent transitions. Build one OrderStatusChanged notification class, wire it to a listener, dispatch it synchronously once to prove the channel config works, then move it to the queue. That single loop exercises routing, templates, credentials, and queueing — the four things that break.
One notification class per event, not per channel. via() returns the channel list; each toMail() / toSms() / etc. builds only that channel's payload. Resist a god-notification with if ($channel === ...) branching — the framework resolves channels by method name, and clarity here pays off when you add or drop a channel later.
Keep controllers and models thin. Dispatch from a listener or a small domain service reacting to a Netflex event/hook, not inline in a controller. This gives you one place to add retries, logging, and "should we notify?" policy, and it makes the send easy to fake in tests.
Routing lives on the Notifiable, not the caller. Put the Notifiable trait on the model that owns the contact details and expose the route keys (email, phone) the channels expect. Then $order->customer->notify(new OrderStatusChanged($order)) — the recipient resolution, locale, and channel addresses stay with the entity. Avoid passing raw email strings around; you lose locale and preference handling.
Queue anything that leaves the process. User-facing email/SMS should be queued. The pattern that holds up: notification implements the queue contract, listener dispatches it, worker does the I/O. This decouples your request latency from a slow SMTP handshake or a flaky SMS API, and gives you retry/backoff for free. Configure a dedicated queue for notifications so a backlog of marketing mail doesn't delay password resets.
Pass identifiers, not graphs. If your notification is queued, its constructor payload gets serialized. Prefer passing a model reference the framework can re-hydrate (or an ID you resolve in the handler) over deep object graphs or closures. This avoids serialization blowups and stale-data surprises.
Templates and copy outside the class where the platform allows. Netflex leans on platform-managed templates for editable content. Push customer-facing copy into templates/translations and keep the notification class to data assembly. Marketing will change wording far more often than you'll change logic.
Centralize channel selection policy. A small NotificationPolicy or per-user preferences check that decides whether to send on each channel keeps via() honest. Doing this ad hoc inside every notification class spreads the same conditional across dozens of files.
Testing pattern. Fake the channel transport, dispatch the notification, assert it was sent to the right recipient on the right channels, and snapshot the rendered payload. For queued notifications, assert the job was pushed and separately test the handler. Never let a test suite hit a real SMS gateway — that's how you discover per-message billing the hard way.
Do not patch the vendor copy. It is a subtree split. Any edit under vendor/netflex/notifications is wiped on composer update, and a PR to this repo goes nowhere. Upstream all changes to netflex/framework. If you must hotfix, fork the framework, not this slice.
Version lockstep. The split is generated from a specific framework commit. Mixing a newer netflex/notifications with an older netflex/framework (or vice versa) can produce missing methods or contract mismatches that look like autoloading bugs. Bump them together and commit the lockfile.
Silent non-delivery usually means no worker. Queued notifications that "never arrive" are overwhelmingly a stopped or misconfigured queue worker, not a notification bug. Check the queue connection and worker logs before touching channel code. Add a failed-job alert — otherwise failed sends vanish into the jobs table.
Channel credentials fail late. Mail/SMS config is resolved at send time, so a missing API key surfaces only when a real user triggers a notification. Verify each channel once in staging with a real send, and assert config presence at boot if the framework offers it.
Recipient resolution returns null quietly. If a Notifiable has no email or phone set, the send may be skipped with no error. Log skipped sends with the reason; "customer had no phone number" should be an observable event, not an absence.
Cost and rate limits are your problem. SMS gateways bill per message and throttle aggressively. Batch digests where you can, dedupe retries, and be careful that a retried job doesn't double-send. Idempotency keys or a sent-ledger help.
Stale serialized models. A queued notification carrying a hydrated model reflects state at dispatch time. If the email body needs the current status, re-fetch by ID inside the handler rather than trusting the serialized snapshot.
Locale and timezone drift. User locale is resolved from the Notifiable, not the request. If your queue worker's default locale differs from the web request, templates render in the wrong language. Set locale explicitly on the notification or ensure the worker honors the notifiable's preference.
Thin community, high self-reliance. With zero stars and zero dependents, there is effectively no Stack Overflow corpus. Budget time to read source and the upstream framework changelog. The upside: the component is small and readable — a couple of hours of source reading replaces days of guessing.
Extension points to prefer. Subclassing the base Notification and adding custom channels through the channel contract is the supported seam. Overriding the dispatcher is possible but brittle across framework upgrades; reach for it only when you genuinely need cross-cutting behavior (audit logging, tenancy) that can't live in a listener.
How can I help you explore Laravel packages today?