Compatibility with FCM HTTP v1 API

Author: erickskrauch

.github/workflows/ci.yml

@@ -16,10 +16,11 @@ jobs:
           - '8.0'
           - '8.1'
           - '8.2'
+          - '8.3'
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup PHP
         uses: shivammathur/setup-php@v2

CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Added
+- Compatibility with FCM HTTP v1 API.
+
+### Changed
+- Signature of the `\ErickSkrauch\Fcm\Client` class now requires the `projectId` param.
+- The return type of the `\ErickSkrauch\Fcm\Client::send()` method is changed to `string`.
+- `\ErickSkrauch\Fcm\Client::send()` now throws `\ErickSkrauch\Fcm\Exception\ErrorResponseException`.
+
+### Removed
+- `ErickSkrauch\Fcm\Recipient\MultipleDevices` and `ErickSkrauch\Fcm\Recipient\MultipleTopics` recipients. Iterate over per-device or per-topic to archive the same behavior.
+- `ErickSkrauch\Fcm\Response\SendResponse`.
+
+### Fixed
+- Deprecation error with nullable arguments for PHP 8.4.
 
 ## [0.2.1] - 2022-12-21
 ### Fixed

README.md

@@ -34,7 +34,7 @@ use ErickSkrauch\Fcm\Message\Message;
 use ErickSkrauch\Fcm\Message\Notification;
 use ErickSkrauch\Fcm\Recipient\Device;
 
-$client = new Client('YOUR SERVER KEY');
+$client = new Client('SERVICE ACCOUNT OAUTH TOKEN', 'project-x146w');
 
 $notification = new Notification(, 'testing body');
 $notification->setTitle('Wow, something happened...');
@@ -44,35 +44,11 @@ $message = new Message();
 $message->setNotification($notification);
 $message->setCollapseKey('collapse.key');
 
