Rename CloudMessage target methods to with* pattern

Author: jeromegamez

CHANGELOG.md

@@ -25,6 +25,9 @@ If it saves you or your team time, please consider [sponsoring its development](
 * `psr/log` has been moved from runtime dependencies to development dependencies
 * `Kreait\Firebase\Contract\Messaging::BATCH_MESSAGE_LIMIT` constant has been removed
 * Exception codes are no longer preserved when wrapping exceptions
+* `Kreait\Firebase\Messaging\CloudMessage` builder methods have been renamed to follow the `with*` pattern:
+  `toToken()` -> `withToken()`, `toTopic()` -> `withTopic()`, `toCondition()` -> `withCondition()`.
+  The old methods are deprecated but still available as aliases.
 
 See **[UPGRADE-8.0](UPGRADE-8.0.md) for more details on the changes between 7.x and 8.0.**
 

UPGRADE-8.0.md

@@ -44,6 +44,32 @@ The `Kreait\Firebase\Contract\Messaging::BATCH_MESSAGE_LIMIT` constant has been
 ### Exception Handling Changes
 Exception codes are no longer preserved when wrapping exceptions. If your code relies on specific exception codes for error handling, you should update it to use exception types or messages instead.
 
+### Cloud Message Builder Method Renames
+
+The `CloudMessage` builder methods for setting message targets have been renamed to follow the `with*` naming pattern for consistency with other builder methods in the SDK:
+
+- `toToken()` -> `withToken()`
+- `toTopic()` -> `withTopic()`
+- `toCondition()` -> `withCondition()`
+
+**Migration:**
+
+Replace the old method names with the new ones:
+
+```php
+// Before (7.x)
+$message = CloudMessage::new()
+    ->toToken('device-token')
+    ->withNotification(['title' => 'Hello']);
+
+// After (8.0)
+$message = CloudMessage::new()
+    ->withToken('device-token')
+    ->withNotification(['title' => 'Hello']);
+```
+
+The old methods are still available as deprecated aliases, so your code will continue to work during the transition period.
+
 ---
 
 **See the complete list of breaking changes below** to identify any adjustments needed. Most changes should (hopefully)

docs/cloud-messaging.rst

@@ -33,9 +33,9 @@ Getting started
     $message = CloudMessage::new()
         ->withNotification(Notification::create('Title', 'Body'))
         ->withData(['key' => 'value'])
-        ->toToken('...')
-        // ->toTopic('...')
-        // ->toCondition('...')
+        ->withToken('...')
+        // ->withTopic('...')
+        // ->withCondition('...')
     ;
 
     $messaging->send($message);
@@ -79,7 +79,7 @@ You can create a message to a topic in one of the following ways:
     $message = CloudMessage::new()
         ->withNotification($notification) // optional
         ->withData($data) // optional
-        ->toTopic($topic)
+        ->withTopic($topic)
     ;
 
     $message = CloudMessage::fromArray([
@@ -132,7 +132,7 @@ Likewise, a user who does not subscribe to TopicA does not receive the message.
     $message = CloudMessage::new()
         ->withNotification($notification) // optional
         ->withData($data) // optional
-        ->toCondition($condition)
+        ->withCondition($condition)
     ;
 
     $message = CloudMessage::fromArray([
@@ -161,7 +161,7 @@ for each end-user client app instance.
     $message = CloudMessage::new()
         ->withNotification($notification) // optional
         ->withData($data) // optional
-        ->toToken($deviceToken)
+        ->withToken($deviceToken)
     ;
 
     $message = CloudMessage::fromArray([

src/Messaging/CloudMessage.php

@@ -233,7 +233,7 @@ public function withHighestPossiblePriority(): self
     /**
      * @param non-empty-string $token
      */
-    public function toToken(string $token): self
+    public function withToken(string $token): self
     {
         $new = clone $this;
         $new->target = MessageTarget::with(MessageTarget::TOKEN, $token);
@@ -244,7 +244,7 @@ public function toToken(string $token): self
     /**
      * @param non-empty-string $topic
      */
-    public function toTopic(string $topic): self
+    public function withTopic(string $topic): self
     {
         $new = clone $this;
         $new->target = MessageTarget::with(MessageTarget::TOPIC, $topic);
@@ -255,14 +255,47 @@ public function toTopic(string $topic): self
     /**
      * @param non-empty-string $condition
      */
-    public function toCondition(string $condition): self
+    public function withCondition(string $condition): self
     {
         $new = clone $this;
         $new->target = MessageTarget::with(MessageTarget::CONDITION, $condition);
 
         return $new;
     }
 
+    /**
+     * @param non-empty-string $token
+     *
+     * @deprecated 8.0.0 Use withToken() instead
+     * @codeCoverageIgnore
+     */
+    public function toToken(string $token): self
+    {
+        return $this->withToken($token);
+    }
+
+    /**
+     * @param non-empty-string $topic
+     *
+     * @deprecated 8.0.0 Use withTopic() instead
+     * @codeCoverageIgnore
+     */
+    public function toTopic(string $topic): self
+    {
+        return $this->withTopic($topic);
+    }
+
+    /**
+     * @param non-empty-string $condition
+     *
+     * @deprecated 8.0.0 Use withCondition() instead
+     * @codeCoverageIgnore
+     */
+    public function toCondition(string $condition): self
+    {
+        return $this->withCondition($condition);
+    }
+
     /**
      * @return MessageOutputShape
      */

tests/Integration/MessagingTest.php

@@ -140,7 +140,7 @@ public function testSendingAMessageWithEmptyMessageDataShouldNotFail(): void
     {
         $message = CloudMessage::new()
             ->withData([])
-            ->toToken($this->getTestRegistrationToken())
+            ->withToken($this->getTestRegistrationToken())
         ;
 
         $result = $this->messaging->send($message);
@@ -158,7 +158,7 @@ public function sendMessageWithReservedKeywordInMessageDataThatIsStillAccepted(s
     {
         $message = CloudMessage::new()
             ->withData([$keyword => 'value'])
-            ->toToken($this->getTestRegistrationToken())
+            ->withToken($this->getTestRegistrationToken())
         ;
 
         $result = $this->messaging->send($message);
@@ -271,10 +271,10 @@ public function testSendMessageToDifferentTargets(): void
         $message = CloudMessage::new()->withNotification(['title' => 'Token Notification', 'body' => 'Token body']);
         $invalidMessage = new RawMessageFromArray(['invalid' => 'message']);
 
-        $tokenMessage = $message->toToken($token);
-        $topicMessage = $message->toTopic($topic);
-        $conditionMessage = $message->toCondition($condition);
-        $invalidToken = $message->toToken($invalidToken);
+        $tokenMessage = $message->withToken($token);
+        $topicMessage = $message->withTopic($topic);
+        $conditionMessage = $message->withCondition($condition);
+        $invalidToken = $message->withToken($invalidToken);
 
         $messages = [$tokenMessage, $topicMessage, $conditionMessage, $invalidToken, $invalidMessage];
 
@@ -406,7 +406,7 @@ public function testSendWebPushNotificationWithAnEmptyTitle(): void
                     'title' => '',
                 ],
             ]))
-            ->toToken($this->getTestRegistrationToken());
+            ->withToken($this->getTestRegistrationToken());
 
         $this->messaging->send($message);
     }