FCM PHP API

A robust PHP implementation for sending push notifications using the Firebase Cloud Messaging (FCM) HTTP v1 API. This solution handles OAuth 2.0 authentication without external SDK dependencies, making it suitable for lightweight server environments and microservices.

Key Features

• OAuth 2.0 Implementation: Handles Google assertion flow via JWT for secure access token generation.
• HTTP v1 Compliance: Fully compatible with the latest Firebase Cloud Messaging standards.
• Flexible Payloads: Supports both standard notifications and custom data objects.
• Optimized for Android: Configures high-priority delivery and notification channels out-of-the-box.
• Production Ready: Includes environment variable support for secret management and a Docker configuration for rapid deployment.

Security and Best Practices

To maintain security in public repositories and production environments:

1. Credential Protection: The service-account.json file is excluded via .gitignore. Never commit this file to version control.
2. Environment Variables: In production, it is recommended to use the FCM_SERVICE_ACCOUNT environment variable. The system will prioritize this variable over the physical JSON file.

Prerequisites

• PHP: Version 8.2 or higher.
• Required Extensions:
  • openssl: Necessary for JWT signing.
  • curl: Used for API communication with Google and FCM.
• Firebase Account: A service account key with the "Firebase Messaging Admin" role.

Setup and Configuration

1. Obtain Service Account Key

• Visit the Firebase Console.
• Navigate to Project Settings > Service Accounts.
• Generate a new private key and save it as service-account.json in the project root for local development.

2. Configure Project ID

In send_notification.php, update the $projectId variable to match your Firebase Project ID.

3. Using Environment Variables

For public deployments, set an environment variable FCM_SERVICE_ACCOUNT containing the entire JSON content of your service account key.

Usage Examples

External Request (cURL)

You can trigger notifications via standard HTTP POST requests:

curl -X POST http://your-api-domain.com/send_notification.php \
     -d "fcm_token=TARGET_DEVICE_TOKEN" \
     -d "title=System Alert" \
     -d "body=This is a notification message" \
     -d "senderName=MonitoringSvc" \
     -d "chat_id=alert_001"

Programmatic Usage (PHP)

Example of calling this API from another PHP script:

<?php
$apiUrl = "http://your-api-domain.com/send_notification.php";
$data = [
    'fcm_token'  => 'DEVICE_TOKEN_HERE',
    'title'      => 'Hello World',
    'body'       => 'Test message via PHP cURL',
    'senderName' => 'MyApp'
];

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Deployment for 24/7 Availability

For continuous availability, hosting services that support Docker or persistent PHP environments are recommended.

Deploying on Render.com

Render is an excellent option for hosting this API for free or low cost with 24/7 uptime.

1. Connect GitHub: Create a new Web Service on Render and connect your repository.
2. Environment Setup:
   • Language: Select Docker.
   • Branch: main.
3. Environment Variables:
   • Under the Env Vars tab, add FCM_SERVICE_ACCOUNT and paste the entire content of your service-account.json.
4. Deploy: Render will build the image using the provided Dockerfile and start the Apache server on port 80.

Other Hosting Options

• Railway.app: Similar to Render, supports Docker-based deployments with easy environment variable management.
• DigitalOcean App Platform: A robust managed solution for scaling PHP/Docker applications.

Troubleshooting

Common Issues

Issue	Potential Cause	Solution
FCM Credentials NOT FOUND	service-account.json missing and FCM_SERVICE_ACCOUNT env var not set.	Ensure the JSON file exists locally or the environment variable is configured in your hosting dashboard.
OpenSSL NOT ENABLED	The PHP openssl extension is missing on the server.	Install/enable php-openssl in your php.ini or server configuration.
401 Unauthorized	Project ID mismatch or invalid Service Account key.	Verify the $projectId in send_notification.php matches your Firebase project.
404 Project Not Found	Incorrect Project ID in the URL.	Double-check that the Project ID in send_notification.php is exactly as shown in Firebase.
CURL ERROR: SSL certificate problem	Local server cannot verify Google's SSL certificates.	Update your server's CA bundle or set CURLOPT_SSL_VERIFYPEER to false (not recommended for production).

Debugging

If you encounter issues, check the API response directly. The send_notification.php script returns the raw FCM response and the HTTP status code, which provides detailed error descriptions from Google.

License

MIT License. See LICENSE for details.