-$recipient = new Device('your-device-token');
+$recipient = new Device('your-device-token'); // or new ErickSkrauch\Fcm\Recipient\Topic('topic');
 
 $result = $client->send($message, $recipient);
 ```
 
-The library provides several implementations for the `Recipient` interface:
-* `Device` is used to send notifications to a single device.
-* `Topic` is used to send notifications to a single topic. 
-* `MultipleDevices` is used to send notifications to multiple devices. The FCM documentation doesn't recommend using this method to send to 1 device.
-* `MultipleTopics` is used to send notifications to multiple topics combined by the operator `||`.
-
-At the moment, the library does not have a builder for complex conditions. But you can always create your own implementation of the `Recipient` interface:
-
-```php
-use ErickSkrauch\Fcm\Recipient\Recipient;
-
-class MyComplexCondition implements Recipient {
-
-    public function getConditionParam(): string{
-        return Recipient::PARAM_CONDITION;
-    }
-    
-    public function getConditionValue(): string {
-        return "'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)";
-    }
-
-}
-```
-
 ## Contribute
 
 This library in an Open Source under the MIT license. It is, thus, maintained by collaborators and contributors.

src/Client.php

@@ -3,10 +3,10 @@
 
 namespace ErickSkrauch\Fcm;
 
+use ErickSkrauch\Fcm\Exception\ErrorResponseException;
 use ErickSkrauch\Fcm\Exception\UnexpectedResponseException;
 use ErickSkrauch\Fcm\Message\Message;
 use ErickSkrauch\Fcm\Recipient\Recipient;
-use ErickSkrauch\Fcm\Response\SendResponse;
 use Http\Discovery\Psr17FactoryDiscovery;
 use Http\Discovery\Psr18ClientDiscovery;
 use Psr\Http\Client\ClientInterface as HttpClientInterface;
@@ -17,52 +17,52 @@ final class Client implements ClientInterface {
 
     private string $apiKey;
 
+    private string $projectName;
+
     private HttpClientInterface $httpClient;
 
     private HttpRequestFactoryInterface $requestFactory;
 
     private StreamFactoryInterface $streamFactory;
 
     /**
-     * @param string $apiKey read how to obtain an api key here: https://firebase.google.com/docs/server/setup#prerequisites
-     * @param HttpClientInterface|null $httpClient
-     * @param HttpRequestFactoryInterface|null $requestFactory
-     * @param StreamFactoryInterface|null $streamFactory
+     * @param string $oauthToken you must generate the JWT key for your service account with a scope "https://www.googleapis.com/auth/firebase.messaging"
+     * @param string $projectId you can find the project's ID here: https://console.firebase.google.com. Copy the gray text under the project name. For example "myapp-5427d"
      */
     public function __construct(
-        string $apiKey,
-        HttpClientInterface $httpClient = null,
-        HttpRequestFactoryInterface $requestFactory = null,
-        StreamFactoryInterface $streamFactory = null
+        string $oauthToken,
+        string $projectId,
+        ?HttpClientInterface $httpClient = null,
+        ?HttpRequestFactoryInterface $requestFactory = null,
+        ?StreamFactoryInterface $streamFactory = null
     ) {
-        $this->apiKey = $apiKey;
+        $this->apiKey = $oauthToken;
+        $this->projectName = $projectId;
         $this->httpClient = $httpClient ?? Psr18ClientDiscovery::find();
         $this->requestFactory = $requestFactory ?? Psr17FactoryDiscovery::findRequestFactory();
         $this->streamFactory = $streamFactory ?? Psr17FactoryDiscovery::findStreamFactory();
     }
 
-    public function send(Message $message, Recipient $recipient): SendResponse {
+    public function send(Message $message, Recipient $recipient): string {
         $json = $message->getPayload();
         $json[$recipient->getConditionParam()] = $recipient->getConditionValue();
 
-        $request = $this->requestFactory->createRequest('POST', 'https://fcm.googleapis.com/fcm/send');
-        $request = $request->withHeader('Authorization', "key={$this->apiKey}");
+        $request = $this->requestFactory->createRequest('POST', "https://fcm.googleapis.com/v1/projects/{$this->projectName}/messages:send");
+        $request = $request->withHeader('Authorization', "Bearer {$this->apiKey}");
         $request = $request->withHeader('Content-Type', 'application/json');
-        $request = $request->withBody($this->streamFactory->createStream(json_encode($json, JSON_THROW_ON_ERROR)));
+        $request = $request->withBody($this->streamFactory->createStream(json_encode(['message' => $json], JSON_THROW_ON_ERROR)));
 
         $response = $this->httpClient->sendRequest($request);
-        if ($response->getStatusCode() !== 200) {
-            throw new UnexpectedResponseException($response);
+        if (!in_array($response->getStatusCode(), [200, 400], true)) {
+            throw new UnexpectedResponseException("Received unexpected FCM response with {$response->getStatusCode()} status code", $response);
         }
 
         $json = json_decode((string)$response->getBody(), true, JSON_THROW_ON_ERROR);
+        if (isset($json['error'])) {
+            throw new ErrorResponseException($json['error']['message'], $json['error']['status'], $response);
+        }
 
-        return new SendResponse(
-            $json['multicast_id'],
-            $json['success'],
-            $json['failure'],
-            $json['results'],
-        );
+        return $json['name'];
     }
 
 }

src/ClientInterface.php

@@ -5,20 +5,20 @@
 
 use ErickSkrauch\Fcm\Message\Message;
 use ErickSkrauch\Fcm\Recipient\Recipient;
-use ErickSkrauch\Fcm\Response\SendResponse;
 
 interface ClientInterface {
 
     /**
      * Sends your notification to the FCM and returns a raw response
      *
-     * @param Message $message
-     * @param Recipient $recipient
+     * @see https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages/send
      *
-     * @return SendResponse
+     * @return string the send ID from FCM
      * @throws \Psr\Http\Client\ClientExceptionInterface
      * @throws \ErickSkrauch\Fcm\Exception\UnexpectedResponseException
+     * @throws \ErickSkrauch\Fcm\Exception\ErrorResponseException
+     * @throws \JsonException
      */
-    public function send(Message $message, Recipient $recipient): SendResponse;
+    public function send(Message $message, Recipient $recipient): string;
 
 }

src/Exception/ErrorResponseException.php

@@ -0,0 +1,27 @@
+<?php
+declare(strict_types=1);
+
+namespace ErickSkrauch\Fcm\Exception;
+
+use Exception;
+use Psr\Http\Message\ResponseInterface;
+
+final class ErrorResponseException extends Exception {
+
+    /**
+     * @readonly
+     */
+    public string $errorCode;
+
+    /**
+     * @readonly
+     */
+    public ResponseInterface $response;
+
+    public function __construct(string $message, string $errorCode, ResponseInterface $response) {
+        $this->errorCode = $errorCode;
+        $this->response = $response;
+        parent::__construct($message, $response->getStatusCode());
+    }
+
+}

src/Exception/UnexpectedResponseException.php

@@ -8,15 +8,14 @@
 
 final class UnexpectedResponseException extends Exception {
 
-    private ResponseInterface $response;
+    /**
+     * @readonly
+     */
+    public ResponseInterface $response;
 
-    public function __construct(ResponseInterface $response) {
-        parent::__construct('Received an unexpected response from FCM');
+    public function __construct(string $message, ResponseInterface $response) {
         $this->response = $response;
-    }
-
-    public function getResponse(): ResponseInterface {
-        return $this->response;
+        parent::__construct($message, $response->getStatusCode());
     }
 
 }

src/Message/Message.php

@@ -18,7 +18,7 @@ final class Message {
      *     mutable_content?: true,
      *     content_available?: true,
      *     image?: string,
-     *     data?: array<string, string|int>,
+     *     data?: string,
      * }
      */
     private array $data = [];
@@ -87,10 +87,12 @@ public function setImage(string $imageUrl): self {
 
     /**
      * @see https://firebase.google.com/docs/cloud-messaging/http-server-ref#data
-     * @param array<string, string|int> $data
+     * @param array<mixed> $data
      */
     public function setData(array $data): self {
-        $this->data['data'] = $data;
+        // https://firebase.google.com/docs/cloud-messaging/migrate-v1#example-nested-json-data
+        $this->data['data'] = json_encode($data, JSON_THROW_ON_ERROR);
+
         return $this;
     }
 
@@ -104,7 +106,7 @@ public function setData(array $data): self {
      *     mutable_content?: true,
      *     content_available?: true,
      *     image?: string,
-     *     data?: array<string, string|int>,
+     *     data?: string,
      * }
      */
     public function getPayload(): array {

src/Message/Notification.php

@@ -106,7 +106,7 @@ public function setSound(string $sound): self {
      * @param array<string|int>|null $args
      * @return self
      */
-    public function setTitleLocKey(string $titleLocKey, array $args = null): self {
+    public function setTitleLocKey(string $titleLocKey, ?array $args = null): self {
         if (isset($this->data['title'])) {
             throw new InvalidArgumentException('You cannot use "title" and "title_loc_key" at the same time');
         }
@@ -124,7 +124,7 @@ public function setTitleLocKey(string $titleLocKey, array $args = null): self {
      * @param array<string|int>|null $args
      * @return self
      */
-    public function setBodyLocKey(string $bodyLocKey, array $args = null): self {
+    public function setBodyLocKey(string $bodyLocKey, ?array $args = null): self {
         if (isset($this->data['body'])) {
             throw new InvalidArgumentException('You cannot use "body" and "body_loc_key" at the same time');
         }

src/Recipient/Device.php

@@ -12,7 +12,7 @@ public function __construct(string $token) {
     }
 
     public function getConditionParam(): string {
-        return Recipient::PARAM_TO;
+        return 'token';
     }
 
     public function getConditionValue(): string {