Nginx Pushstream Broadcaster Laravel Package

Product Decisions This Supports

• Real-time UX without a managed service. This is a Laravel-native path to push updates (progress bars, live job status, dashboards, admin notifications) over nginx-pushstream, avoiding per-message/per-connection costs and third-party vendor lock-in for teams already running nginx. Useful input to build vs. buy decisions against Pusher/Ably/Soketi/Redis-broadcast stacks — it strengthens the "build on existing infrastructure" option.
• Notification-channel parity. v1.2.0 makes push a first-class Laravel notification channel alongside mail, database, and broadcast. That reduces the cost of a feature decision like "should these alerts be in-app live, emailed, or both?" — the same notify() API, Notification::fake() in tests, and queue opt-in means PMs can greenlight multi-channel notification features without a bespoke delivery project.
• Feature scope and sequencing. Because on-demand routing, events, and cancellation are supported, roadmap items like "cancel a running export," "notify the assignee on status change," or "live progress on report generation" become small, composable stories rather than platform work.
• Risk/rollout decisions. The package explicitly separates what is proven (101 tests, 323 assertions, 100% line/method coverage, 106/106 mutants killed, static analysis, independent runtime review with HTTP fakes) from what is not (live nginx-to-browser delivery requires deployment acceptance). That gives a PM a clean gate: adopt behind a spike, ship after a deployment acceptance test.
• Security posture decision. The release notes are candid that a channel name does not authenticate subscribers — anyone who knows/derives a channel can subscribe. This is a product-visible decision: acceptable for non-sensitive progress/telemetry, not acceptable for PII, financial, or permission-scoped data without an additional authorization layer at the nginx/subscription boundary. PMs should treat this as a scoping constraint, not a bug.
• Migration/upgrade planning. Guidance to keep the existing shared salt during migration preserves personal subscriptions — a low-drama upgrade path that avoids a user-visible "my live updates stopped" incident.

Use cases that fit well: long-running job progress, async report/export status, internal admin and ops dashboards, lightweight in-app toasts, per-user activity feeds on a single Laravel app behind nginx.

When to Consider This Package

Adopt when:

• You run (or will run) nginx with the pushstream module and want to use it rather than stand up a separate realtime service.
• You are on a supported Laravel version and already use the Notifiable pattern; the trait composing Notifiable and deriving the personal channel means near-zero integration code.
• Your push payloads are low-sensitivity and short-lived (progress, status, counts) where a channel-name-only subscription model is acceptable.
• You need testability — Notification::fake(), notification events, and cancellation support mean this won't become an untestable special case in your suite.
• You want queue control per notification: the supplied wrapper sends synchronously, and domain notifications can opt into queues, so latency/throughput trade-offs are a per-feature decision.
• You can absorb a deployment acceptance step for live nginx-to-browser delivery — the package's own evidence stops at HTTP fakes and an independent runtime review.

Look elsewhere when:

• You need authenticated or authorized subscriptions. If a leaked or guessable channel name is a real threat (multi-tenant data, regulated data, anything user-private), require a signed-token/authorization layer in front of nginx, or choose a platform with built-in private-channel auth (Pusher-style, Soketi, Laravel Reverb/WebSockets).
• You are not running nginx or cannot own nginx module configuration and the shared salt as operational surface. This package deliberately owns the channel salt in its documented config — that's a deployment responsibility, not a hidden one.
• You need bidirectional or client-to-server messaging; this is publish/subscribe push.
• You need managed SLAs, presence, or fan-out at large scale — an infrastructure team and an on-call story are prerequisites.
• You require cross-region or vendor-managed delivery guarantees; nginx-pushstream pushes that onto your own ops.

Adoption checklist before committing: confirm nginx build includes pushstream; decide where the shared salt lives and how it rotates; define which payload classes are permitted (no PII by default); add the deployment acceptance test to the release checklist; document the salt-migration procedure.

How to Pitch It (Stakeholders)

For executives (one paragraph): We can add live, in-app push updates — progress on long-running jobs, status changes, admin alerts — using Laravel's standard notification API and infrastructure we already operate, instead of paying a realtime SaaS vendor per connection or per message. The new release makes this a normal Laravel notification channel: same developer API, same test fakes, queue support where we want it. Engineering evidence is strong (full test coverage, mutation testing all killed, static analysis, plus an independent runtime review), with one honest gap: live nginx-to-browser delivery still needs a deployment acceptance test before we rely on it in production.

For engineering leads:

• Integration is a trait on the User model plus a configured channel salt; personal channels are derived automatically, and custom notifications can implement toPushstream() with PushstreamChannel::class.
• Test surface is intact — Notification::fake(), notification events, on-demand routing, and cancellation all work; nothing here forces you into untestable code.
• Delivery model is explicit: the provided wrapper is synchronous; queueing is an opt-in per domain notification. Existing publisher/broadcast APIs and application JSON envelopes are unchanged, so this is additive, not a rewrite.
• The upgrade is safe if we keep the existing shared salt through migration, which preserves current personal subscriptions.

Risks to state plainly, not bury: channel names are not authentication — we must decide which data classes are allowed on this channel and, if needed, add an authorization step at subscribe time. The shared salt becomes a piece of production configuration we own. And the delivery path from nginx to browser is validated only by HTTP fakes and runtime review so far; treat the deployment acceptance test as a release blocker, not a nice-to-have.