aliamassi / fcm-notification
Laravel package to send Firebase Cloud Messaging notifications to Android and iOS.
Requires
- php: >=8.0
- google/auth: ^1.20
- guzzlehttp/guzzle: ^7.0
This package is auto-updated.
Last update: 2025-07-08 09:22:37 UTC
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
- Fork the repository
- Clone your fork:
git clone https://github.com/yourusername/laravel-fcm-notification.git
- Install dependencies:
composer install
- Run tests:
vendor/bin/phpunit
- Create feature branch:
git checkout -b feature/amazing-feature
- Commit changes:
git commit -m 'Add amazing feature'
- Push to branch:
git push origin feature/amazing-feature
- 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: amassi.business@gmail.com
- ๐ Issues: GitHub Issues
- ๐ Documentation: GitHub Wiki
๐ Links
Made with โค๏ธ for the Laravel community