Push Notification Laravel Package

Getting Started

1. Install and confirm discovery. composer require asacanell/push-notification. Check vendor/asacanell/push-notification/composer.json for the service provider and facade FQCNs; on Laravel ≥5.5 they should be auto-discovered. If not, register them manually in config/app.php.
2. Publish config. Run php artisan vendor:publish --provider="ASacanell\PushNotification\PushNotificationServiceProvider" (use the exact provider from the package's composer.json) and inspect the generated config file. Expect two credential blocks: an FCM/GCM server key for Android and an APN certificate path + passphrase for iOS.
3. Wire credentials through .env, not the config file, so staging and production can differ. For APN, use an absolute path to the .pem/.p8 and confirm the sandbox vs. production gateway setting before your first send.
4. First use case: persist a device token when a user logs in (a device_tokens table keyed to user_id, token, platform), then send a single test push to one token through the package's facade/client class and log the raw transport response. Do this before building anything else — it tells you immediately whether the package is still viable against current FCM/APN endpoints.

Look first at the package's src/ client class to see which HTTP endpoint it calls. That single detail determines whether the package is usable today (see Gotchas).

Implementation Patterns

• Wrap the package in your own service. Never call the facade directly from controllers. Create an PushService or action class with sendToUser(User $user, string $title, string $body, array $data = []) that resolves tokens, splits by platform, and delegates. This isolates you from the package's API and lets you swap it later.
• Route by platform explicitly. Don't rely on the package to infer transport from the token. Query tokens with their platform column and call the FCM path for android and the APN path for ios. Mixed sends to a single call are the most common source of silent no-ops.
• Queue every send. Wrap the service call in a ShouldQueue job. Push sending is network I/O with third-party latency; doing it inline in a request will bite you under load. Set $tries = 3 and a backoff() of 30–60s.
• Integrate with Laravel Notifications. Add a custom NotificationChannel whose send() calls your PushService. You then get via() routing, toPush() payload shaping, and Notification::fake() in tests for free — which this package almost certainly does not provide out of the box.
• Batch and chunk. For fan-out (e.g., a topic to 10k users), chunk tokens into groups of ~500–1000 per request rather than looping one-by-one; both FCM and APN punish per-message round trips.
• Test against a fake. Because there is likely no built-in fake, bind a no-op implementation of your PushService interface in the test container, or use Http::fake() if the package uses the Laravel HTTP client. Assert on your service, not the package.

Gotchas and Tips

• Verify the FCM endpoint before committing. Many 2023-era packages post to the legacy https://fcm.googleapis.com/fcm/send with Authorization: key=<server-key>. Google shut that API down; those calls now fail. If the package does not speak FCM HTTP v1 with OAuth2 service-account credentials, treat it as non-functional for Android and budget to fork or replace it (kreait/firebase-php or laravel-notification-channels/fcm are the usual substitutes).
• APN auth mode matters. Certificate-based .pem auth expires yearly and breaks silently; if the package supports .p8 token auth, prefer it. If it only supports certificates, put the expiry date on a calendar and monitor for auth failures.
• Handle token invalidation. FCM returns UNREGISTERED/NotRegistered and APN returns 410 Unregistered. Parse the response and delete dead tokens — the package will not do this for you. Without it your token table rots within weeks.
• Payload limits and keys differ per platform. FCM caps at ~4KB; APN at 4KB. sound, badge, and content-available are APN-only; priority and notification vs. data blocks are FCM-only. Build platform-specific payloads in your service rather than passing one array through.
• Silent/data pushes are not guaranteed. On iOS, content-available: 1 is throttled and dropped by the OS; on Android, data-only messages need priority: high to wake the device. Don't use either for anything transactional.
• Config caching. After changing credentials: php artisan config:clear && php artisan config:cache. Cert paths that work in php artisan serve often fail under a queue worker running as a different user with a different working directory — use absolute paths.
• It is effectively unmaintained. Zero stars, zero dependents, last release March 2023. Pin the exact version in composer.json, and if you adopt it, fork it into your own VCS so a Packagist deletion doesn't break your build. Audit composer.json for PHP/Laravel version constraints before assuming it runs on Laravel 11/12.
• Debugging: log the full raw response body from both transports before parsing. Most failures here are 401/403 (bad key or expired cert) or 404 (dead endpoint), and the package's own error reporting is likely to swallow these into a boolean false.