Fcm Laravel Laravel Package

Getting Started

• Install with composer require amdad121/fcm-laravel. Publish the config (php artisan vendor:publish --provider="Amdad121\Fcm\FcmServiceProvider" — confirm the provider namespace in the v2 README) and open config/fcm.php first.
• v2 is a major release and targets Firebase Cloud Messaging HTTP v1. You need a Firebase service account JSON (Firebase Console → Project Settings → Service Accounts → Generate new private key), not the legacy server key. Set the credentials path/JSON and project ID via env/config.
• First use case: send a test notification to one device token from a tinker session or a temporary route, then confirm delivery in the Firebase Console. Method names may have changed in v2, so cross-check the README and the v1.3.0...v2.0.0 compare diff before wiring it into app code.
• Look first at the compare diff on GitHub. The release notes are only a changelog link, so the diff and README are the source of truth for breaking changes.

Implementation Patterns

• Wrap the package in a small application service (e.g. PushNotifier) instead of calling the facade from controllers. Inject the service so tests can swap it and payload construction stays in one place.
• Send from queued jobs or ShouldQueue notifications. FCM HTTP v1 calls are synchronous; queueing keeps request latency and FCM outages out of your web path.
• For Laravel notifications, add a custom channel that delegates to the package. Keep the package call in the channel's send method and map toFcm/toArray on the notifiable.
• Store device tokens in a dedicated table (user_id, token, platform, last_seen_at, revoked_at). Upsert on login/app open; delete or revoke on logout.
• For multicast sends, chunk token lists (e.g. 500 per job) and dispatch one job per chunk. Handle partial failures per chunk rather than treating the batch as all-or-nothing.
• Prefer topic sends over looping large token lists when your audience maps to a topic. Manage subscriptions in a dedicated job or admin action.
• Put the package behind an interface and bind a fake in tests. Assert that your job dispatched and the payload shape is correct; avoid hitting FCM from the test suite.

Gotchas and Tips

• v2.0.0 is a breaking major. The sparse release notes mean you must read the compare diff. Expect credential changes (service account/OAuth2 instead of a server key), possible config key renames, and HTTP v1 payload differences (message.token instead of to, notification/data placement, android/apns/webpush blocks). Do not upgrade production without a staging send.
• The legacy FCM server-key API is retired. If your app still uses a server key, v2 will not work until you migrate to a service account.
• Error handling matters: treat UNREGISTERED/INVALID_ARGUMENT as a reason to delete or quarantine the token; treat UNAVAILABLE/INTERNAL as retryable with backoff. Log the FCM error code, not just the human-readable message.
• Tokens rotate. Upsert tokens on app open, prune stale ones, and revoke locally when FCM returns UNREGISTERED.
• Keep data payloads small (~4KB limit); don't put large blobs in data.
• Debug by logging the full FCM response around your send call and checking storage/logs/laravel.log plus the Firebase Console delivery reports. A failed send often returns a useful error code that the package may not surface by default.
• Extension points: publish and edit config/fcm.php; if the package exposes a custom HTTP client or payload builder, use it to add analytics labels and platform-specific blocks without forking.
• Pin the major version (^2.0) and budget time to diff v1.3.0...v2.0.0 yourself before upgrading; the release notes alone are not enough to assess migration risk.