Filagora Push Laravel Package

Product Decisions This Supports

• Notification channel strategy (web push vs email vs in-app). This package makes browser push a first-class, shippable channel on day one, so the roadmap decision becomes "which events deserve push?" rather than "can we build push?" Use it to pilot push for a small set of high-signal events before committing to broader rollout.
• Re-engagement and retention experiments. Push is one of the few levers that reaches users off-site. The listen switches per alert type (mentions, new posts in followed threads, private messages) allow A/B or staged rollout by category without new code.
• Build vs. buy for delivery infrastructure. The package ships the subscription store, VAPID/endpoint validation, delivery, and stale cleanup. The remaining build decision narrows to "do we need custom segmentation, scheduling, or analytics?" — typically a later-phase concern.
• Privacy and compliance roadmap. The included privacy contributor (export without endpoint or keys; erasure) and the push.stale_subscriptions retention rule (180 days) mean GDPR/DSAR obligations are covered out of the box, reducing legal review cycles for launch.
• Security posture for user-supplied URLs. isAllowedEndpoint (https-only, default port, host allowlist, parser-ambiguity rejection, PushRefused/PushRefusal reasons) hardens against SSRF and parser-confusion attacks — a security-review checkbox that would otherwise block launch.
• Cross-product integration sequencing. The forums (filagora-forums) and messaging (filagora-messages) alert hooks show the intended integration path; decisions about whether push is enabled by default for those modules, and what the default preference (AllowsAllPush) should be, are product calls this package exposes explicitly.
• Multi-tenant / multi-model flexibility. "Works with any user model" means the same package serves multiple products or tenant types without a separate integration, informing consolidation decisions.

When to Consider This Package

Adopt when:

• You are on Laravel/PHP and already use (or plan to use) filagora-forums and/or filagora-messages; the built-in alerts are effectively free.
• You need browser push as a distinct channel and want the subscription lifecycle (store, resync, remove, prune) handled rather than hand-rolled.
• Compliance matters (GDPR export/erasure, data retention) and you want those guarantees at the package layer.
• You have an existing push_subscriptions table on the sending side — the migration here is explicitly designed to match it index-for-indexto ease migration.
• You need per-category user opt-in (PushPreferences, PushCategory) and per-user model support.

Look elsewhere / defer when:

• You need native mobile push (APNs/FCM) — this is web push only.
• You require advanced campaign tooling: scheduling, drip sequences, audience segmentation, delivery analytics, or A/B testing of creative. This package delivers alerts, not a marketing platform.
• You cannot maintain an allowed_hosts allowlist or are in an environment where push endpoints are dynamic — the strict endpoint validation will refuse legitimate-but-unlisted hosts.
• You are not on Laravel (or are on an older, unsupported version — the release notes imply modern Laravel conventions but do not state a version floor; verify before committing).
• The resync requirement ("the old endpoint must already be on file for the person") does not match your data migration story — you may need a backfill strategy rather than a like-for-like swap.
• You need multi-channel orchestration (push + email + SMS fallback) — treat this as one channel adapter, not the whole notification system.

How to Pitch It (Stakeholders)

For executives: We can turn on browser push notifications without building a notification platform. This package gives us the full loop — capturing subscriptions, validating endpoints securely, delivering alerts, and complying with privacy obligations — so the cost is integration and product policy, not infrastructure. It reuses our existing forums and messaging products to drive immediate value (mention alerts, thread activity, DMs), which is our cheapest path to improved retention and re-engagement.

For engineering: It is a focused Laravel package: a push_subscriptions table and model, a PushSubscriptions service handling the full subscription lifecycle (including a pruneStale cleanup and a scheduled command with a 180-day retention rule), a PushNotifier/WebPushAlert delivery pipeline that respects per-user PushPreferences, and optional integrations for forums and messaging alerts exposed via listen and routes. Endpoint validation is deliberately strict — https-only, default port, host allowlist, parser-confusion–safe, with typed PushRefused/PushRefusal results — which materially reduces SSRF risk. It is user-model agnostic and ships a privacy contributor for export and erasure. Note: the migration intentionally mirrors an existing table for easy adoption; if we are not migrating from that sender, review the schema and the resync semantics first.

For legal/security: Privacy and endpoint-hardening are built in, not bolted on; the retention rule and erasure path should short-circuit typical DSAR review, and the URL validation rationale is documented in the release itself.

Open questions to settle before commitment: Do we enable push by default for new users (default AllowsAllPush) or opt-in? Which alert categories do we ship with listen enabled first? Do we have a version-support and upgrade policy for the package given it is at v0.1.0 (pre-1.0 API stability risk)?