Laravel Push Notifications Laravel Package

Technical Evaluation

Architecture fit. This is a thin, idiomatically Laravel integration layer over aporat/push-notifications, not a reimplementation of APNs/FCM transport. The design maps well to common Laravel deployments: per-app configuration entries line up with multi-brand/multi-tenant product structures, via() channel support means push slots into the existing notification pipeline rather than running alongside it, and process-lifetime clients align with how queue workers actually behave (connection reuse across jobs instead of a TLS handshake per send). The abstraction boundary — Push::app('name') resolving to a platform-aware sender — is the right seam; it keeps provider-specific concerns out of application code and makes multi-provider routing a config decision rather than a code branch.

Integration feasibility. Two blockers gate adoption and both are logistics, not architecture:

• Distribution. Until both packages are on Packagist, the package's own composer.json resolves the core from a sibling checkout via a path repository. The notes state consumers' Composer ignores that entry, which means the integration package is effectively unpublishable/uninstallable in a normal CI or production pipeline today. This must be confirmed as resolved before any sprint commitment.
• Version floor. PHP 8.4+, Laravel 12 or 13. PHP 8.4 as a hard minimum excludes estates still on 8.2/8.3, and the Laravel 12/13 window is narrow enough that this package must be verified against the specific Laravel minor in use. Treat the PHP 8.4 upgrade as a prerequisite work item with its own cost, not as a given.

Technical risk.

• Pre-1.0 on both packages. 0.1.0 and ^0.1.2 carry no semver stability guarantee. Any minor bump can break the API. Pin exact versions and treat upgrades as deliberate change requests.
• Two-package surface. The integration and core version independently; upgrade compatibility is a matrix the team owns, not something the vendor guarantees at 0.x.
• Credential handling. Config accepts either a path or inline PEM/JSON. Inline secrets in config risk leaking through config:cache artifacts, log context, or VCS. The claim that secrets-manager values "work as-is" needs verification of exactly where the value is dereferenced and whether it ever lands in a cached config file.
• Token cache correctness. Provider/access tokens are shared across workers through "any Laravel cache store." JWT/OAuth expiry, clock skew, and non-atomic cache stores are the classic failure vectors here. A store without atomic add/lock semantics can produce a token-refresh stampede against the provider.
• Sandbox fallback is a correctness-versus-cost trade: it doubles round trips on a specific failure class and can mask a genuine production token problem as "handled."
• Bus factor. Single-maintainer OSS with no stated support model. The package is small enough to fork, which is the real mitigation, but that decision should be conscious.

Key questions.

1. Packagist publication date for both packages — is this a days or quarters problem?
2. What is the actual Laravel 13 release timeline, and is the constraint ^12.0|^13.0 or narrower?
3. Which cache stores are validated for the token cache, and is there locking to prevent refresh stampedes?
4. How are credentials resolved — at config load or at send time — and can a secrets-manager reference avoid materializing the PEM in cached config?
5. What is the BC/deprecation policy between 0.x minors, and is there a security disclosure channel?
6. On partial fan-out failure, are events emitted per target, and does the channel throw only when zero targets were reached? Duplicate-send behavior on queue retry needs to be explicit.
7. License and any usage restrictions?

Integration Approach

Stack fit. Best fit is a Laravel 12 application already on PHP 8.4 with queue workers and a shared cache backend (Redis is the natural choice given the token-cache requirement). It is a poor fit for anything mid-way through a PHP or Laravel major upgrade, and it is not usable at all until Packagist distribution is confirmed.

Migration path. Assume an existing laravel-notification-channels/apn + FCM setup or a homegrown sender:

1. Parallel, not replacement. Stand up the new package behind a config flag alongside the incumbent. Both send; compare delivery outcomes for a sample of traffic.
2. Token store is the migration. The durable device-token table is the asset that matters. Map the existing token rows into the new app-scoped shape first, before any sends move. DeviceTokenUnregistered should be wired to the existing cleanup job so token hygiene behavior is unchanged during the transition.
3. Cut over one notification at a time, lowest-risk first (non-transactional, non-time-sensitive).
4. Retire the incumbent only after the event stream and delivery metrics match for a full release cycle.

