Pushok Laravel Package

Technical Evaluation

Architecture fit. Pushok is a framework-agnostic PHP library, not a Laravel package — there is no ServiceProvider, facade, publishable config, or queue integration. Within a Laravel codebase it belongs at the transport layer beneath a domain notification service. The fluent payload builder and explicit Client/Notification abstraction map cleanly onto a domain-oriented sender, but the team must own the wrapper (config, DI binding, channel adapter). A TPM should scope this as "library + thin in-house integration layer," not "drop-in Laravel package."

Integration feasibility. Low-to-moderate. Composer install is trivial; the real prerequisites are deployment-level: ext-curl compiled with HTTP/2 (nghttp2) and ext-openssl for ES256 JWT signing. Authentication is either a .p8 provider key (key ID + team ID, preferred) or a legacy .p12 certificate, with sandbox/production endpoints selectable. Realistic first integration effort is 1–2 engineering days for a wrapper plus smoke test.

Technical risk.

• Bus factor. Single maintainer, ~400 stars, low ecosystem gravity. Pin a version and keep a fallback (fork or an alternative APNs client) in the risk register.
• Host requirements. Missing HTTP/2 in curl is the most common silent failure; must be validated in CI and on every deploy target.
• Token lifecycle. JWT provider tokens have ~1-hour TTL and require accurate system clocks; incorrect caching/regeneration is a latent outage.
• No built-in operational policy. No retry/backoff, queue semantics, token pruning, or rate limiting — all must be built around it.
• Maintenance cadence. Release dates suggest activity but no institutional backing; treat as a pinned dependency rather than a foundation.

Key questions.

• Which auth path — token (.p8) or certificate — and who owns key rotation?
• Are we integrating Pushok directly, or via laravel-notification-channels/apn (which wraps it)? Decide before building a channel adapter.
• Do target hosts guarantee HTTP/2-capable curl and ES256 openssl?
• Do we need VoIP (PushKit) or silent/background pushes, which carry stricter Apple-side delivery semantics?
• What reliability SLA do we need versus the library's maintenance trajectory?

Integration Approach

Stack fit. Laravel 8–11 / PHP 7.4–8.3. Bind a configured Pushok Client as a singleton in a small ServiceProvider, expose config/pushok.php backed by env vars (APNS_KEY_ID, APNS_TEAM_ID, APNS_KEY_PATH, APNS_BUNDLE_ID, APNS_SANDBOX). Wrap sends in queued jobs and add a Laravel Notification channel so product teams send APNs the same way they send mail. Exploit HTTP/2 multiplexing to batch multiple device tokens over one connection.

Migration path. If the org already uses laravel-notification-channels/apn, Pushok is the underlying driver — keep the channel and don't rebuild. For greenfield, build the config wrapper + channel adapter rather than forking. Abstract sends behind a PushNotifier interface so the transport can be swapped without touching product code.

Compatibility. Validate curl HTTP/2, openssl ES256, PHP version, and any HTTP-client version conflicts Pushok pins. Confirm the .p8 format matches Apple's. Test both api.push.apple.com and api.sandbox.push.apple.com; never let sandbox tokens leak into production.

Sequencing.

1. Credential provisioning + config wrapper + DI binding.
2. Sandbox smoke test to a single real device.
3. Queued job + Notification channel adapter.
4. Payload contract and validation (size limits, required aps keys).
5. Error-response mapping and observability.
6. Per-app production cutover with rollback.

Operational Impact

Maintenance. Pin the version, track releases, and maintain a documented fallback path. Own a credential-rotation runbook (.p8 keys, certificate expiry, key IDs). Watch PHP/curl upgrades that could silently drop HTTP/2 support.

Support. The library returns structured APNs errors but no operational policy — build a translation layer: BadDeviceToken/Unregistered → prune token; ExpiredProviderToken → refresh JWT; TooManyRequests → backoff; PayloadTooLarge → tighten payload guards. Capture the apns-id header for tracing. Document an on-call playbook.

Scaling. Reuse a single client/connection per process to benefit from HTTP/2 multiplexing. Scale via queue workers, but note each send is a stream — a burst of workers can trigger TooManyRequests. Add per-token dedup and rate limiting. Silent/background and VoIP payloads have distinct throttling behavior on Apple's side.

Failure modes. Stale connections after idle periods (reconnect logic), clock skew invalidating JWTs, sandbox/production mismatch (BadEnvironment), expired credentials, oversized payloads (>4KB), and Apple's opportunistic delivery of silent pushes. Each should map to a distinct alert and remediation.

Ramp-up. Modest: a mid-level Laravel developer can integrate in a few days. The real learning is APNs auth semantics (.p8 vs .p12), HTTP/2 host prerequisites, and Apple's error taxonomy. Investing in an internal runbook before production cuts the on-call cost of the inevitable auth/throttling incidents.