Filagora Push Laravel Package

Technical Evaluation

Assessment basis: No prior assessment existed; this is the initial assessment for v0.1.0, a first release. Treat API and schema as pre-1.0 and subject to change.

Architecture fit: The package fits a Laravel modular monolith or package-oriented architecture. It supplies an Eloquent model and migration for push_subscriptions, a domain service (PushSubscriptions), a notifier (PushNotifier), alert categories (PushCategory), and integration hooks for mentions, followed-thread posts, and private messages. The explicit choice to own the push_subscriptions migration instead of the sending package’s migration is the right architectural boundary: subscription storage and endpoint policy live with this package, while delivery mechanics remain with the sender. It works with any user model, which is important for reuse across apps and avoids coupling to a single User class.

Integration feasibility: Feasible for a Laravel application that already has queue workers, configuration management, and a user/person model. The package is security-conscious around endpoint validation: HTTPS-only, default port, host allowlist, and refusal when URL parser and HTTP client interpretations diverge. That is a meaningful control for web push endpoint spoofing and SSRF-style risks. resync requiring the old endpoint to already be on file prevents arbitrary endpoint replacement. Optional alerts depend on filagora-forums and filagora-messages, so adoption can be staged. Privacy contributor support for export and erasure is a positive sign for production readiness, though it must be verified against the host app’s privacy framework.

Technical risk: Main risks are pre-1.0 instability, migration ownership conflicts with the sending package, and configuration sensitivity. allowed_hosts must be correct or all subscriptions will be refused; default-port-only validation may reject legitimate nonstandard endpoints. PushPreferences defaulting to AllowsAllPush needs product/privacy review. The package adds writes on delivery (last_used_at) and cleanup jobs, so queue and database behavior must be tested under load. Optional module coupling can create runtime failures if listeners are enabled without the corresponding packages. Route definitions for alert destinations may conflict with host app routing conventions. The endpoint validation logic is high-risk security code and should have dedicated tests, including parser/client disagreement cases.

Key questions: What Laravel/PHP/database versions are supported? Which sending package and VAPID configuration are assumed? Is the push_subscriptions schema/index set exactly compatible with the existing site’s table? What is the expected user/person contract for PushNotifier and PushPreferences? How are PushCategory values mapped to preferences and alert listen switches? Are jobs queued, retried, and rate-limited, and how are 404/410/429/5xx responses handled? How are routes published or overridden? Does the privacy contributor integrate with the host app’s export/erasure pipeline? How does pruning behave under concurrent delivery? Is multi-tenant or multi-app use supported?

Integration Approach

Stack fit: Good fit for a Laravel app using Eloquent, Artisan commands, config publishing, and queued notifications. It complements rather than replaces a web-push sender package. The package’s table and model match an existing site’s schema, reducing data migration effort. Optional forum/message alerts make it suitable for incremental adoption.

Migration path: Install the package and publish its config and migration. Critically, remove or disable the sending package’s push_subscriptions migration so only this package owns the table. Confirm index parity with the existing site’s table before running in production. Configure allowed_hosts and the sender’s VAPID/web-push credentials. For existing subscriptions, use resync only where the old endpoint is already on file for that person; do not attempt arbitrary endpoint import. Then wire PushNotifier and alert listeners, keeping listen switches off until each integration is validated. Enable the privacy contributor and verify export excludes endpoint/keys and erasure removes subscriptions.

Compatibility: Confirm Laravel and PHP constraints, database support, queue driver expectations, and optional filagora-forums/filagora-messages versions. Validate that URL validation behavior matches the HTTP client used by the sender in the target runtime. Test against the host app’s user model and preference resolution. Check route naming and middleware compatibility before enabling alert routes.

Sequencing: 1) dependency/version pin and config review; 2) migration ownership and schema parity check; 3) endpoint validation and refusal-reason tests; 4) sender integration and VAPID configuration; 5) preference/category wiring; 6) optional alert listeners behind flags; 7) pruning command and retention schedule; 8) privacy export/erasure verification; 9) staging canary, then production rollout. For an existing site, coordinate the cutover so the sending package migration is removed in the same deployment window that this migration is introduced.

Operational Impact

Maintenance: v0.1.0 is pre-1.0, so pin the version and review release notes before upgrades. Maintain host-app tests around endpoint validation, migration parity, preference defaults, and privacy behavior. Changes to allowed hosts, routes, or optional module versions should be treated as configuration changes requiring validation.

Support: Expect support load around allowed_hosts misconfiguration, refused endpoints, preference defaults, and optional module enablement. Provide runbooks for “push not delivered” triage: subscription existence, endpoint allowlist, preference category, queue health, sender response, and last_used_at freshness. Privacy requests need a documented path for export and erasure.

Scaling: Delivery writes last_used_at, so high-volume push traffic creates database write pressure. Subscription fanout per person and per browser must be sized against queue throughput. Pruning should run off-peak and be monitored; 180-day retention limits table growth but large subscription tables still need appropriate indexes. Consider batching and queue separation for push jobs.

Failure modes: All endpoints refused due to allowed_hosts or port policy; migration conflict with the sending package; parser/client disagreement edge cases; expired subscriptions not cleaned if pruning is unscheduled; push provider 404/410/429/5xx responses; queue backlog delaying alerts; missing optional modules causing listener errors; privacy export leaking endpoint/keys or erasure missing subscriptions; route collisions; write contention on last_used_at. Each should have a test and an operational alert where practical.

Ramp-up: Moderate for a Laravel team. Engineers need familiarity with web push/VAPID, endpoint security, Laravel queues, and the host app’s privacy framework. TPM should plan a short spike for endpoint validation and migration ownership, a staging validation pass with real browser subscriptions, and a production runbook before enabling alerts broadly.