Compatibility. Pin exact versions (0.1.0 / core 0.1.2). Record the PHP and Laravel constraint in the dependency policy so the Laravel 13 upgrade is not accidentally blocked by this package. Verify against the exact Laravel minor in production, not just the major.

Sequencing.

1. Confirm Packagist availability and successful composer require from a clean environment (including CI).
2. Spike in a non-production app: php artisan push:test against both APNs and FCM with real credentials — this validates the credential-resolution path end to end and is the single highest-value 30-minute check.
3. Wire config with credentials sourced from the secrets manager, not inline; verify config:cache output contains no secret material.
4. Register event listeners for NotificationSent/NotificationFailed/DeviceTokenUnregistered and point them at existing telemetry and token-cleanup jobs.
5. Adopt the channel for one notification; add Push::fake() assertions to that feature's tests so the pattern is established.
6. Expand per app/brand; leave sandbox fallback off initially, enable only if Xcode-build tokens are a real support burden.

Operational Impact

Maintenance. Two 0.x dependencies to track, both single-vendor. Budget for reading release notes on every bump and for occasional forced upgrades. Because the surface is small and pure PHP, a one-time code read to establish internal ownership is cheap insurance against maintainer disappearance; decide explicitly whether the fallback is fork-and-vendor or rewrite.

Support. No commercial support. Your team owns debugging provider edge cases — APNs 410s, FCM UNREGISTERED noise, bad-token vs. bad-credential disambiguation. push:test is a genuine operational win here and should be documented in the runbook as the first diagnostic step for "pushes stopped."

Scaling. Three things scale with the app, not linearly with traffic:

• Connections. Clients live for the life of the process, so connection count tracks worker count, not send volume. This is efficient under load but means a large worker fleet holds a proportional number of long-lived provider connections. Check provider connection limits at your worker tier.
• Cache is now a critical path. The token cache store becomes a hard dependency for every send. A cache outage or eviction storm degrades to auth failures or refresh stampedes, not a graceful slowdown. Treat it as a Tier-1 dependency with its own monitoring.
• Concurrency on fan-out. Targets grouped by app and sent concurrently means a large broadcast becomes a burst against the provider. Rate-limit awareness belongs in the application layer, not here.

Failure modes to instrument.

• Credential rotation with process-lifetime clients. Rotating an APNs key or FCM service account does not take effect in running workers until they restart. This is the sharpest operational edge in the release: document a mandatory worker restart in the rotation runbook.
• Duplicate sends on queue retry. The channel throws only when a send reached nobody with a retryable failure — good design, but a retry after a partial success can re-deliver to targets that already received the push. Confirm idempotency expectations with product; users noticing double pushes is a support-ticket generator.
• Token-cleanup event storms. A malformed config or a swapped APNs environment can produce a flood of DeviceTokenUnregistered events and wipe live tokens. Rate-limit the listener and alert on anomalous volume before it acts.
• Sandbox fallback ambiguity. A production push silently answered from the sandbox will look "delivered" in your metrics while the real device never got it. If enabled, tag fallback deliveries in telemetry.
• Silent config drift. Inline PEM in config plus config:cache is the most likely place a secret leaks into a build artifact; add a CI check.

Ramp-up. Small, well-shaped API surface: a config block, a channel, three events, a fake, and one artisan command. A Laravel-fluent engineer is productive in a day and confident in a week. The learning curve is not the package — it is provider semantics (APNs token-vs-certificate auth, sandbox vs. production gateways, FCM registration-token lifecycle). Allocate the ramp-up budget to that, and have the migrating engineer own the token-cleanup listener work so the provider knowledge stays in one head at first.

Recommendation. Architecturally sound and a clean fit for Laravel's notification pipeline; the risk is entirely in distribution readiness, version floors, and 0.x volatility. Gate on Packagist availability and a passed push:test spike, pin versions, and adopt behind a flag — do not commit to it as a hard dependency while both packages are pre-1.0 and unpublished.