README

This package makes it easy to send notifications using Firebase Cloud Messaging (FCM) with Laravel.

Contents

• Installation
  • Setting up the FCM service
• Usage
  • Available message methods
  • Topic notifications
  • Custom clients
  • Handling errors
• Changelog
• Testing
• Security
• Contributing
• Credits
• License

Installation

Install this package with Composer:

composer require laravel-notification-channels/fcm

Setting up the FCM service

This package now uses the laravel-firebase library to authenticate and make the API calls to Firebase. Follow the configuration steps specified in their readme before using this.

After following their configuration steps, make sure that you've specified your FIREBASE_CREDENTIALS in your .env file.

Usage

After setting up your Firebase credentials, you can now send notifications via FCM by a Notification class and sending it via the FcmChannel::class. Here is an example:

use Illuminate\Notifications\Notification;
use NotificationChannels\Fcm\FcmChannel;
use NotificationChannels\Fcm\FcmMessage;
use NotificationChannels\Fcm\Resources\Notification as FcmNotification;

class AccountActivated extends Notification
{
    public function via($notifiable)
    {
        return [FcmChannel::class];
    }

    public function toFcm($notifiable): FcmMessage
    {
        return (new FcmMessage(notification: new FcmNotification(
                title: 'Account Activated',
                body: 'Your account has been activated.',
                image: 'http://example.com/url-to-image-here.png'
            )))
            ->data(['data1' => 'value', 'data2' => 'value2'])
            ->custom([
                'android' => [
                    'notification' => [
                        'color' => '#0A0A0A',
                        'sound' => 'default',
                    ],
                    'fcm_options' => [
                        'analytics_label' => 'analytics',
                    ],
                ],
                'apns' => [
                    'payload' => [
                        'aps' => [
                            'sound' => 'default'
                        ],
                    ],
                    'fcm_options' => [
                        'analytics_label' => 'analytics',
                    ],
                ],
            ]);
    }
}

You will have to set a routeNotificationForFcm() method in your notifiable model. This method should return the user's FCM token(s) from storage. For example:

class User extends Authenticatable
{
    use Notifiable;

    ...

    /**
     * Specifies the user's FCM token
     *
     * @return string|array
     */
    public function routeNotificationForFcm()
    {
        return $this->fcm_token;
    }
}

You can also return an array of tokens to send notifications via multicast to different user devices.

class User extends Authenticatable
{
    use Notifiable;

    ...

    /**
     * Specifies the user's FCM tokens
     *
     * @return string|array
     */
    public function routeNotificationForFcm()
    {
        return $this->getDeviceTokens();
    }
}

Once you have that in place, you can simply send a notification to the user by doing the following:

$user->notify(new AccountActivated);

Available Message methods

View the FcmMessage source for the complete list of options.

FcmMessage::create()
    ->name('name')
    ->token('token')
    ->topic('topic')
    ->condition('condition')
    ->data(['a' => 'b'])
    ->custom(['notification' => []]);

Topic notifications

You can also send FCM notifications to topics with the FcmTopicChannel. Use an on-demand notification to to route the notification to the topic, or you can set the topic on the message itself in the toFcm method.

use NotificationChannels\Fcm\FcmTopicChannel;

Notification::route(FcmTopicChannel::class, 'news')
    ->notify(new BlogCreated($blog));

Custom clients

You can change the underlying Firebase Messaging client on the fly if required. Provide an instance of Kreait\Firebase\Contract\Messaging to your FCM message and it will be used in place of the default client.

public function toFcm(mixed $notifiable): FcmMessage
{
    $client = app(\Kreait\Firebase\Contract\Messaging::class);

    return FcmMessage::create()->usingClient($client);
}

Handling errors

When a notification fails it will dispatch an Illuminate\Notifications\Events\NotificationFailed event. You can listen for this event and choose to handle these notifications as appropriate. For example, you may choose to delete expired notification tokens from your database.

<?php

namespace App\Listeners;

use Illuminate\Notifications\Events\NotificationFailed;
use Illuminate\Support\Arr;

class DeleteExpiredNotificationTokens
{
    /**
     * Handle the event.
     */
    public function handle(NotificationFailed $event): void
    {
        if ($event->channel == FcmChannel::class) {

            $report = Arr::get($event->data, 'report');

            $target = $report->target();

            $event->notifiable->notificationTokens()
                ->where('push_token', $target->value())
                ->delete();
        }
    }
}

Remember to register your event listeners in the event service provider.

/**
 * The event listener mappings for the application.
 *
 * @var array
 */
protected $listen = [
    \Illuminate\Notifications\Events\NotificationFailed::class => [
        \App\Listeners\DeleteExpiredNotificationTokens::class,
    ],
];

Changelog

Please see CHANGELOG for more information what has changed recently.

Testing

composer test

Security

If you discover any security related issues, please email chrisbjr@gmail.com instead of using the issue tracker.

Contributing

Please see CONTRIBUTING for details.

Credits

• Chris Bautista
• All Contributors

License

The MIT License (MIT). Please see License File for more information.