Laravel FCM

laravel-fcm is a powerful Laravel package to send Push Notifications to one or many devices of the user. Being channel-based you only need to specify the channel in your Laravel Notification.

• Quick Start
• Installation
• Routes
• Customizing The Notification
• Customizing The Controller

⚡ Quick Start

1. Creating notifications

php artisan make:notification InvoicePaid

2. Adding delivery channels

Every notification class has a via method that determines on which channels the notification will be delivered. Add fcm as delivery channel:

/**
 * Get the notification's delivery channels.
 *
 * @param  mixed  $notifiable
 * @return array
 */
public function via($notifiable)
{
    return ['fcm'];
}

3. Formatting notifications

The notification method support the Firebase payload:

/**
 * Get the Firebase Message representation of the notification.
 *
 * @param  mixed  $notifiable
 * @return \williamcruzme\FCM\Messages\FcmMessage
 */
public function toFcm($notifiable)
{
    return (new FcmMessage)
                ->notification([
                    'title' => 'Happy Code!',
                    'body' => 'This is a test',
                ]);
}

4. Sending notifications

FcmMessage automatically gets all devices of the notifiable entities; you just need to send notifications. Notifications may be sent in two ways: using the notify method of the Notifiable trait or using the Notification facade. First, let's explore using the trait:

Using The Notifiable Trait

This trait is utilized by the default App\User model and contains one method that may be used to send notifications: notify. The notify method expects to receive a notification instance:

use App\Notifications\InvoicePaid;

$user->notify(new InvoicePaid($invoice));

Remember, you may use the Illuminate\Notifications\Notifiable trait on any of your models. You are not limited to only including it on your App\User model.

Using The Notification Facade

Alternatively, you may send notifications via the Notification facade. This is useful primarily when you need to send a notification to multiple notifiable entities such as a collection of users. To send notifications using the facade, pass all of the notifiable entities and the notification instance to the send method:

use App\Notifications\InvoicePaid;
use Illuminate\Support\Facades\Notification;

Notification::send($users, new InvoicePaid($invoice));

💿 Installation

composer require williamcruzme/laravel-fcm

1. Configure the enviroment

Get the key of Server Key and paste in your .env file:
(gear-next-to-project-name) > Project Settings > Cloud Messaging

FCM_KEY=

2. Adding traits

In your App\User model add the HasDevices trait:

<?php

namespace App;

use williamcruzme\FCM\Traits\HasDevices;
use Illuminate\Notifications\Notifiable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use HasDevices, Notifiable;
}

Remember, you may use the williamcruzme\FCM\Traits\HasDevices trait on any of your models. You are not limited to only including it on your App\User model.

3. Running migrations

php artisan migrate

(Optional) Sometimes you may need to customize the migrations. Using the vendor:publish command you can export the migrations:

php artisan vendor:publish --tag=migrations

4. Adding routes

In your routes/api.php add the routes using the Device facade, this is for manage the devices:

Route::middleware('auth')->group(function () {
    Device::routes();
});

🌐 Routes

Add device

Method	URI
POST	/devices

Body Params

{
    "token": "fxssWy2Lgtk:APA91bFXy79AmofgTnBm5CfBpyeEFJsSHq0Xcdk..."
}

Remove device

Method	URI
DELETE	/devices/{deviceToken}

🎨 Customizing The Notification

Specifying devices

Using the to method you can specific the device's to send the notification:

/**
 * Get the Firebase Message representation of the notification.
 *
 * @param  mixed  $notifiable
 * @return \williamcruzme\FCM\Messages\FcmMessage
 */
public function toFcm($notifiable)
{
    return (new FcmMessage)
                ->to('fxssWy2Lgtk:APA91bFXy79AmofgTnBm5CfBpyeEFJsSHq0Xcdk...')
                ->notification([
                    'title' => 'Happy Code!',
                    'body' => 'This is a test',
                ]);
}

Remember, this is optional because FcmMessage automatically gets all devices of $notifiable.

Specifying topics

Using the topic method you can specific the topic to send the notification:

/**
 * Get the Firebase Message representation of the notification.
 *
 * @param  mixed  $notifiable
 * @return \williamcruzme\FCM\Messages\FcmMessage
 */
public function toFcm($notifiable)
{
    return (new FcmMessage)
                ->topic('news')
                ->notification([
                    'title' => 'Happy Code!',
                    'body' => 'This is a test',
                ]);
}

This method ignores the devices of $notifiable.

Sending data

Using the data method you can specify the custom key-value pairs of the notification payload:

/**
 * Get the Firebase Message representation of the notification.
 *
 * @param  mixed  $notifiable
 * @return \williamcruzme\FCM\Messages\FcmMessage
 */
public function toFcm($notifiable)
{
    return (new FcmMessage)
                ->notification([
                    'title' => 'Happy Code!',
                    'body' => 'This is a test',
                ])
                ->data([
                    'type' => 'banner',
                    'link' => 'https://github.com/',
                ]);
}

Adding conditions

Using the condition method you can specify a boolean expression to send the notification:

/**
 * Get the Firebase Message representation of the notification.
 *
 * @param  mixed  $notifiable
 * @return \williamcruzme\FCM\Messages\FcmMessage
 */
public function toFcm($notifiable)
{
    return (new FcmMessage)
                ->condition("'stock-GOOG' in topics || 'industry-tech' in topics")
                ->notification([
                    'title' => 'Happy Code!',
                    'body' => 'This is a test',
                ]);
}

Setting priority

Using the priority method you can specify a priority of the notification. Default is normal:

/**
 * Get the Firebase Message representation of the notification.
 *
 * @param  mixed  $notifiable
 * @return \williamcruzme\FCM\Messages\FcmMessage
 */
public function toFcm($notifiable)
{
    return (new FcmMessage)
                ->priority('high')
                ->notification([
                    'title' => 'Happy Code!',
                    'body' => 'This is a test',
                ]);
}

🎨 Customizing The Controller

First of all, create your own DeviceController controller and add the ManageDevices trait.

Second, modify the namespace of the Device facade routes to :

Device::routes('App\Http\Controllers');

Custom request validations

The createRules deleteRules validationErrorMessages methods in the DeviceController allows you override the default request validations:

<?php

namespace App\Http\Controllers;

use williamcruzme\FCM\Traits\ManageDevices;

class DeviceController extends Controller {

    use ManageDevices;
    
    /**
     * Get the validation rules that apply to the create a device.
     *
     * @return array
     */
    protected function createRules()
    {
        return [
            'token' => ['required', 'string'],
        ];
    }

    /**
     * Get the validation rules that apply to the delete a device.
     *
     * @return array
     */
    protected function deleteRules()
    {
        return [
            'token' => ['required', 'string', 'exists:devices,token'],
        ];
    }

    /**
     * Get the device management validation error messages.
     *
     * @return array
     */
    protected function validationErrorMessages()
    {
        return [];
    }
}

Custom guards

The guard method in the DeviceController allows you override the default guard:

<?php

namespace App\Http\Controllers;

use williamcruzme\FCM\Traits\ManageDevices;

class DeviceController extends Controller {

    use ManageDevices;
    
    /**
     * Get the guard to be used during device management.
     *
     * @return \Illuminate\Contracts\Auth\StatefulGuard
     */
    protected function guard()
    {
        return auth('admin')->guard();
    }
}

🚸 Contributing

You are welcome to contribute to this project, but before you do, please make sure you read the contribution guide.

🔒 License

MIT