Nginx Pushstream Broadcaster Laravel Package

Getting Started

Start with the package's configuration file — specifically NGINX_PUSHSTREAM_CHANNEL_SALT. This is the single value that ties the Laravel side to your nginx pushstream module, and everything else (personal channels, broadcast, notifications) derives from it. Set it before anything else, and mirror the same value in your nginx config.

Next, add the new trait to your authenticatable model:

use NginxPushstream\Laravel\Notifications\ReceivesPushstreamNotifications;

class User extends Authenticatable
{
    use ReceivesPushstreamNotifications;
}

The trait already pulls in Notifiable, so do not add it twice — if you have an existing Notifiable on the model, consolidate them.

Your first use case is the smallest possible one: fire an ad-hoc progress update to a logged-in user.

$user->notify(new PushstreamNotification(Message::data(['progress' => 50])));

Then verify delivery by subscribing to the derived personal channel from the browser and watching for the payload. If nothing arrives, check the salt and that the user has an identifier before suspecting the nginx side — those are the two silent-disabled conditions.

For anything beyond personal channels, look at the existing publisher/broadcast API first; that surface is unchanged in this release and remains the right tool for fan-out to shared channels. Notifications are the ergonomic wrapper, not a replacement.

Implementation Patterns

Personal channel notifications. The trait derives the established personal channel from the user identity, so $user->notify(...) requires no channel argument. This is the pattern to reach for whenever the target is exactly one authenticated user — progress bars, job completion, per-user alerts.

Domain notifications for anything structured. When a payload belongs to your app rather than to Laravel's generic message concept, create a notification class that selects the channel explicitly and implements the conversion method:

class OrderShipped extends Notification
{
    public function via($notifiable): array
    {
        return [PushstreamChannel::class];
    }

    public function toPushstream($notifiable): Message
    {
        return Message::data(['order' => $this->order->id]);
    }
}

This is where you get queue support. The supplied PushstreamNotification wrapper sends synchronously; only notifications you write yourself can opt into ShouldQueue. If notification latency matters (for example, notifying inside a request that also writes to the database), write the domain notification rather than reaching for the wrapper.

On-demand routing. For users who aren't persisted models — invitees, guest sessions — use Laravel's Notification::route(...) on-demand API. The package supports it, so you don't need to fake a user record just to push to them.

Testing with Notification::fake(). Standard Laravel assertion helpers work unchanged. Assert on the notification class and channel, not on HTTP. This keeps the suite fast and independent of a running nginx instance.

Migration sequencing. If you already have personal subscriptions in the wild, deploy the new salt-aware configuration while keeping the existing shared salt value. Rotating the salt during the migration breaks every live subscriber's channel derivation, and they won't reconnect until they reload. Treat the salt as a long-lived secret, not a per-release value.

Cancellation and events. Notification events fire and cancellation is supported, so you can wire existing listeners (audit logging, metrics) around the notification lifecycle without special-casing this channel.

Gotchas and Tips

• Missing identity or salt fails silently. Personal routing is disabled rather than throwing. A missing user identifier or an unset NGINX_PUSHSTREAM_CHANNEL_SALT produces no exception and no delivery. Add an assertion or config check in your bootstrapping so this surfaces at deploy time instead of as a "notifications sometimes don't arrive" bug.
• A channel name is not authentication. Anyone who knows or guesses the channel name can subscribe. The salt derives the name; it does not authorise the subscriber. Do not treat private-looking channel names as access control — if the payload is sensitive, protect the subscribe path in nginx (auth subrequest, signed URLs) or reduce what you send.
• Keep the salt stable across deploys. Rotating it silently orphans every open subscription. Any environment that generates the salt dynamically — per-container secrets, ephemeral envs — is a latent bug for long-lived subscribers.
• The wrapper is synchronous. PushstreamNotification blocks on the HTTP call inside the request. For high-frequency progress updates, consider whether each tick needs its own notification, or whether you should batch at the publisher level instead.
• Trait conflicts. ReceivesPushstreamNotifications includes Notifiable. On a model that already uses Notifiable, resolve the duplicate use rather than leaving both — trait method resolution order will decide for you otherwise, and that's a confusing debugging session.
• Debugging order. When a push doesn't land, check in this sequence: (1) is the salt set and identical to nginx's, (2) does the notifiable have an identifier, (3) is the derived channel the same one the browser subscribed to, (4) is the message actually reaching the endpoint. Only the fourth step involves the transport, and it's the one people jump to first.
• Queue support lives in your notification, not the wrapper. Switching PushstreamNotification to queued won't work; convert to a domain notification implementing ShouldQueue if you need async delivery.
• Live delivery is not tested. The package's suite covers 101 tests, 100% executable line coverage, and kills all 106 generated mutants including HTTP-fake-level channel delivery — but nginx-to-browser delivery is explicitly out of scope and requires your own deployment acceptance. Budget for a manual end-to-end check in staging before trusting it in production.