README

A simple and flexible Laravel package for sending Firebase Cloud Messaging (FCM) notifications using a Firebase Service Account. Supports both direct (instant) and queued (asynchronous) notifications — including topic-based broadcasts.

🧩 Features

• ✅ Send notifications to individual devices or specific topics
• ✅ Supports queued notifications for scalable delivery
• ✅ Uses Firebase Admin REST API v1 (no legacy FCM keys)
• ✅ Fully configurable via .env
• ✅ Compatible with Laravel 9, 10, and 11

📦 Installation

Install via Composer:

composer require kz370/laravel-firebase-notifications

⚙️ Configuration

Publish the configuration file:

php artisan vendor:publish --provider="Kz370\FirebaseNotifications\FirebaseNotificationServiceProvider" --tag=config

This creates config/firebase-notifications.php.

.env Setup

Add your Firebase credentials and project ID:

FIREBASE_SERVICE_ACCOUNT=storage/app/firebase-service-account.json
FIREBASE_PROJECT_ID=your-firebase-project-id

💡 Tip: Download your Firebase service account key from Project Settings → Service Accounts → Generate New Private Key

🚀 Usage Examples

Send Notification to a Specific Device

use FirebaseNotification;

$deviceToken = 'your-device-token-here';

FirebaseNotification::sendNotification(
    $deviceToken,
    'Hello there!',
    'Welcome to our platform 🎉',
    'https://example.com/welcome-banner.png',
    ['type' => 'welcome', 'user_id' => 123]
);

Method: sendNotification()

This method sends a push notification directly to a specific device using its FCM device token.

sendNotification(
    string $deviceToken,
    string $title,
    string $body,
    ?string $imageUrl = null,
    array $data = []
): array

Parameters:

Send Notification to a Topic

You can send notifications to any topic your users have subscribed to. By default, the topic is "all" — but you can specify your own.

FirebaseNotification::sendNotificationToTopic(
    'System Update',
    'We're upgrading our system tonight.',
    'https://example.com/update-banner.png',
    ['maintenance_mode' => true],
    'news'
);

This will send the notification to all users subscribed to the topic news.

Method: sendNotificationToTopic()

sendNotificationToTopic(
    string $title,
    string $body,
    ?string $imageUrl = null,
    array $data = [],
    string $topic = 'all'
): array

Parameters:

⏳ Using Queues

You can queue notifications for background processing using Laravel's queue system.

Queue Single Device Notification

use Kz370\FirebaseNotifications\Jobs\FirebaseNotificationJob;

FirebaseNotificationJob::dispatch(
    $deviceToken,
    'Queued Message',
    'This notification is sent via the queue!'
);

Queue Topic Notification

FirebaseNotificationJob::dispatch(
    null,
    'Breaking News',
    'Something big just happened!',
    null,
    ['category' => 'news'],
    true // Indicates it's for a topic
);

Delay Notification

FirebaseNotificationJob::dispatch(
    $deviceToken,
    'Reminder',
    'Your session starts soon.'
)->delay(now()->addMinutes(10));

Make sure your queue worker is running:

php artisan queue:work

⚡ Configuration Overview

config/firebase-notifications.php

return [
    'service_account_path' => env('FIREBASE_SERVICE_ACCOUNT', storage_path('app/firebase-service-account.json')),
    'project_id' => env('FIREBASE_PROJECT_ID', 'your-project-id'),
];

🧰 Troubleshooting

invalid_grant or unauthorized_client

Check that your Firebase service account JSON file is valid and the .env path is correct.

Notification not delivered

• The device token must be valid and active
• Ensure the app is subscribed to the topic you're sending to
• The Firebase Cloud Messaging API must be enabled in Google Cloud Console

Queues not processing

Run your queue worker:

php artisan queue:work

🪪 License

This package is open-source software licensed under the MIT License.

✨ Author

KZ370
💻 Laravel Developer