aliamassi/fcm-notification

Laravel package to send Firebase Cloud Messaging notifications to Android and iOS.

dev-main 2025-07-08 09:22 UTC

This package is auto-updated.

Last update: 2025-07-08 09:22:37 UTC


README

Latest Stable Version Total Downloads License PHP Version Require

A simple and elegant Laravel package to send Firebase Cloud Messaging (FCM) push notifications to Android and iOS devices.

โœจ Features

  • ๐Ÿš€ Easy Laravel integration
  • ๐Ÿ“ฑ Support for Android & iOS devices
  • ๐Ÿ”” Single & batch notifications
  • ๐Ÿ“Š Custom data payloads
  • โš™๏ธ Configurable settings
  • ๐Ÿ›ก๏ธ Built-in error handling

๐Ÿ“‹ Requirements

  • PHP >= 8.0
  • Laravel >= 9.0
  • Firebase project with FCM enabled

๐Ÿ“ฆ Installation

Step 1: Install Package

For Production

composer require aliamassi/fcm-notification:dev-main --dev

For Local Development

Add to your composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "aliamassi/fcm-notification"
        }
    ]
}

Then install:

composer require aliamassi/fcm-notification:dev-main

Step 2: Publish Configuration

php artisan vendor:publish --tag=config --provider="AliAmassi\FcmNotification\FirebaseNotificationServiceProvider"

Step 3: Environment Setup

Add to your .env file:

FIREBASE_PROJECT_ID=your_firebase_project_id_here
FIREBASE_CREDENTIALS=your_firebase_file_here[path to -->firebase-service-account.json]

โš™๏ธ Configuration

The published config file (config/firebase.php):

<?php

return [
    /*
    |--------------------------------------------------------------------------
    | FCM Server Key
    |--------------------------------------------------------------------------
    |
    | Your Firebase Cloud Messaging server key from Firebase Console
    | Project Settings > Cloud Messaging > Server Key
    |
    */
     // Path to service account JSON
    'credentials' => env('FIREBASE_CREDENTIALS', storage_path('app/firebase-service-account.json')),
    
     // Your Firebase project ID
    'project_id' => env('FIREBASE_PROJECT_ID'),

    /*
    |--------------------------------------------------------------------------
    | Request Timeout
    |--------------------------------------------------------------------------
    |
    | Maximum time in seconds to wait for FCM response
    |
    */
    'timeout' => env('FCM_TIMEOUT', 30),
];

๐Ÿš€ Usage

Basic Usage

<?php

use AliAmassi\FcmNotification\Facades\FirebaseNotification;

// single device
    FcmNotification::sendToToken(
      $oneToken,
      ['title'=>'Hi','body'=>'Hello!'],
      ['foo'=>'bar']
    );

// multicast
    FcmNotification::sendToTokens(
      $arrayOfTokens,
      ['title'=>'Group!','body'=>'Hey everyone'],
      ['extra'=>'data']
    );

๐Ÿงช Testing

Postman Testing

Endpoint: POST /api/send-notification

Headers:

Content-Type: application/json
Authorization: Bearer your_api_token

Request Body:

{
    "device_tokens": [
        "device_token_1",
        "device_token_2"
    ],
    "notification": {
        "title": "Test Notification",
        "body": "This is a test notification",
        "sound": "default"
    },
    "data": {
        "test_key": "test_value",
        "action": "test_action"
    }
}

cURL Testing

curl -X POST https://your-app.com/api/send-notification \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token" \
  -d '{
    "device_tokens": ["your_device_token"],
    "notification": {
      "title": "Test",
      "body": "Hello from cURL!"
    },
    "data": {
      "foo": "bar"
    }
  }'

๐Ÿ“š API Reference

Methods

send($tokens, $notification, $data = [], $options = [])

Send notification to device tokens.

Parameters:

  • $tokens (string|array) - Device token(s)
  • $notification (array) - Notification payload
  • $data (array) - Custom data payload
  • $options (array) - FCM options

Returns: Response array from FCM

Notification Structure

$notification = [
    'title' => 'string (required)',
    'body'  => 'string (required)',
    'sound' => 'string (optional)',
    'icon'  => 'string (optional)',
    'color' => 'string (optional, #RRGGBB)',
    'click_action' => 'string (optional)',
    'tag'   => 'string (optional)'
];

Options Structure

$options = [
    'priority' => 'normal|high',
    'time_to_live' => 3600, // seconds
    'collapse_key' => 'string',
    'dry_run' => false // boolean
];

๐Ÿ”ง Troubleshooting

Common Issues

1. Invalid Server Key

  • Verify FCM_SERVER_KEY in .env
  • Check Firebase Console > Project Settings > Cloud Messaging

2. Invalid Device Tokens

  • Device tokens expire regularly
  • Implement token refresh in your mobile app

3. Network Issues

  • Ensure server has internet access
  • Check firewall settings for HTTPS outbound

4. Authentication Errors

  • Verify server key format
  • Ensure key has FCM permissions

Debug Mode

Enable Laravel debugging:

APP_DEBUG=true
LOG_LEVEL=debug

๐Ÿ“– Examples

E-commerce Order Notification

public function sendOrderNotification($order)
{
    $tokens = $order->user->device_tokens;
    
    $notification = [
        'title' => 'Order Confirmed!',
        'body'  => "Your order #{$order->id} has been confirmed",
        'sound' => 'default',
        'icon'  => 'order_icon'
    ];
    
    $data = [
        'order_id' => $order->id,
        'action'   => 'view_order',
        'amount'   => $order->total
    ];
    
    return $this->fcm->send($tokens, $notification, $data);
}

Chat Message Notification

public function sendChatNotification($message)
{
    $tokens = $message->recipient->device_tokens;
    
    $notification = [
        'title' => $message->sender->name,
        'body'  => $message->content,
        'sound' => 'message_sound',
        'click_action' => 'OPEN_CHAT'
    ];
    
    $data = [
        'chat_id' => $message->chat_id,
        'sender_id' => $message->sender_id,
        'message_id' => $message->id
    ];
    
    return $this->fcm->send($tokens, $notification, $data);
}

๐Ÿค Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

  1. Fork the repository
  2. Clone your fork: git clone https://github.com/yourusername/laravel-fcm-notification.git
  3. Install dependencies: composer install
  4. Run tests: vendor/bin/phpunit
  5. Create feature branch: git checkout -b feature/amazing-feature
  6. Commit changes: git commit -m 'Add amazing feature'
  7. Push to branch: git push origin feature/amazing-feature
  8. Submit Pull Request

๐Ÿ“ Changelog

v1.0.0

  • Initial release
  • Basic FCM notification support
  • Single and batch notifications
  • Custom data payloads

๐Ÿ“„ License

This package is open-sourced software licensed under the MIT License.

๐Ÿ™ Support

๐Ÿ”— Links

Made with โค๏ธ for the Laravel community