PHPackages                             chinhnh/laravel-fcm - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Mail &amp; Notifications](/categories/mail)
4. /
5. chinhnh/laravel-fcm

ActiveLibrary[Mail &amp; Notifications](/categories/mail)

chinhnh/laravel-fcm
===================

Laravel / Lumen package for Firebase Cloud Messaging

v1.2.5(8y ago)19MITPHPPHP &gt;=5.5.9

Since Jun 29Pushed 8y agoCompare

[ Source](https://github.com/chinhnh93/Laravel-FCM)[ Packagist](https://packagist.org/packages/chinhnh/laravel-fcm)[ RSS](/packages/chinhnh-laravel-fcm/feed)WikiDiscussions master Synced today

READMEChangelogDependencies (7)Versions (14)Used By (0)

Laravel-FCM
===========

[](#laravel-fcm)

[![Build Status](https://camo.githubusercontent.com/77ba258fbdc6f90aa2574a853e9f0ea6bbf63f1aa669830c754719d158e3790e/68747470733a2f2f7472617669732d63692e6f72672f62726f7a6f742f4c61726176656c2d46434d2e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/brozot/Laravel-FCM) [![Coverage Status](https://camo.githubusercontent.com/37b515c774c0ab8681fe834ea136c43a40485813465edc73f1e8fe89eed559f4/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f62726f7a6f742f4c61726176656c2d46434d2f62616467652e7376673f6272616e63683d6d6173746572)](https://coveralls.io/github/brozot/Laravel-FCM?branch=master) [![Latest Stable Version](https://camo.githubusercontent.com/3e37decb1e399ff0be363ad1c049783e095788283ea10c0a3dcdd427584fd238/68747470733a2f2f706f7365722e707567782e6f72672f62726f7a6f742f6c61726176656c2d66636d2f762f737461626c65)](https://packagist.org/packages/brozot/laravel-fcm) [![Total Downloads](https://camo.githubusercontent.com/9a404bedf02e4c00aff2aa9778e6eff3f278d760b7697a5d4ca7847a607c2b3a/68747470733a2f2f706f7365722e707567782e6f72672f62726f7a6f742f6c61726176656c2d66636d2f646f776e6c6f616473)](https://packagist.org/packages/brozot/laravel-fcm)[![License](https://camo.githubusercontent.com/b60009c61d12b84b2536d6424619974997684fcc36e8a9a41d1ca40694aea2d9/68747470733a2f2f706f7365722e707567782e6f72672f62726f7a6f742f6c61726176656c2d66636d2f6c6963656e7365)](https://packagist.org/packages/brozot/laravel-fcm)

Introduction
------------

[](#introduction)

Laravel-FCM is an easy to use package working with both Laravel and Lumen for sending push notification with [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging/) (FCM).

It currently **only supports HTTP protocol** for :

- sending a downstream message to one or multiple devices
- managing groups and sending message to a group
- sending topics messages

> Note: The XMPP protocol is not currently supported.

Installation
------------

[](#installation)

To get the latest version of Laravel-FCM on your project, require it from "composer":

```
$ composer require brozot/laravel-fcm

```

Or you can add it directly in your composer.json file:

```
{
	"require": {
    	"brozot/laravel-fcm": "1.2.*"
	}
}

```

### Laravel

[](#laravel)

Register the provider directly in your app configuration file config/app.php `config/app.php`:

```
'providers' => [
	// ...

	LaravelFCM\FCMServiceProvider::class
]
```

Add the facade aliases in the same file:

```
'aliases' => [
	...
	'FCM'      => LaravelFCM\Facades\FCM::class,
	'FCMGroup' => LaravelFCM\Facades\FCMGroup::class, // Optional
]
```

> Note: The `FCMGroup` facade is needed only if you want to manage groups messages in your application.

Publish the package config file using the following command:

```
$ php artisan vendor:publish

```

### Lumen

[](#lumen)

Register the provider in your boostrap app file `boostrap/app.php`

Add the following line in the "Register Service Providers" section at the bottom of the file.

```
$app->register(LaravelFCM\FCMServiceProvider::class);
```

For facades, add the following lines in the section "Create The Application" . FCMGroup facade is only necessary if you want to use groups message in your application.

```
class_alias(\LaravelFCM\Facades\FCM::class, 'FCM');
class_alias(\LaravelFCM\Facades\FCMGroup::class, 'FCMGroup');
```

Copy the config file `fcm.php` manually from the directory `/vendor/brozot/laravel-fcm/config` to the directory `/config ` (you may need to create this directory).

### Package Configuration

[](#package-configuration)

In your `.env` file, add the server key and the secret key for the Firebase Cloud Messaging:

```
FCM_SERVER_KEY=my_secret_server_key
FCM_SENDER_ID=my_secret_sender_id
```

To get these keys, you must create a new application on the [firebase cloud messaging console](https://console.firebase.google.com/).

After the creation of your application on Firebase, you can find keys in `project settings -> cloud messaging`.

Basic Usage
-----------

[](#basic-usage)

Two types of messages can be sent using Laravel-FCM:

- Notification messages, sometimes thought of as "display messages"
- Data messages, which are handled by the client app

More information is available in the [official documentation](https://firebase.google.com/docs/cloud-messaging/concept-options).

### Downstream Messages

[](#downstream-messages)

A downstream message is a notification message, a data message, or both, that you send to a target device or to multiple target devices using its registration\_Ids.

The following use statements are required for the examples below:

```
use LaravelFCM\Message\OptionsBuilder;
use LaravelFCM\Message\PayloadDataBuilder;
use LaravelFCM\Message\PayloadNotificationBuilder;
use FCM;
```

#### Sending a Downstream Message to a Device

[](#sending-a-downstream-message-to-a-device)

```
$optionBuilder = new OptionsBuilder();
$optionBuilder->setTimeToLive(60*20);

$notificationBuilder = new PayloadNotificationBuilder('my title');
$notificationBuilder->setBody('Hello world')
				    ->setSound('default');

$dataBuilder = new PayloadDataBuilder();
$dataBuilder->addData(['a_data' => 'my_data']);

$option = $optionBuilder->build();
$notification = $notificationBuilder->build();
$data = $dataBuilder->build();

$token = "a_registration_from_your_database";

$downstreamResponse = FCM::sendTo($token, $option, $notification, $data);

$downstreamResponse->numberSuccess();
$downstreamResponse->numberFailure();
$downstreamResponse->numberModification();

//return Array - you must remove all this tokens in your database
$downstreamResponse->tokensToDelete();

//return Array (key : oldToken, value : new token - you must change the token in your database )
$downstreamResponse->tokensToModify();

//return Array - you should try to resend the message to the tokens in the array
$downstreamResponse->tokensToRetry();

// return Array (key:token, value:errror) - in production you should remove from your database the tokens
```

#### Sending a Downstream Message to Multiple Devices

[](#sending-a-downstream-message-to-multiple-devices)

```
$optionBuilder = new OptionsBuilder();
$optionBuilder->setTimeToLive(60*20);

$notificationBuilder = new PayloadNotificationBuilder('my title');
$notificationBuilder->setBody('Hello world')
				    ->setSound('default');

$dataBuilder = new PayloadDataBuilder();
$dataBuilder->addData(['a_data' => 'my_data']);

$option = $optionBuilder->build();
$notification = $notificationBuilder->build();
$data = $dataBuilder->build();

// You must change it to get your tokens
$tokens = MYDATABASE::pluck('fcm_token')->toArray();

$downstreamResponse = FCM::sendTo($tokens, $option, $notification, $data);

$downstreamResponse->numberSuccess();
$downstreamResponse->numberFailure();
$downstreamResponse->numberModification();

//return Array - you must remove all this tokens in your database
$downstreamResponse->tokensToDelete();

//return Array (key : oldToken, value : new token - you must change the token in your database )
$downstreamResponse->tokensToModify();

//return Array - you should try to resend the message to the tokens in the array
$downstreamResponse->tokensToRetry();

// return Array (key:token, value:errror) - in production you should remove from your database the tokens present in this array
$downstreamResponse->tokensWithError();
```

### Topics Messages

[](#topics-messages)

A topics message is a notification message, data message, or both, that you send to all the devices registered to this topic.

> Note: Topic names must be managed by your app and known by your server. The Laravel-FCM package or fcm doesn't provide an easy way to do that.

The following use statement is required for the examples below:

```
use LaravelFCM\Message\Topics;
```

#### Sending a Message to a Topic

[](#sending-a-message-to-a-topic)

```
$notificationBuilder = new PayloadNotificationBuilder('my title');
$notificationBuilder->setBody('Hello world')
				    ->setSound('default');

$notification = $notificationBuilder->build();

$topic = new Topics();
$topic->topic('news');

$topicResponse = FCM::sendToTopic($topic, null, $notification, null)

$topicResponse->isSuccess();
$topicResponse->shouldRetry();
$topicResponse->error());
```

#### Sending a Message to Multiple Topics

[](#sending-a-message-to-multiple-topics)

It sends notification to devices registered at the following topics:

- news and economic
- news and cultural

> Note : Conditions for topics support two operators per expression

```
$notificationBuilder = new PayloadNotificationBuilder('my title');
$notificationBuilder->setBody('Hello world')
				    ->setSound('default');

$notification = $notificationBuilder->build();

$topic = new Topics();
$topic->topic('news')->andTopic(function($condition) {

	$condition->topic('economic')->orTopic('cultural');

});

$topicResponse = FCM::sendToTopic($topic, null, $notification, null);

$topicResponse->isSuccess();
$topicResponse->shouldRetry();
$topicResponse->error());
```

### Group Messages

[](#group-messages)

#### Sending a Notification to a Group

[](#sending-a-notification-to-a-group)

```
$notificationKey = ['a_notification_key'];

$notificationBuilder = new PayloadNotificationBuilder('my title');
$notificationBuilder->setBody('Hello world')
                        ->setSound('default');

$notification = $notificationBuilder->build();

$groupResponse = FCM::sendToGroup($notificationKey, null, $notification, null);

$groupResponse->numberSuccess();
$groupResponse->numberFailure();
$groupResponse->tokensFailed();
```

#### Creating a Group

[](#creating-a-group)

```
$tokens = ['a_registration_id_at_add_to_group'];
$groupName = "a_group";
$notificationKey

// Save notification key in your database you must use it to send messages or for managing this group
$notification_key = FCMGroup::createGroup($groupName, $tokens);
```

#### Adding Devices to a Group

[](#adding-devices-to-a-group)

```
$tokens = ['a_registration_id_at_add_to_the_new_group'];
$groupName = "a_group";
$notificationKey = "notification_key_received_when_group_was_created";

$key = FCMGroup::addToGroup($groupName, $notificationKey, $tokens);
```

#### Deleting Devices from a Group

[](#deleting-devices-from-a-group)

> Note if all devices are removed from the group, the group is automatically removed in "fcm".

```
$tokens = ['a_registration_id_at_remove_from_the_group'];
$groupName = "a_group";
$notificationKey = "notification_key_received_when_group_was_created";

$key = FCMGroup::removeFromGroup($groupName, $notificationKey, $tokens);
```

Options
-------

[](#options)

Laravel-FCM supports options based on the options of Firebase Cloud Messaging. These options can help you to define the specificity of your notification.

You can construct an option as follows:

```
$optionsBuilder = new OptionsBuilder();

$optionsBuilder->setTimeToLive(42*60)
                ->setCollapseKey('a_collapse_key');

$options = $optionsBuilder->build();
```

Notification Messages
---------------------

[](#notification-messages)

Notification payload is used to send a notification, the behaviour is defined by the App State and the OS of the receptor device.

**Notification messages are delivered to the notification tray when the app is in the background.** For apps in the foreground, messages are handled by these callbacks:

- didReceiveRemoteNotification: on iOS
- onMessageReceived() on Android. The notification key in the data bundle contains the notification.

See the [official documentation](https://firebase.google.com/docs/cloud-messaging/concept-options#notifications).

```
$notificationBuilder = new PayloadNotificationBuilder();
$notificationBuilder->setTitle('title')
            		->setBody('body')
            		->setSound('sound')
            		->setBadge('badge');

$notification = $notificationBuilder->build();
```

Data Messages
-------------

[](#data-messages)

Set the data key with your custom key-value pairs to send a data payload to the client app. Data messages can have a 4KB maximum payload.

- **iOS**, FCM stores the message and delivers it **only when the app is in the foreground** and has established a FCM connection.
- **Android**, a client app receives a data message in onMessageReceived() and can handle the key-value pairs accordingly.

See the [official documentation](https://firebase.google.com/docs/cloud-messaging/concept-options#data_messages).

```
$dataBuilder = new PayloadDataBuilder();
$dataBuilder->addData([
	'data_1' => 'first_data'
]);

$data = $dataBuilder->build();
```

Notification &amp; Data Messages
--------------------------------

[](#notification--data-messages)

App behavior when receiving messages that include both notification and data payloads depends on whether the app is in the background or the foreground—essentially, whether or not it is active at the time of receipt ([source](https://firebase.google.com/docs/cloud-messaging/concept-options#messages-with-both-notification-and-data-payloads)).

- **Background**, apps receive notification payload in the notification tray, and only handle the data payload when the user taps on the notification.
- **Foreground**, your app receives a message object with both payloads available.

Topics
------

[](#topics)

For topics message, Laravel-FCM offers an easy to use api which abstract firebase conditions. To make the condition given for example in the firebase official documentation it must be done with Laravel-FCM like below:

**Official documentation condition**

```
'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)

```

```
$topics = new Topics();

$topics->topic('TopicA')
       ->andTopic(function($condition) {
	       $condition->topic('TopicB')->orTopic('TopicC');
       });
```

Testing
-------

[](#testing)

For integration testing, you can mock the responses with mockery and Mocks provided by the package.

There are 3 kinds of "MockResponse" given by the package:

- MockDownstreamResponse
- MockGroupResponse
- MockTopicResponse

You can mock the FCM call as in the following example:

```
$numberSucess = 2;
$mockResponse = new \LaravelFCM\Mocks\MockDownstreamResponse(numberSucess);

$mockResponse->addTokenToDelete('token_to_delete');
$mockResponse->addTokenToModify('token_to_modify', 'token_modified');
$mockResponse->setMissingToken(true);

$sender = Mockery::mock(\LaravelFCM\Sender\FCMSender::class);
$sender->shouldReceive('sendTo')->once()->andReturn($mockResponse);

$this->app->singleton('fcm.sender', function($app) use($sender) {
	return $sender;
});
```

API Documentation
-----------------

[](#api-documentation)

You can find more documentation about the API in the [API reference](./doc/Readme.md).

Licence
-------

[](#licence)

This library is open-sourced software licensed under the [MIT license](http://opensource.org/licenses/MIT).

Some of this documentation is coming from the official documentation. You can find it completely on the [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging/) Website.

###  Health Score

28

—

LowBetter than 57% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity6

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity65

Established project with proven stability

 Bus Factor1

Top contributor holds 63.8% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~35 days

Recently: every ~96 days

Total

13

Last Release

3128d ago

Major Versions

v0.9.3 → v1.0.02016-07-11

### Community

Maintainers

![](https://www.gravatar.com/avatar/b2fe63923d3d5b41111305c48ed2abf33bb3bf205ba92427b02090237db69c09?d=identicon)[chinhnh93](/maintainers/chinhnh93)

---

Top Contributors

[![brozot](https://avatars.githubusercontent.com/u/3015296?v=4)](https://github.com/brozot "brozot (37 commits)")[![arubacao](https://avatars.githubusercontent.com/u/7462542?v=4)](https://github.com/arubacao "arubacao (10 commits)")[![gcphost](https://avatars.githubusercontent.com/u/1173636?v=4)](https://github.com/gcphost "gcphost (3 commits)")[![chinhnh93](https://avatars.githubusercontent.com/u/24380793?v=4)](https://github.com/chinhnh93 "chinhnh93 (2 commits)")[![chimit](https://avatars.githubusercontent.com/u/839349?v=4)](https://github.com/chimit "chimit (2 commits)")[![marfurt](https://avatars.githubusercontent.com/u/108321?v=4)](https://github.com/marfurt "marfurt (1 commits)")[![appkr](https://avatars.githubusercontent.com/u/6471947?v=4)](https://github.com/appkr "appkr (1 commits)")[![enniel](https://avatars.githubusercontent.com/u/19760944?v=4)](https://github.com/enniel "enniel (1 commits)")[![ANich](https://avatars.githubusercontent.com/u/8276642?v=4)](https://github.com/ANich "ANich (1 commits)")

---

Tags

laravelpushlumennotificationfirebaseFCMFirebase Cloud Messaging

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/chinhnh-laravel-fcm/health.svg)

```
[![Health](https://phpackages.com/badges/chinhnh-laravel-fcm/health.svg)](https://phpackages.com/packages/chinhnh-laravel-fcm)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
