README

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

❗️ This library only works with the new FCM HTTP v1 API ❗️

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

Supported platforms

✅	Platform
✅	Apns
✅	Android
✅	WebPush

Installation

You can install the package via composer:

composer require mrgarest/laravel-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.

If you don't know how to get a Service account, here is a video from YouTube.

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();

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::now()->addHours(1));

Custom message

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

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

When using setMessage(), the setNotification(), setAndroid() and setApns() methods will not work.

Auth Token

In some cases, you may need an Auth Token for Firebase, and it can be obtained separately without sending any notifications using the getAuthToken() method.

$auth = $firebaseSender->getAuthToken();

Example of a successful response:

[
  "access_token" => "access_token"
  "expires_in" => 3599
  "token_type" => "Bearer"
]

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 add notification information to the log, you'll need to use an additional method before sending notifications:

$firebaseSender->setLog(
    true,
    'language',
    'en'
);

The setLog method takes three arguments:

enabled - enables or disables logging. If set to true, information about the notification will be written to the database log.
payload1 and payload2 - additional values that will be stored in the log. You can use it to store your own data (for example, a unique identifier or tag) to facilitate identification or filtering of notifications.

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)
);

mrgarest / laravel-firebase-sender

Maintainers

Details