aliamassi/fcm-notification

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

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

Requires

• php: >=8.0
• google/auth: ^1.20
• guzzlehttp/guzzle: ^7.0

MIT

README

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

• 📧 Email: [e-mail]
• 🐛 Issues: GitHub Issues
• 📚 Documentation: GitHub Wiki

🔗 Links

• Firebase Console
• FCM Documentation
• Laravel Documentation

Made with ❤️ for the Laravel community