Download the PHP package deegitalbe/laravel-trustup-io-notifications without Composer

Trustup IO Notifications (Laravel client)

Drop-in Laravel client for the Trustup IO Notifications service. It lets a source application send notifications through Laravel's native notification system and receive delivery feedback (delivered, bounced, opened, clicked, ...), all over Kafka.

• Package name: deegitalbe/laravel-trustup-io-notifications
• Namespace: Deegitalbe\TrustupIoNotificationsClient\
• Requires: PHP 8.2+, Laravel 12, mateusjunges/laravel-kafka, and the contracts package deegitalbe/laravel-trustup-io-notifications-contracts.

The notification payloads and channel definitions live in the contracts package. See its README for how to define a NotificationData class, override channel rendering, and add a new notification type. This README covers wiring the client into an app and the send / receive flows.

1. Install

The service provider is auto-discovered. It registers the config file and the two consume commands.

2. Configure

Publish the config if you want to edit defaults (optional; env vars are enough for most apps):

Set the source and the Kafka broker. Everything else has working defaults.

Config keys (config/trustup-io-notifications.php):

3. Send a notification (bare minimum)

Three pieces: a notification class, a notifiable that knows its recipient, and a notify() call.

The notification

The notification receives your own domain models and derives the NotificationData from them inside toTrustupIoNotificationsData(). You do not pass the data object in from the outside. Both toTrustupIoNotificationsData() and restrictTrustupIoNotificationsChannels() receive the notifiable being notified, so the payload and the channel restriction can depend on the recipient.

• Implement SendsTrustupIoNotification; toTrustupIoNotificationsData(object $notifiable) maps your models to the typed payload, and receives the notifiable so the payload can depend on the recipient.
• use InteractsWithTrustupIoNotifications to get the default "all channels" behavior; without it you must implement restrictTrustupIoNotificationsChannels(object $notifiable) yourself.
• Reference the channel by class in via().
• The NotificationData class (ToolsCommentNotificationData here) comes from the contracts package; see its README to define your own.

The notifiable

Add Laravel's Notifiable (for notify()), implement the interface, and use the routing trait:

Notifiable is required (it provides notify()); the package does not include it for you. RoutesTrustupIoNotifications wires Laravel's routing convention to your toTrustupIoNotificationsRecipient().

The recipient omits the source: the client fills it from TRUSTUP_IO_NOTIFICATIONS_SOURCE at publish time. Pass it explicitly (Recipient::identified((string) $this->id, Source::Tools)) only if this app sends for more than one source.

Send it

That publishes the request to Kafka. The notifications service picks it up, resolves the recipient's coordinates, and delivers on each supported channel.

4. Receive delivery feedback

The service publishes back onto the status and engagement topics. The client turns those into two Laravel events you listen to.

Run the consumers + a queue worker

The consume commands are long-running Kafka consumers. They only enqueue jobs; the events fire from inside those queued jobs. So you need the consumers and a queue worker running:

Without a queue worker, statuses and engagements are consumed but the events never dispatch.

Listen to the events

The package defines no listeners of its own by design: it emits the events, your app decides what to do (update a local model, alert on bounce, track engagement, ...). Register as many listeners as you want, on either event. Dispatching with zero listeners is a no-op, not an error.

StatusPayload and EngagementPayload shapes are documented in the contracts README.

5. What must be running

Sending only needs a reachable Kafka broker. Receiving feedback needs the two consumers and a queue worker.

Customization

Restrict channels per notification

By default a notification goes out on every channel its data class supports. Override to narrow it:

null = all supported channels. [] is invalid and rejected (InvalidEnvelopeException).

Anonymous recipients (no model)

When there is no notifiable model, route on the fly with a Recipient::anonymous(...):

The routing key is the literal string trustup-io-notifications.

Customize the payload / channels / rendering

The notification's content (which template, which variables, SMS/push wording, translations) is controlled by the NotificationData class and its Renders* traits, all in the contracts package. See that README's "Capability interfaces and their default rendering" section for the overridable methods (emailTemplate, emailVariables, emailTemplateLocaleGranularity, smsBody, pushTitle, ...).

Default source vs explicit source

Recipient::identified($id, Source::Tools) sets the source explicitly. Built without a source (Recipient::identified($id) or any anonymous recipient), the client fills it from config('trustup-io-notifications.source') at publish time. Set TRUSTUP_IO_NOTIFICATIONS_SOURCE so this always resolves.

Errors