Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/mrgarest/laravel-firebase-sender

Laravel library for sending notifications with Firebase Cloud Messaging (FCM)
https://github.com/mrgarest/laravel-firebase-sender

fcm fcm-notifications firebase laravel laravel-package php

Last synced: 6 months ago
JSON representation

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

Awesome Lists containing this project

README 

          
# Laravel Firebase Sender



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](https://github.com/mrgarest/laravel-firebase-sender/blob/master/migrating-to-v3.md)._



### 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](https://www.youtube.com/watch?v=aeBiLIw2KnY)._



## Usage



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



```php

$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.



```php

$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:



```php

$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:



```php

$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.



```php

$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.



```php

$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).



```php

$firebaseSender->setApns(new ApnsPush(

    title: 'TITLE',

    body: 'BODY'

));

```



### Send a notification



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



```php

$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](https://laravel.com/docs/12.x/queues) must be configured in your Laravel project.



```php

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

```



This method takes one required value and two optional values.



| Value          | Type     | Required | Description                                                    |

| -------------- | -------- | -------- | -------------------------------------------------------------- |

| `$scheduledAt` | `Carbon` | Yes      | Date when notification should be sent                          |

| `$chunkLength` | `int`    | No       | Allows you to split messages into chunks                       |

| `$maxRand`     | `int`    | No       | Adds a random number of seconds to the chunk dispatch schedule |



### Clear



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



```php

$firebaseSender->clear(): void

```



### Grouping



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



```php

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

```



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



Example of sending group notifications:

```php

$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.



```php

$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.



```php

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

```



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



```php

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

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

```



### FirebaseSenderLog Query Scopes



#### messageId



Filter logs by the message ID.



```php

$query->messageId(45543643);

```



#### serviceAccount



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



```php

$query->serviceAccount('MY_SERVICE_ACCOUNT_NAME');

```



#### deviceToken



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



```php

$query->deviceToken('DEVICE_TOKEN');

```



#### Topic



Filters records where the topic exactly matches the value passed.



```php

$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.



```php

$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:



```php

$query->matchTopic(

    'TOPIC_NAME',

    true

);

```



#### Payload



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



```php

$query->payload1('language');

```



#### createdBetween



Filter logs created between two dates.



```php

$query->createdBetween(

    Carbon::now(),

    Carbon::now()->subHours(1)

);

```



#### sentBetween



Filter logs where the notification was sent between two dates.



```php

$query->sentBetween(

    Carbon::now(),

    Carbon::now()->subHours(1)

);

```



#### scheduledBetween



Filter logs where the notification was scheduled between two dates.



```php

$query->scheduledBetween(

    Carbon::now(),

    Carbon::now()->subHours(1)

);

```



#### failedBetween



Filter logs where the notification failed between two dates.



```php

$query->failedBetween(

    Carbon::now(),

    Carbon::now()->subHours(1)

);

```