PHPackages                             larafact/spn - 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. larafact/spn

ActiveLibrary

larafact/spn
============

Simple classes for sending Push Notifications via Firebase Cloud Messaging

0.1.5(7y ago)011MITPHPPHP ^7.0

Since Sep 28Pushed 7y agoCompare

[ Source](https://github.com/larafact/spn)[ Packagist](https://packagist.org/packages/larafact/spn)[ RSS](/packages/larafact-spn/feed)WikiDiscussions master Synced 2mo ago

READMEChangelog (3)Dependencies (4)Versions (2)Used By (0)

SPN - Simple Push Notification
==============================

[](#spn---simple-push-notification)

A very simple way for sending, and nothing else, `push notifications` using FireBase Clouding Messaging.

About
-----

[](#about)

Package for Pushing Notifications using Firebase Cloud Messaging Protocol.

Such as its name suggests, the package is intended for providing a simple way for pushing notifications, and nothing else.

> Note: It has not any support for pushing `messages` or notifications based on `topics`

Main features about SPN are:

- Intended for only push notifications - Keeping things simple!
- Push notifications are sent using only HTTP Protocol ()
- It is able for returning the FCM's raw response or a parsed one.
- Parsed responses have information about delivered / undelivered notifications, devices tokens that should be deleted, and about those ones should be resend.
- Also It has support for `Group Device Messaging`. See:
    -
    -

For all about errors and exception triggering, please take a look at:

-
-

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

[](#installation)

Require the latest version of Spn into your project

```
composer require larafact/spn

```

Or you can add it directly into your project's composer.json file:

```
{
    "require": {
        "larafact/spn": "^0.1.0"
    }
}

```

### Laravel configuration

[](#laravel-configuration)

Register the Spn Service Provider into your app configuration file `config/app.php`:

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

    larafact\Spn\SpnServiceProvider::class,
]

```

Then publish the package config file:

```
php artisan vendor:publish

```

And finally in your `.env` file, add your Server's keys and project ID using the Keys you got from FCM:

```
FCM_PROJECT_ID=
FCM_KEY=

```

To get these keys, you must create a new application on the Firebase Cloud Messaging console.

Getting started
---------------

[](#getting-started)

Once everything is installed and configured, you can start to using all the helpers exposed by SPN, to achieve all tasks related with

- Push notifications.
- Querying responses.
- Handling Exceptions.
- Device Group Management.

### Push Notifications

[](#push-notifications)

SPN can only handle **Notification Messages** via Firebase Http Protocol. The XMPP protocol is not currently supported.

#### Single Device

[](#single-device)

```
 $response = push_notification(, 'Greetings', 'Hi, from SPN :)');
```

#### Multiple devices

[](#multiple-devices)

```
$recipients = [device_token, device_token, ..., device_token] // Up to 1000 device tokens
$response = push_notification($repicpients, 'Greetings', 'Hi, from SPN :)');
```

#### Devices Group

[](#devices-group)

```
$response = push_notification(, 'Greetings', 'Hi, from SPN :)');
```

### Handling responses

[](#handling-responses)

Once a notification message has been sent, SPN holds the FCM response, so you can querying it for useful information. Check it out the following examples:

#### Getting the FCM's raw response

[](#getting-the-fcms-raw-response)

```
$response = push_notification(, 'Greetings', 'Hi, from SPN :)');
$rawResponse = $response->rawResponse();
```

it returns:

```
{"multicast_id":8724186164068196172,"success":1,"failure":0,"canonical_ids":0,"results":[{"message_id":"0:1488747479995544%6975114c6975114c"}]}
```

#### Response's stats

[](#responses-stats)

```
$response = push_notification(, 'Greetings', 'Hi, from SPN :)');
$stats = $response->stats();
```

it returns:

```
[
    'delivered' => [device_token, device_token, ..., device_token],
    'undelivered' => [device_token, device_token, ..., device_token],
    'shouldBeDeleted' => [device_token, device_token, ..., device_token],
    'shouldBeResend' => [device_token, device_token, ..., device_token]
]
```

If you like to get only an specific stats information, you can use one of the following methods:

```
$delivered = $response->delivered(); // delivered tokens devices array.
$undelivered = $response->undelivered(); // undelivered tokens devices array.
$tokensForDeletion = $response->tokensForDeletion(); // invalid tokens.
$tokensForResending = $response->tokensForResending(); // tokens for resending.
```

> Note: For notification messages sent to a Device Group, the `shouldBeDeleted`, and `shouldBeResend` always be `null`.

### Handling errors and Exceptions.

[](#handling-errors-and-exceptions)

SPN config file `config/spn.php` defines 2 keys for specifying how errors should be handled:

- `on_error`: tell if an exception will be triggered when any of errors described in [Interpreting a downstream message response](https://firebase.google.com/docs/cloud-messaging/http-server-ref#table4) are found
- `on_partial_deliveries`: tell if an exception will be triggered when a notification cannot be delivered to all of its recipients.

SPN defines the following exceptions:

- `ConnectionException`: Any exception thrown by `GuzzleClient` class.
- `InvalidServerKeyException`: There was an error authenticating the sender account.
- `BadRequestException`: Only applies for JSON requests. Indicates that the request could not be parsed as JSON, or it contained invalid fields
- `InvalidServerErrorException`: Any fatal error.
- `UndeliveredNotificationException:` Triggered when a notification was not delivered to any of its recipients (it requires setting `on_partial_deliveries = true` in `config/spn.php` )
- `NontificationKeyAlreadyException`: The Device Group cannot be created because it already exists.
- `NotificationKeyNotFound`: The Device Group Notification Key is invalid.

### Device Group Messaging

[](#device-group-messaging)

According FCM:

> "With device group messaging, you can send a single message to multiple instances of an app running on devices belonging to a group. Typically, "group" refers a set of different devices that belong to a single user. All devices in a group share a common notification key, which is the token that FCM uses to fan out messages to all devices in the group."

SPN exposes helpers for Device Group Management tasks:

### Creating a Device Group

[](#creating-a-device-group)

```
$devices = [device_token, device_token, ...., device_token];
$response = dgm_create(
    $devices,
    'appUser-Chris'
);
```

it replies with a `notification_key`:

```
{
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}
```

### Adding members to a Device Group

[](#adding-members-to-a-device-group)

```
$devices = [device_token, device_token, ...., device_token];
$notificationKey = '';
$notificationKeyName = 'appUser-Chris';
$response = dgm_add(
    $devices,
    $notificationKey,
    $notificationKeyName
);
```

it replies with a `notification_key`:

```
{
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}
```

### Removing members from a Device Group

[](#removing-members-from-a-device-group)

```
$devices = [device_token, device_token, ...., device_token];
$notificationKey = '';
$notificationKeyName = 'appUser-Chris';
$response = dgm_remove(
    $devices,
    $notificationKey,
    $notificationKeyName
);
```

it replies with a `notification_key`:

```
{
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}
```

License
-------

[](#license)

Copyright (c) 2017 - Cobis ()

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

###  Health Score

21

—

LowBetter than 19% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity5

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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

Unknown

Total

1

Last Release

2781d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/2d6d5e1997613ef3adfea92982b0c45e1c806677b7ce3a69541abfa260fb6388?d=identicon)[larafact](/maintainers/larafact)

---

Top Contributors

[![larafact](https://avatars.githubusercontent.com/u/39576573?v=4)](https://github.com/larafact "larafact (3 commits)")

---

Tags

laravelFCMpush notificationdgmdevice group manager

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/larafact-spn/health.svg)

```
[![Health](https://phpackages.com/badges/larafact-spn/health.svg)](https://phpackages.com/packages/larafact-spn)
```

###  Alternatives

[laravel-notification-channels/discord

Laravel notification driver for Discord.

2371.3M11](/packages/laravel-notification-channels-discord)[tzsk/sms

A robust and unified SMS gateway integration package for Laravel, supporting multiple providers.

320244.3k6](/packages/tzsk-sms)[erag/laravel-disposable-email

A Laravel package to detect and block disposable email addresses.

226102.4k](/packages/erag-laravel-disposable-email)[truckersmp/steam-socialite

Laravel Socialite provider for Steam OpenID.

1516.7k](/packages/truckersmp-steam-socialite)

PHPackages © 2026

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