PHPackages                             netosts/laravel-fcm-notifications - 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 & Notifications](/categories/mail)
4. /
5. netosts/laravel-fcm-notifications

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

netosts/laravel-fcm-notifications
=================================

A robust and secure Firebase Cloud Messaging (FCM) notification system for Laravel applications

1.0.9(8mo ago)1210↑33.3%MITPHPPHP ^8.1

Since Jul 2Pushed 8mo agoCompare

[ Source](https://github.com/netosts/laravel-fcm-notifications)[ Packagist](https://packagist.org/packages/netosts/laravel-fcm-notifications)[ RSS](/packages/netosts-laravel-fcm-notifications/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (1)Versions (13)Used By (0)

[![Laravel FCM Notifications Banner](assets/banner_wide.png)](assets/banner_wide.png)

Laravel FCM Notifications
=========================

[](#laravel-fcm-notifications)

[![Latest Version on Packagist](https://camo.githubusercontent.com/10b84c3ba3ea74df458d10c036b31e04de473a7c1b056096fada37d79b795d0e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6e65746f7374732f6c61726176656c2d66636d2d6e6f74696669636174696f6e733f7374796c653d666c61742d737175617265)](https://packagist.org/packages/netosts/laravel-fcm-notifications)[![Total Downloads](https://camo.githubusercontent.com/01e8539795696bb5bec89553ed8dde74b2bb0f890c991e293e71480e43159cf6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6e65746f7374732f6c61726176656c2d66636d2d6e6f74696669636174696f6e733f7374796c653d666c61742d737175617265)](https://packagist.org/packages/netosts/laravel-fcm-notifications)[![License](https://camo.githubusercontent.com/748305741f2fd238ea24189d188ad5452d4a4bbdac520f738d0d58ecc5b2dc2d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6e65746f7374732f6c61726176656c2d66636d2d6e6f74696669636174696f6e733f7374796c653d666c61742d737175617265)](https://packagist.org/packages/netosts/laravel-fcm-notifications)

A robust and secure Firebase Cloud Messaging (FCM) notification system for Laravel applications. This package provides a comprehensive solution for sending push notifications with automatic token management, cleanup, and support for all FCM message types.

Table of Contents
-----------------

[](#table-of-contents)

- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
    - [Firebase Setup](#1-firebase-setup)
    - [Environment Variables](#2-environment-variables)
    - [Database Setup](#3-database-setup)
    - [Token Management](#4-token-management)
- [Usage](#usage)
    - [Basic Usage](#basic-usage)
    - [Direct Service Usage](#direct-service-usage)
    - [Message Types](#message-types)
    - [Batch Sending](#batch-sending)
    - [Platform-Specific Configuration](#platform-specific-configuration)
- [Testing](#testing)
- [Configuration Options](#configuration-options)
- [Troubleshooting](#troubleshooting)
- [Support](#support)

Features
--------

[](#features)

- 🚀 **Easy Integration** - Drop-in Laravel notification channel
- 🔐 **Secure Authentication** - JWT-based Google OAuth2 authentication
- 📱 **Multiple Message Types** - Support for notification-only, data-only, and combined messages
- 🔄 **Automatic Token Cleanup** - Removes invalid tokens automatically
- 📊 **Batch Sending** - Send to multiple devices efficiently
- 🛠️ **Platform Specific** - Android and iOS specific configurations
- 📝 **Comprehensive Logging** - Detailed logging for debugging
- ⚡ **Performance Optimized** - Token caching and efficient API calls
- 🧪 **Testing Commands** - Built-in commands for testing functionality

Requirements
------------

[](#requirements)

- PHP 8.1 or higher
- Laravel 10.0 or higher
- Firebase project with FCM enabled

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

[](#installation)

You can install the package via Composer:

```
composer require netosts/laravel-fcm-notifications
```

Publish the configuration file:

```
php artisan vendor:publish --tag=fcm-notifications-config
```

Quick Start
-----------

[](#quick-start)

Get up and running in minutes:

### 1. Set up your Firebase credentials

[](#1-set-up-your-firebase-credentials)

Add these environment variables to your `.env` file:

```
FCM_PROJECT_ID=your-firebase-project-id
FCM_CLIENT_EMAIL=your-service-account@your-project.iam.gserviceaccount.com
FCM_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYour-Private-Key-Here\n-----END PRIVATE KEY-----"
```

### 2. Add FCM token to your User model

[](#2-add-fcm-token-to-your-user-model)

```
// Add to your users table migration
Schema::table('users', function (Blueprint $table) {
    $table->string('fcm_token')->nullable();
});

// Make it fillable in your User model
class User extends Model
{
    protected $fillable = ['fcm_token'];
}
```

### 3. Send your first notification

[](#3-send-your-first-notification)

```
use LaravelFcmNotifications\Notifications\FcmNotification;

$notification = new FcmNotification(
    title: 'Welcome!',
    body: 'Thanks for joining our app'
);

$user->notify($notification);
```

That's it! Your notification will be sent to the user's device.

Configuration
-------------

[](#configuration)

> **💡 Tip:** If you just want to get started quickly, check the [Quick Start](#quick-start) section above.

### 1. Firebase Setup

[](#1-firebase-setup)

To use FCM, you need a Firebase project with proper credentials:

1. Go to the [Firebase Console](https://console.firebase.google.com/)
2. Create a new project or select an existing one
3. Navigate to **Project Settings** → **Service Accounts**
4. Click **Generate New Private Key** to download the service account JSON file

### 2. Environment Variables

[](#2-environment-variables)

Add the following variables to your `.env` file:

```
# Required - Firebase Credentials
FCM_PROJECT_ID=your-firebase-project-id
FCM_CLIENT_EMAIL=your-service-account@your-project.iam.gserviceaccount.com
FCM_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYour-Private-Key-Here\n-----END PRIVATE KEY-----"

# Optional - API Settings
FCM_TIMEOUT=30
FCM_DEFAULT_MODE=data_only

# Optional - Token Management
FCM_TOKEN_COLUMN=token
FCM_AUTO_CLEANUP_TOKENS=true
```

> **⚠️ Important:** The private key must include `\n` characters for line breaks.

### 3. Database Setup

[](#3-database-setup)

Choose one of the following approaches for storing FCM tokens:

#### Option A: Multiple Tokens per User (Recommended)

[](#option-a-multiple-tokens-per-user-recommended)

For users with multiple devices, create a dedicated tokens table:

```
// Create migration: php artisan make:migration create_notification_tokens_table
Schema::create('notification_tokens', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained()->onDelete('cascade');
    $table->string('token')->unique();
    $table->string('device_type')->nullable(); // 'android', 'ios', 'web'
    $table->timestamps();
});
```

#### Option B: Single Token per User

[](#option-b-single-token-per-user)

Add a token column to your existing users table:

```
// Add to your users table migration
Schema::table('users', function (Blueprint $table) {
    $table->string('fcm_token')->nullable();
});
```

### 4. Token Management

[](#4-token-management)

Configure how the package discovers FCM tokens from your models:

#### For Multiple Tokens (Option A)

[](#for-multiple-tokens-option-a)

```
class User extends Model
{
    public function notificationTokens()
    {
        return $this->hasMany(NotificationToken::class);
    }
}

// Optional: Create a NotificationToken model
class NotificationToken extends Model
{
    protected $fillable = ['user_id', 'token', 'device_type'];

    public function user()
    {
        return $this->belongsTo(User::class);
    }
}
```

#### For Single Token (Option B)

[](#for-single-token-option-b)

```
class User extends Model
{
    protected $fillable = ['fcm_token'];

    // Optional: Custom method name
    public function getFcmToken()
    {
        return $this->fcm_token;
    }
}
```

Usage
-----

[](#usage)

### Basic Usage

[](#basic-usage)

There are two main ways to send FCM notifications:

#### Method 1: Using FcmNotification Directly (Simple)

[](#method-1-using-fcmnotification-directly-simple)

```
use LaravelFcmNotifications\Notifications\FcmNotification;

// Simple notification
$notification = new FcmNotification(
    title: 'New Message',
    body: 'You have a new message from John'
);

$user->notify($notification);
```

#### Method 2: Custom Notification Class (Recommended)

[](#method-2-custom-notification-class-recommended)

Create a custom notification class for better organization:

```
php artisan make:notification PushNotification
```

Extend the `FcmNotification` class:

```