Filagora Push Laravel Package

Getting Started

1. Install the package and run migrations. Use the package’s push_subscriptions migration and not the migration from the sending package; the table mirrors the existing site index-for-index.
2. Set push.allowed_hosts to the push-service hosts you actually use. Endpoints are accepted only when they are https, on the default port, and targeted at one of these hosts.
3. Review the listen and routes configuration for the bundled alerts: mentions, new posts in followed threads via filagora-forums, and private messages via filagora-messages.
4. Register the browser subscription flow: request permission, obtain the push subscription, then persist it through PushSubscriptions::store.
5. First useful end-to-end case: store a subscription for a user, trigger a mention or private-message alert, and confirm last_used_at is updated on the PushSubscription.

Look first at PushSubscriptions, PushNotifier, WebPushAlert, PushPreferences/AllowsAllPushPush, and the PushRefused/PushRefusal types. Those define the day-to-day API surface.

Implementation Patterns

Subscription lifecycle

Use PushSubscriptions as the single entry point rather than writing to the model directly:

• store when a browser first subscribes.
• resync when the client reports an existing subscription again. The old endpoint must already be on file for that person; do not use it for a brand-new endpoint.
• remove on explicit unsubscribe or when the browser subscription is revoked.
• for and hasAny to drive UI state such as showing “Enable notifications” versus “Notifications enabled”.
• pruneStale is normally invoked by filagora:push:prune-stale, scheduled in Laravel’s scheduler.

Sending alerts

Create a WebPushAlert with the relevant PushCategory, then hand it to PushNotifier. The notifier works with any user model, so existing application user classes do not need a package-specific base class.

The notifier is responsible for:

• Checking whether the person has any subscription.
• Consulting PushPreferences; the default AllowsAllPush allows every category.
• Dropping expired subscriptions during delivery.
• Updating last_used_at after use.

Preferences and categories

Implement PushPreferences when users need granular control. Without a custom implementation, AllowsAllPush means category checks always pass. Keep category decisions in preferences rather than branching in every alert call site.

Bundled framework alerts

For filagora-forums and filagora-messages, use the provided mention, followed-thread, and private-message alerts instead of writing duplicate listeners. Toggle each alert under listen, and configure the destination pages under routes. This keeps notification behaviour consistent with the host application’s URL structure.

Privacy and retention

The package supplies a privacy contributor that exports subscription data without endpoint or keys and supports erasure. Wire it into the application’s privacy/export flow. Schedule filagora:push:prune-stale; the retention rule is push.stale_subscriptions and defaults to 180 days.

Gotchas and Tips

• Endpoint validation is deliberately strict. isAllowedEndpoint accepts only HTTPS on the default port and only hosts in allowed_hosts. Local development URLs, custom ports, and unlisted push hosts will be refused.
• Handle refusals explicitly. A refused endpoint throws PushRefused carrying a PushRefusal reason. Catch this at the subscription boundary and return a useful validation response rather than a generic 500.
• Do not normalise endpoints client-side. The package refuses URLs that a URL parser and an HTTP client could interpret differently. Rewriting or trimming the endpoint before storage can create a mismatch or a refusal.
• resync is not store. It requires the previous endpoint to already exist for that person. Calling it for a first-time subscription will not create the record.
• Migration conflict risk. If the sending package’s migration is already present, remove or skip it; this package explicitly expects its own push_subscriptions migration to be used.
• Default preferences are permissive. AllowsAllPush means alerts are allowed unless a real PushPreferences implementation is bound. Add preference checks before assuming category-level opt-outs work.
• Expired subscriptions disappear during send. Delivery can remove expired records, so do not assume a subscription fetched earlier still exists after a send.
• Pruning is configuration-driven. Changing push.stale_subscriptions requires clearing cached config in deployed environments.
• Privacy export intentionally omits secrets. Endpoint and key material are excluded from exports; do not “fix” this by adding them back. Erasure must remove the stored subscription data through the contributor.
• last_used_at is delivery telemetry, not proof of receipt. Use it to understand recent activity, not as a guaranteed read receipt.