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:

Parameter	Type	Required	Description
`$deviceToken`	`string`	✅	The Firebase device token that identifies a specific user's device. You typically get this from your mobile app's Firebase SDK.
`$title`	`string`	✅	The title text of the notification, usually displayed in bold (e.g., "New Message").
`$body`	`string`	✅	The main message content or body text of the notification.
`$imageUrl`	`string\|null`	❌	(Optional) URL of an image to display in the notification if supported by the client app.
`$data`	`array`	❌	(Optional) A custom key-value data payload sent alongside the notification. Useful for deep links or background processing.

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:

Parameter	Type	Required	Description
`$title`	`string`	✅	The notification title shown in the header (e.g., `"System Update"`)
`$body`	`string`	✅	The main notification body text (e.g., `"We're upgrading our system tonight."`)
`$imageUrl`	`string\|null`	❌	Optional image URL to display in the notification (if supported)
`$data`	`array`	❌	Custom key-value payload for background handling or deep linking
`$topic`	`string`	❌	Target topic (default: `"all"`)

⏳ 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

kz370 / laravel-firebase-notifications

Maintainers

Details