Deprecate CloudMessage::withTarget() in favor of toToken(), `toTo…

…pic()`, and `toCondition()`

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
 

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 <https://firebase.google.com/docs/cloud-messaging/unity/client#initia
 
     $deviceToken = '...';
 
-    $message = CloudMessage::withTarget('token', $deviceToken)
+    $message = CloudMessage::new()
         ->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'

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;

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);
     }

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]

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);
     }
 }