Enhancement: Recipient rework

composer.json

@@ -20,7 +20,8 @@
     "require": {
         "php": ">=8.2",
         "ext-curl": "*",
-        "ext-json": "*"
+        "ext-json": "*",
+        "symfony/deprecation-contracts": "^3.5"
     },
     "require-dev": {
         "ergebnis/composer-normalize": "^2.43",

src/Client/GlancesClient.php

@@ -56,12 +56,12 @@ public function buildCurlPostFields(Glance $glance): array
             'user' => $glance->getRecipient()->getUserKey(),
         ];
 
-        if (!empty($glance->getRecipient()->getDevice())) {
-            if (\count($glance->getRecipient()->getDevice()) > 1) {
-                throw new LogicException(sprintf('Glance can be pushed to only one device. "%s" devices provided.', \count($glance->getRecipient()->getDevice())));
+        if (!empty($glance->getRecipient()->getDevices())) {
+            if (\count($glance->getRecipient()->getDevices()) > 1) {
+                throw new LogicException(sprintf('Glance can be pushed to only one device. "%s" devices provided.', \count($glance->getRecipient()->getDevices())));
             }
 
-            $curlPostFields['device'] = $glance->getRecipient()->getDeviceListCommaSeparated();
+            $curlPostFields['device'] = $glance->getRecipient()->getDevicesCommaSeparated();
         }
 
         $title = $glance->getGlanceDataFields()->getTitle();

src/Client/GroupsClient.php

@@ -71,8 +71,8 @@ public function buildCurlPostFields(?Recipient $recipient = null): array
             $curlPostFields['user'] = $recipient->getUserKey();
 
             if ($this->action === self::ACTION_ADD_USER) {
-                if (!empty($recipient->getDevice())) {
-                    $curlPostFields['device'] = $recipient->getDevice()[0];
+                if (!empty($recipient->getDevices())) {
+                    $curlPostFields['device'] = $recipient->getDevices()[0];
                 }
 
                 if (null !== $recipient->getMemo()) {

src/Client/MessageClient.php

@@ -56,8 +56,8 @@ public function buildCurlPostFields(Notification $notification): array
             'timestamp' => $notification->getMessage()->getTimestamp(),
         ];
 
-        if (!empty($notification->getRecipient()->getDevice())) {
-            $curlPostFields['device'] = $notification->getRecipient()->getDeviceListCommaSeparated();
+        if (!empty($notification->getRecipient()->getDevices())) {
+            $curlPostFields['device'] = $notification->getRecipient()->getDevicesCommaSeparated();
         }
 
         if (null !== $notification->getMessage()->getTitle()) {

src/Client/Response/ReceiptResponse.php

@@ -175,7 +175,7 @@ private function processCurlResponse(string $curlResponse): void
                 $recipient = new Recipient($decodedCurlResponse->acknowledged_by);
                 $recipient->addDevice($decodedCurlResponse->acknowledged_by_device);
                 $this->setAcknowledgedBy($recipient);
-                $this->setAcknowledgedByDevice($recipient->getDeviceListCommaSeparated());
+                $this->setAcknowledgedByDevice($recipient->getDevicesCommaSeparated());
             }
 
             $this->setLastDeliveredAt(new \DateTime('@'.$decodedCurlResponse->last_delivered_at));

src/Client/SubscriptionClient.php

@@ -51,12 +51,12 @@ public function buildCurlPostFields(Subscription $subscription, Recipient $recip
             'user' => $recipient->getUserKey(),
         ];
 
-        if (!empty($recipient->getDevice())) {
-            if (\count($recipient->getDevice()) > 1) {
-                throw new LogicException(sprintf('Only one device is supported. "%s" devices provided.', \count($recipient->getDevice())));
+        if (!empty($recipient->getDevices())) {
+            if (\count($recipient->getDevices()) > 1) {
+                throw new LogicException(sprintf('Only one device is supported. "%s" devices provided.', \count($recipient->getDevices())));
             }
 
-            $curlPostFields['device_name'] = $recipient->getDeviceListCommaSeparated();
+            $curlPostFields['device_name'] = $recipient->getDevicesCommaSeparated();
         }
 
         if (null !== $sound) {

src/Client/UserGroupValidationClient.php

@@ -47,12 +47,12 @@ public function buildCurlPostFields(Application $application, Recipient $recipie
             'user' => $recipient->getUserKey(),
         ];
 
-        if (!empty($recipient->getDevice())) {
-            if (\count($recipient->getDevice()) > 1) {
-                throw new LogicException(sprintf('API can validate only 1 device at a time. "%s" devices provided.', \count($recipient->getDevice())));
+        if (!empty($recipient->getDevices())) {
+            if (\count($recipient->getDevices()) > 1) {
+                throw new LogicException(sprintf('API can validate only 1 device at a time. "%s" devices provided.', \count($recipient->getDevices())));
             }
 
-            $curlPostFields['device'] = $recipient->getDeviceListCommaSeparated();
+            $curlPostFields['device'] = $recipient->getDevicesCommaSeparated();
         }
 
         return $curlPostFields;

src/Recipient.php

@@ -35,7 +35,7 @@ class Recipient
      *
      * @var array<string>
      */
-    private array $device = [];
+    private array $devices = [];
 
     /**
      * Used only when sending messages to a Group. If user is disabled in a group, they won't receive messages.
@@ -73,29 +73,46 @@ public function getUserKey(): string
      */
     public function getDevice(): array
     {
-        return $this->device;
+        trigger_deprecation('serhiy/pushover', '1.7.0', 'Method %s() is deprecated and will be removed in 2.0. Use %s() instead.', __METHOD__, 'getDevices()');
+
+        return $this->getDevices();
     }
 
     /**
-     * Adds device to the device list / array.
+     * @return array<string>
+     */
+    public function getDevices(): array
+    {
+        return $this->devices;
+    }
+
+    /**
+     * Adds device to the devices list / array.
      */
     public function addDevice(string $device): void
     {
         if (1 !== preg_match('/^[a-zA-Z0-9_-]{1,25}$/', $device)) {
             throw new InvalidArgumentException(sprintf('Device names are optional, may be up to 25 characters long, and will contain the character set [A-Za-z0-9_-]. "%s" given with "%s" characters."', $device, \strlen($device)));
         }
 
-        if (!\in_array($device, $this->device, true)) {
-            $this->device[] = $device;
+        if (!\in_array($device, $this->devices, true)) {
+            $this->devices[] = $device;
         }
     }
 
     /**
-     * Converts device array to comma separated list and returns it.
+     * Converts devices array to comma separated list and returns it.
      */
     public function getDeviceListCommaSeparated(): string
     {
-        return implode(',', $this->device);
+        trigger_deprecation('serhiy/pushover', '1.7.0', 'Method %s() is deprecated and will be removed in 2.0. Use %s() instead.', __METHOD__, 'getDevicesCommaSeparated()');
+
+        return $this->getDevicesCommaSeparated();
+    }
+
+    public function getDevicesCommaSeparated(): string
+    {
+        return implode(',', $this->devices);
     }
 
     public function isDisabled(): bool
@@ -116,7 +133,7 @@ public function getMemo(): ?string
     public function setMemo(?string $memo): void
     {
         if (\is_string($memo) && $length = \strlen($memo) > 200) {
-            throw new InvalidArgumentException('Memo contained '.$length.' characters. Memos are limited to 200 characters.');
+            throw new InvalidArgumentException(sprintf('Memo contained %s characters. Memos are limited to 200 characters.', $length));
         }
 
         $this->memo = $memo;

tests/Client/Response/RetrieveGroupResponseTest.php

@@ -56,6 +56,6 @@ public function testGetUsers(RetrieveGroupResponse $response): void
         $this->assertSame('aaaa1111AAAA1111bbbb2222BBBB22', $recipient->getUserKey());
         $this->assertFalse($recipient->isDisabled());
         $this->assertSame('This is a test memo', $recipient->getMemo());
-        $this->assertSame(['test-device-1'], $recipient->getDevice());
+        $this->assertSame(['test-device-1'], $recipient->getDevices());
     }
 }

tests/RecipientTest.php

@@ -53,6 +53,9 @@ public function testGetUserKey(): void
         $this->assertSame($userKey, $recipient->getUserKey());
     }
 
+    /**
+     * @group legacy
+     */
     public function testGetDevice(): void
     {
         $recipient = new Recipient('aaaa1111AAAA1111bbbb2222BBBB22');
@@ -62,6 +65,18 @@ public function testGetDevice(): void
         $this->assertSame(['test-device-1', 'test-device-2'], $recipient->getDevice());
     }
 
+    public function testGetDevices(): void
+    {
+        $recipient = new Recipient('aaaa1111AAAA1111bbbb2222BBBB22');
+        $recipient->addDevice('test-device-1');
+        $recipient->addDevice('test-device-2');
+
+        $this->assertSame(['test-device-1', 'test-device-2'], $recipient->getDevices());
+    }
+
+    /**
+     * @group legacy
+     */
     public function testGetDeviceListCommaSeparated(): void
     {
         $recipient = new Recipient('aaaa1111AAAA1111bbbb2222BBBB22');
@@ -71,6 +86,15 @@ public function testGetDeviceListCommaSeparated(): void
         $this->assertSame('test-device-1,test-device-2', $recipient->getDeviceListCommaSeparated());
     }
 
+    public function testGetDevicesCommaSeparated(): void
+    {
+        $recipient = new Recipient('aaaa1111AAAA1111bbbb2222BBBB22');
+        $recipient->addDevice('test-device-1');
+        $recipient->addDevice('test-device-2');
+
+        $this->assertSame('test-device-1,test-device-2', $recipient->getDevicesCommaSeparated());
+    }
+
     public function testIsDisabledReturnsFalse(): void
     {
         $recipient = new Recipient('aaaa1111AAAA1111bbbb2222BBBB22');