README

Laravel library for sending notifications with Firebase Cloud Messaging (FCM).

If you have previously used the old version of v2, you should read the instructions for migrating to v3.

⚠️ IMPORTANT UPDATE: This package has been renamed from mrgarest/laravel-firebase-sender to garest/firebase-sender.

Supported platforms

Installation

You can install the package via composer:

composer require garest/firebase-sender

Configuration

After installing the package, you will need to publish the configuration file firebase-sender.php

php artisan vendor:publish --tag=firebase-sender-config

After publishing the configuration file, you need to open it and add the Service account data from the Firebase console.

Usage

FirebaseSender is a class that is responsible for sending notification to devices via Firebase Cloud Messaging (FCM) using a service account with Firebase.

$firebaseSender = new FirebaseSender('MY_SERVICE_ACCOUNT_NAME');

MY_SERVICE_ACCOUNT_NAME - the identifier of your service account registered in the firebase-sender.php configuration.

Send a notification to a specific device

To send a notification directly to the device, use the setDeviceToken method, passing in a unique device token generated by Firebase.

$firebaseSender->setDeviceToken('DEVICE_TOKEN');

Note that you can use either setDeviceToken or setTopic. You cannot use both methods.

Send a notification on a specific topic

To send a notification to all devices subscribed to a specific topic, use the setTopic() method, passing the topic name as a string:

$firebaseSender->setTopic('TOPIC_NAME');

Topic conditions

The TopicCondition class allows you to create complex logical conditions for determining the topics to which a notification will be sent.

To send a notification to a combination of topics, you need to build a boolean expression that describes the target topics. The expression can contain the AND (&&) and OR (||) operators, as well as grouping using parentheses.

For example, to send a notification to devices subscribed to topicA and (topicB or topicC), you can build the following expression:

$firebaseSender->setTopic(TopicCondition::make()
    ->topic('topicA')
    ->and()
    ->group(fn($group) => $group->topic('topicB')->or()->topic('topicC'))
);

Set notifications

The setNotification method allows you to set the main content of the notification that will be sent through Firebase.

$firebaseSender->setNotification(new NotificationPush(
    title: 'TITLE',
    body: 'BODY'
));

Set notifications for Android

The setAndroid method allows you to set the notification content for Android devices.

$firebaseSender->setAndroid(new AndroidPush(
    title: 'TITLE',
    body: 'BODY'
));

Set notifications for APNs

The setApns method allows you to set the notification content for APNs (Apple Push Notification Service).

$firebaseSender->setApns(new ApnsPush(
    title: 'TITLE',
    body: 'BODY'
));

Send a notification

After configuring the notification, you can send it by calling the send method.

$firebaseSender->send(): SendReport

If you don't want to send the message immediately, but want to schedule it for later, you can use the sendJob method. To use this method, queues must be configured in your Laravel project.

$firebaseSender->sendJob(Carbon $scheduledAt, int $chunkLength = 10, int $maxRand = 0): void

This method takes one required value and two optional values.

Clear

When you need to send new notifications, you can simply clear the previously sent data without having to re-announce the class.

$firebaseSender->clear(): void

Grouping

Using the setGroup grouping method, you can send multiple messages at once by combining messages into groups.

$firebaseSender->setGroup(int $index): void

Each group must have its own index, recipient, and message body.

Example of sending group notifications:

$firebaseSender = new FirebaseSender('MY_SERVICE_ACCOUNT_NAME');

$firebaseSender->setGroup(0);
$firebaseSender->setDeviceToken("MY_DEVICE_TOKEN_1");
$firebaseSender->setNotification(new NotificationPush(
    title: "Lorem ipsum",
    body: 'Lorem ipsum dolor sit amet consectetur adipisicing elit.',
));

$firebaseSender->setGroup(1);
$firebaseSender->setDeviceToken("MY_DEVICE_TOKEN_2");
$firebaseSender->setNotification(new NotificationPush(
    title: "Lorem ipsum",
    body: 'Lorem ipsum dolor sit amet consectetur adipisicing elit.',
));

$firebaseSender->send();

Custom messages

With this method, you can specify a custom data structure for the messages to be sent through FCM. This can be useful for sending additional information that is not included in the standard notification options.

$firebaseSender->setMessages([
    [
        'token' => 'DEVICE_TOKEN',
        'notification' => [
            'title' => 'TITLE',
            'body' => 'BODY'
        ]
    ]
]);

When using setMessages, the setNotification, setAndroid and setApns methods will not work.

Localized notifications

AndroidPush and ApnsPush support sending localized notifications, which allows you to dynamically display text depending on the user's language.

To do this, use the titleLocKey and bodyLocKey parameters, which specify the keys to localized strings in your application's resources.

You can also specify the titleLocArgs and bodyLocArgs parameters, which can be used to pass values that will be inserted into localized notification templates.

Notification log

If you want to use the log of sent notifications, you will also need to publish the migration file and perform the migration.

php artisan vendor:publish --tag=firebase-sender-migrations

php artisan make:migration

To store information about sent notifications in the database, you can enable the event log.

$firebaseSender->logEnabled(bool $enabled = true): void

The event log also supports two additional methods for adding payloads to the log.

$firebaseSender->setPayload1(?string $payload = null): void
$firebaseSender->setPayload2(?string $payload = null): void

FirebaseSenderLog Query Scopes

messageId

Filter logs by the message ID.

$query->messageId(45543643);

serviceAccount

Filter logs by the service account used to send the notification.

$query->serviceAccount('MY_SERVICE_ACCOUNT_NAME');

deviceToken

Filter logs by the device token (for notifications sent to a specific device).

$query->deviceToken('DEVICE_TOKEN');

Topic

Filters records where the topic exactly matches the value passed.

$query->topic('TOPIC_NAME');

If you need to search for a topic that may appear as part of a condition, use the matchTopic method. It allows matching both exact topics and topics used in conditions.

$query->matchTopic('TOPIC_NAME');

By default, matchTopic checks for both exact and conditional matches. If you want to search only within conditions, pass true as the second argument:

$query->matchTopic(
    'TOPIC_NAME',
    true
);

Payload

payload1 and payload2 filter logs by the first value of the user payload.

$query->payload1('language');

createdBetween

Filter logs created between two dates.

$query->createdBetween(
    Carbon::now(),
    Carbon::now()->subHours(1)
);

sentBetween

Filter logs where the notification was sent between two dates.

$query->sentBetween(
    Carbon::now(),
    Carbon::now()->subHours(1)
);

scheduledBetween

Filter logs where the notification was scheduled between two dates.

$query->scheduledBetween(
    Carbon::now(),
    Carbon::now()->subHours(1)
);

failedBetween

Filter logs where the notification failed between two dates.

$query->failedBetween(
    Carbon::now(),
    Carbon::now()->subHours(1)
);

Google Access Token

If you only need an access token from Google to send messages from other platforms or for any other purpose, you can use the following example:

use Garest\FirebaseSender\Facades\GoogleApi;
use Garest\FirebaseSender\Facades\ServiceAccount;

$account = ServiceAccount::getByName('MY_SERVICE_ACCOUNT_NAME');
$token = GoogleApi::getAccessToken($account);

Events

When Firebase returns an error during sending (for example, invalid token or quota exhausted), the package generates a Garest\FirebaseSender\Events\FirebaseMessageFailed event. You can subscribe to this event to perform some actions.