Download the PHP package netosts/laravel-fcm-notifications without Composer

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

• Features
• Requirements
• Installation
• Quick Start
• Configuration
  • Firebase Setup
  • Environment Variables
  • Database Setup
  • Token Management
• Usage
  • Basic Usage
  • Direct Service Usage
  • Message Types
  • Batch Sending
  • Platform-Specific Configuration
• Testing
• Configuration Options
• Troubleshooting
• Support

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

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

Installation

You can install the package via Composer:

Publish the configuration file:

Quick Start

Get up and running in minutes:

1. Set up your Firebase credentials

Add these environment variables to your .env file:

2. Add FCM token to your User model

3. Send your first notification

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

Configuration

💡 Tip: If you just want to get started quickly, check the Quick Start section above.

1. Firebase Setup

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

1. Go to the Firebase Console
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

Add the following variables to your .env file:

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

3. Database Setup

Choose one of the following approaches for storing FCM tokens:

Option A: Multiple Tokens per User (Recommended)

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

Option B: Single Token per User

Add a token column to your existing users table:

4. Token Management

Configure how the package discovers FCM tokens from your models:

For Multiple Tokens (Option A)

For Single Token (Option B)

Usage

Basic Usage

There are two main ways to send FCM notifications:

Method 1: Using FcmNotification Directly (Simple)

Method 2: Custom Notification Class (Recommended)

Create a custom notification class for better organization:

Extend the FcmNotification class:

Use your custom notification:

Direct Service Usage

For more control, use the FCM service directly:

Message Types

FCM supports different message types for different use cases:

1. Notification + Data (Default)

Shows a system notification and passes custom data to your app:

2. Data Only

Sends data silently to your app without showing a notification:

3. Notification Only

Shows only a system notification without custom data:

Batch Sending

Send the same message to multiple devices efficiently:

Platform-Specific Configuration

Customize notifications for different platforms:

Android Specific Settings

iOS Specific Settings

Cross-Platform Message

Event Listeners

The package automatically handles token cleanup through events:

When an invalid token is detected, it's automatically removed from your database (if FCM_AUTO_CLEANUP_TOKENS=true).

Testing

Built-in Test Commands

The package includes helpful commands for testing your FCM integration:

Token Validation

Validate FCM tokens before sending notifications:

Testing in Development

Configuration Options

The config/fcm-notifications.php file provides comprehensive configuration options:

Configuration Details

Troubleshooting

Common Issues

🔐 Authentication Failed

Symptoms: Authentication errors, 401 responses from FCM

Solutions:

• Verify your Firebase service account credentials in .env
• Ensure the private key includes proper line breaks (\n)
• Check that your service account has FCM permissions
• Validate your project_id matches your Firebase project

🔍 Tokens Not Found

Symptoms: No notifications sent, "no tokens found" errors

Solutions:

• Check your token storage implementation
• Verify the token_column configuration matches your database
• Ensure users have FCM tokens stored
• Check relationship methods in your User model

📱 Messages Not Received

Symptoms: API calls succeed but notifications don't appear

Solutions:

• Test with the built-in test command
• Check FCM token validity
• Verify your mobile app is properly configured for FCM
• Check device notification settings
• Ensure app is not in battery optimization mode (Android)

⚡ Performance Issues

Symptoms: Slow notification sending, timeouts

Solutions:

• Enable token caching in config
• Use batch sending for multiple recipients
• Implement queue processing for large volumes
• Increase timeout setting if needed

Debug Mode

Enable detailed logging for troubleshooting:

This will log detailed FCM request/response information to help diagnose issues.

Getting Help

If you're still having issues:

1. Check the logs - Look in storage/logs/laravel.log for detailed error messages
2. Test with the built-in commands - Use php artisan fcm:test to isolate issues
3. Validate your setup - Double-check Firebase credentials and configuration
4. Review the FCM documentation - Some issues may be Firebase-specific

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security

If you discover any security-related issues, please email [email protected] instead of using the issue tracker.

Credits

• Neto Santos - Creator and maintainer
• All Contributors - Community contributors

License

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

Support

Need help? Here's how to get support:

• 📧 Email: [email protected]
• 🐛 Bug Reports: GitHub Issues
• 💬 Questions & Discussions: GitHub Discussions
• 📖 Documentation: This README and inline code documentation