From 9d3fa848b9bbe666a628749904b8d4a5e155e1f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Gamez?= Date: Wed, 16 Oct 2024 22:59:51 +0200 Subject: [PATCH] Deprecate `CloudMessage::withTarget()` in favor of `toToken()`, `toTopic()`, and `toCondition()` --- CHANGELOG.md | 8 ++++ docs/cloud-messaging.rst | 43 +++++++--------------- src/Firebase/Messaging/CloudMessage.php | 45 ++++++++++++++++++++++- tests/Integration/MessagingTest.php | 22 +++++++---- tests/Unit/Messaging/CloudMessageTest.php | 26 +++---------- tests/Unit/MessagingTest.php | 4 +- 6 files changed, 88 insertions(+), 60 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4c4f86b5..c268624d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,14 @@ Please read about the future of the Firebase Admin PHP SDK on the * The Messaging component doesn't rely on the `CloudMessage` class for message handling anymore. If you provide a message as an array and it has an error, the Firebase API will report it. You can still use the `CloudMessage` class as a message builder +* Deprecated the `CloudMessage::withTarget()` method, use the new `toToken()`, `toTopic()` or `toCondition()` methods instead + +### Deprecated + +* `Kreait\Firebase\Messaging\CloudMessage::withTarget()` +* `Kreait\Firebase\Messaging\CloudMessage::withChangedTarget()` +* `Kreait\Firebase\Messaging\CloudMessage::target()` +* `Kreait\Firebase\Messaging\CloudMessage::hasTarget()` ## [7.15.0] - 2024-09-11 diff --git a/docs/cloud-messaging.rst b/docs/cloud-messaging.rst index 53d24112..651f9f25 100644 --- a/docs/cloud-messaging.rst +++ b/docs/cloud-messaging.rst @@ -52,9 +52,13 @@ Getting started use Kreait\Firebase\Messaging\CloudMessage; - $message = CloudMessage::withTarget(/* see sections below */) + $message = CloudMessage::new() ->withNotification(Notification::create('Title', 'Body')) - ->withData(['key' => 'value']); + ->withData(['key' => 'value']) + ->toToken('...') + // ->toTopic('...') + // ->toCondition('...') + ; $messaging->send($message); @@ -94,9 +98,10 @@ You can create a message to a topic in one of the following ways: $topic = 'a-topic'; - $message = CloudMessage::withTarget('topic', $topic) + $message = CloudMessage::new() ->withNotification($notification) // optional ->withData($data) // optional + ->toTopic($topic) ; $message = CloudMessage::fromArray([ @@ -146,9 +151,10 @@ Likewise, a user who does not subscribe to TopicA does not receive the message. $condition = "'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)"; - $message = CloudMessage::withTarget('condition', $condition) + $message = CloudMessage::new() ->withNotification($notification) // optional ->withData($data) // optional + ->toCondition($condition) ; $message = CloudMessage::fromArray([ @@ -180,9 +186,10 @@ and `Unity withNotification($notification) // optional ->withData($data) // optional + ->toToken($deviceToken) ; $message = CloudMessage::fromArray([ @@ -314,28 +321,6 @@ you can attach data to it: $message = $message->withData($data); -*************************** -Changing the message target -*************************** - -You can change the target of an already created message with the ``withChangedTarget()`` method. - -.. code-block:: php - - use Kreait\Firebase\Messaging\CloudMessage; - - $deviceToken = '...'; - $anotherDeviceToken = '...'; - - $message = CloudMessage::withTarget('token', $deviceToken) - ->withNotification(['title' => 'My title', 'body' => 'My Body']) - ; - - $messaging->send($message); - - $sameMessageToDifferentTarget = $message->withChangedTarget('token', $anotherDeviceToken); - - ********************************************* Adding target platform specific configuration ********************************************* @@ -458,7 +443,7 @@ The SDK provides helper methods to add sounds to messages: .. code-block:: php - $message = CloudMessage::withTarget('token', $token) + $message = CloudMessage::new() ->withNotification(['title' => 'Notification title', 'body' => 'Notification body']) ->withDefaultSounds() // Enables default notifications sounds on iOS and Android devices. ->withApnsConfig( @@ -516,7 +501,7 @@ Example .. code-block:: php - $message = CloudMessage::withTarget('token', $token) + $message = CloudMessage::new() ->withNotification([ 'title' => 'If you had an iOS device…', 'body' => '… you would have received a very important message' diff --git a/src/Firebase/Messaging/CloudMessage.php b/src/Firebase/Messaging/CloudMessage.php index ad60b24c..6a2cdc73 100644 --- a/src/Firebase/Messaging/CloudMessage.php +++ b/src/Firebase/Messaging/CloudMessage.php @@ -47,12 +47,14 @@ private function __construct( } /** + * @deprecated 7.16.0 Use `CloudMessage::new()` and one of `toToken()`, `toTopic()`, or `toCondition()` instead. + * * @param MessageTarget::CONDITION|MessageTarget::TOKEN|MessageTarget::TOPIC|MessageTarget::UNKNOWN $type * @param non-empty-string $value */ public static function withTarget(string $type, string $value): self { - return self::new()->withChangedTarget($type, $value); + return new self(MessageTarget::with($type, $value)); } public static function new(): self @@ -102,6 +104,8 @@ public static function fromArray(array $data): self } /** + * @deprecated 7.16.0 Use one of `toToken()`, `toTopic()`, or `toCondition()` instead. + * * @param MessageTarget::CONDITION|MessageTarget::TOKEN|MessageTarget::TOPIC|MessageTarget::UNKNOWN $type * @param non-empty-string $value * @@ -221,11 +225,50 @@ public function withHighestPossiblePriority(): self return $new; } + /** + * @param non-empty-string $token + */ + public function toToken(string $token): self + { + $new = clone $this; + $new->target = MessageTarget::with(MessageTarget::TOKEN, $token); + + return $new; + } + + /** + * @param non-empty-string $topic + */ + public function toTopic(string $topic): self + { + $new = clone $this; + $new->target = MessageTarget::with(MessageTarget::TOPIC, $topic); + + return $new; + } + + /** + * @param non-empty-string $condition + */ + public function toCondition(string $condition): self + { + $new = clone $this; + $new->target = MessageTarget::with(MessageTarget::CONDITION, $condition); + + return $new; + } + + /** + * @deprecated 7.16.0 + */ public function hasTarget(): bool { return $this->target->type() !== MessageTarget::UNKNOWN; } + /** + * @deprecated 7.16.0 + */ public function target(): MessageTarget { return $this->target; diff --git a/tests/Integration/MessagingTest.php b/tests/Integration/MessagingTest.php index 734ac3d3..400ca778 100644 --- a/tests/Integration/MessagingTest.php +++ b/tests/Integration/MessagingTest.php @@ -135,20 +135,25 @@ public function sendRawMessage(): void #[Test] public function sendingAMessageWithEmptyMessageDataShouldNotFail(): void { - $message = CloudMessage::withTarget('token', $this->getTestRegistrationToken()) + $message = CloudMessage::new() ->withData([]) + ->toToken($this->getTestRegistrationToken()); ; $this->messaging->send($message); $this->addToAssertionCount(1); } + /** + * @param non-empty-string $keyword + */ #[DataProvider('reservedKeywordsThatStillAreAccepted')] #[Test] public function sendMessageWithReservedKeywordInMessageDataThatIsStillAccepted(string $keyword): void { - $message = CloudMessage::withTarget('token', $this->getTestRegistrationToken()) + $message = CloudMessage::new() ->withData([$keyword => 'value']) + ->toToken($this->getTestRegistrationToken()); ; $this->messaging->send($message); @@ -258,10 +263,10 @@ public function sendMessageToDifferentTargets(): void $message = CloudMessage::new()->withNotification(['title' => 'Token Notification', 'body' => 'Token body']); $invalidMessage = new RawMessageFromArray(['invalid' => 'message']); - $tokenMessage = $message->withChangedTarget('token', $token); - $topicMessage = $message->withChangedTarget('topic', $topic); - $conditionMessage = $message->withChangedTarget('condition', $condition); - $invalidToken = $message->withChangedTarget('token', $invalidToken); + $tokenMessage = $message->toToken($token); + $topicMessage = $message->toTopic($topic); + $conditionMessage = $message->toCondition($condition); + $invalidToken = $message->toToken($invalidToken); $messages = [$tokenMessage, $topicMessage, $conditionMessage, $invalidToken, $invalidMessage]; @@ -397,12 +402,13 @@ public function getAppInstanceForUnknownToken(): void #[DoesNotPerformAssertions] public function sendWebPushNotificationWithAnEmptyTitle(): void { - $message = CloudMessage::withTarget('token', $this->getTestRegistrationToken()) + $message = CloudMessage::new() ->withWebPushConfig(WebPushConfig::fromArray([ 'notification' => [ 'title' => '', ], - ])); + ])) + ->toToken($this->getTestRegistrationToken()); $this->messaging->send($message); } diff --git a/tests/Unit/Messaging/CloudMessageTest.php b/tests/Unit/Messaging/CloudMessageTest.php index d111aaf8..1e04fb63 100644 --- a/tests/Unit/Messaging/CloudMessageTest.php +++ b/tests/Unit/Messaging/CloudMessageTest.php @@ -11,7 +11,6 @@ use Kreait\Firebase\Messaging\FcmOptions; use Kreait\Firebase\Messaging\MessageData; use Kreait\Firebase\Messaging\MessageTarget; -use Kreait\Firebase\Messaging\Notification; use PHPUnit\Framework\Attributes\DataProvider; use PHPUnit\Framework\Attributes\Test; use PHPUnit\Framework\TestCase; @@ -28,27 +27,14 @@ public function emptyMessage(): void } #[Test] - public function withChangedTarget(): void + public function anEmptyMessageHasNoTarget(): void { - $original = CloudMessage::withTarget(MessageTarget::TOKEN, 'bar') - ->withData(['foo' => 'bar']) - ->withNotification(Notification::create('title', 'body')) - ; - - $changed = $original->withChangedTarget(MessageTarget::TOKEN, 'baz'); - - $encodedOriginal = Json::decode(Json::encode($original), true); - $encodedOriginal[MessageTarget::TOKEN] = 'baz'; - - $encodedChanged = Json::decode(Json::encode($changed), true); - - $this->assertSame($encodedOriginal, $encodedChanged); - } + $message = CloudMessage::new(); + $payload = Json::decode(Json::encode($message), true); - #[Test] - public function anEmptyMessageHasNotTarget(): void - { - $this->assertFalse(CloudMessage::new()->hasTarget()); + $this->assertArrayNotHasKey('token', $payload); + $this->assertArrayNotHasKey('condition', $payload); + $this->assertArrayNotHasKey('topic', $payload); } #[Test] diff --git a/tests/Unit/MessagingTest.php b/tests/Unit/MessagingTest.php index dc7ef0fc..2ab83f5f 100644 --- a/tests/Unit/MessagingTest.php +++ b/tests/Unit/MessagingTest.php @@ -56,9 +56,9 @@ public function itWillNotSendAMessageWithoutATarget(): void { $message = CloudMessage::new(); - $this->assertFalse($message->hasTarget()); - $this->expectException(InvalidArgumentException::class); + $this->expectExceptionMessageMatches('/missing a target/'); + $this->messaging->send($message); } }