Merge pull request #33 from b24io/feature/32-add-mobile-phone-node-v3

Feature/32 add mobile phone node v3

CHANGELOG.md

@@ -1,5 +1,32 @@
 # loyalty-php-sdk
 
+## Upcoming
+
+### Added
+* WIP add support for email account for contacts
+
+
+## 3.3.0 (2024.07.10)
+
+### Added
+* add requirements:
+    * `nesbot/carbon` version `^2.*`,
+* add `MobilePhoneItemResult` – information about mobile phone.
+* add support for mobile phone for `ContactItemResult`
+* add support for mobile phone for `CardItemResult`
+
+### Changed
+
+* change signature for method `Loyalty\SDK\Services\Admin\Contacts::add`, argument `$mobilePhone` can be nullable.
+* change signature for method  `Loyalty\SDK\Services\Admin\Contacts::getById` from `ContactItemResult` to `ContactResult`
+* change signature for method  `Loyalty\SDK\Services\Admin\Cards::getById` from `CardItemResult` to `CardResult`
+* change `DateTimeImmutable` to `CarbonImmutable` in all results
+
+## 3.2.0 (2024.05.23)
+
+* Downgrade branch v3 to `PHP 7.4`
+* Bump branch v4 to `PHP 8.2`
+
 ## 3.1.0 (2024.05.11)
 
 * add requirements:

composer.json

@@ -35,6 +35,7 @@
     "symfony/uid": "^5.4 || 7.*",
     "symfony/filesystem": "^5.4 || 7.*",
     "moneyphp/money": "^3.3 || 4.*",
+    "nesbot/carbon": "^2.0",
     "giggsey/libphonenumber-for-php": "8.1.*",
     "league/csv": "^9.0",
     "mesilov/moneyphp-percentage": "0.1.0 || 0.2.0"

docker-compose.yml

@@ -1,4 +1,4 @@
-version: '3'
+version: '3.8'
 
 services:
   php-cli:

phpstan.neon

@@ -4,4 +4,5 @@ parameters:
     - src/
     - tests/
   bootstrapFiles:
-    - tests/bootstrap.php
+    - tests/bootstrap.php
+  treatPhpDocTypesAsCertain: false

src/Common/FullName.php

@@ -18,10 +18,25 @@ class FullName
      * @readonly
      */
     public ?string $patronymic = null;
-    public function __construct(string  $name, ?string $surname = null, ?string $patronymic = null)
+
+    public function __construct(string $name, ?string $surname = null, ?string $patronymic = null)
     {
-        $this->name = $name;
+        $this->name = trim($name);
+
+        if ($surname !== null) {
+            $surname = trim($surname);
+        }
+        if ($surname === '') {
+            $surname = null;
+        }
         $this->surname = $surname;
+
+        if ($patronymic !== null) {
+            $patronymic = trim($patronymic);
+        }
+        if ($patronymic === '') {
+            $patronymic = null;
+        }
         $this->patronymic = $patronymic;
     }
 
@@ -36,4 +51,9 @@ public function toArray(): array
             'patronymic' => $this->patronymic
         ];
     }
+
+    public function equals(self $fullName): bool
+    {
+        return $this->name === $fullName->name && $this->surname === $fullName->surname && $this->patronymic === $fullName->patronymic;
+    }
 }

src/Common/Result/Cards/CardItemResult.php

@@ -5,9 +5,11 @@
 namespace B24io\Loyalty\SDK\Common\Result\Cards;
 
 use B24io\Loyalty\SDK\Common\Result\Contacts\ContactItemResult;
+use B24io\Loyalty\SDK\Common\Result\Contacts\MobilePhoneItemResult;
 use B24io\Loyalty\SDK\Core\Exceptions\InvalidArgumentException;
 use B24io\Loyalty\SDK\Core\Result\AbstractItem;
-use DateTimeImmutable;
+use Carbon\CarbonImmutable;
+use Exception;
 use Money\Currency;
 use Money\Money;
 use MoneyPHP\Percentage\Percentage;
@@ -19,19 +21,20 @@
  * @property-read string $barcode
  * @property-read Money $balance
  * @property-read Percentage $percentage
- * @property-read DateTimeImmutable $created
- * @property-read DateTimeImmutable $modified
+ * @property-read CarbonImmutable $created
+ * @property-read CarbonImmutable $modified
  * @property-read CardStatus $status
  * @property-read string $externalId
  * @property-read ?CardLevelItemResult $level
  * @property-read ContactItemResult $contact
+ * @property-read MobilePhoneItemResult|null $mobilePhone
  */
 class CardItemResult extends AbstractItem
 {
     /**
      * @param int|string $offset
      * @throws InvalidArgumentException
-     * @throws \Exception
+     * @throws Exception
      */
     public function __get($offset)
     {
@@ -57,6 +60,11 @@ public function __get($offset)
                     return null;
                 }
                 return new ContactItemResult($this->data[$offset]);
+            case 'mobilePhone':
+                if ($this->data['mobile_phone'] === null) {
+                    return null;
+                }
+                return new MobilePhoneItemResult($this->data['mobile_phone']);
             default:
                 return parent::__get($offset);
         }

src/Common/Result/Cards/CardLevelItemResult.php

@@ -5,6 +5,7 @@
 namespace B24io\Loyalty\SDK\Common\Result\Cards;
 
 use B24io\Loyalty\SDK\Core\Result\AbstractItem;
+use Carbon\CarbonImmutable;
 use DateTimeImmutable;
 use Exception;
 use MoneyPHP\Percentage\Percentage;
@@ -18,8 +19,8 @@
  * @property-read Percentage $defaultPercentage
  * @property-read string $description
  * @property-read string $externalId
- * @property-read DateTimeImmutable $created
- * @property-read DateTimeImmutable $modified
+ * @property-read CarbonImmutable $created
+ * @property-read CarbonImmutable $modified
  */
 class CardLevelItemResult extends AbstractItem
 {

src/Common/Result/Cards/CardResult.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace B24io\Loyalty\SDK\Common\Result\Cards;
+
+use B24io\Loyalty\SDK\Core\Result\AbstractResult;
+
+class CardResult extends AbstractResult
+{
+    public function getCard(): CardItemResult
+    {
+        return new CardItemResult($this->getCoreResponse()->getResponseData()->result);
+    }
+}

src/Common/Result/Contacts/ContactItemResult.php

@@ -23,12 +23,14 @@
  * @property-read DateTimeImmutable $created
  * @property-read DateTimeImmutable $modified
  * @property-read ?CardItemResult $card
+ * @property-read MobilePhoneItemResult|null $mobilePhone
  */
 class ContactItemResult extends AbstractItem
 {
     /**
      * @param int|string $offset
      * @throws InvalidArgumentException
+     * @throws \Exception
      */
     public function __get($offset)
     {
@@ -56,6 +58,11 @@ public function __get($offset)
                     return null;
                 }
                 return new CardItemResult($this->data['card']);
+            case 'mobilePhone':
+                if ($this->data['mobile_phone'] === null) {
+                    return null;
+                }
+                return new MobilePhoneItemResult($this->data['mobile_phone']);
             default:
                 return parent::__get($offset);
         }

src/Common/Result/Contacts/ContactResult.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace B24io\Loyalty\SDK\Common\Result\Contacts;
+
+use B24io\Loyalty\SDK\Core\Result\AbstractResult;
+
+class ContactResult extends AbstractResult
+{
+    public function getContact(): ContactItemResult
+    {
+        return new ContactItemResult($this->getCoreResponse()->getResponseData()->result);
+    }
+}

src/Common/Result/Contacts/MobilePhoneItemResult.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace B24io\Loyalty\SDK\Common\Result\Contacts;
+
+use B24io\Loyalty\SDK\Common\VerificationStatus;
+use B24io\Loyalty\SDK\Core\Exceptions\InvalidArgumentException;
+use B24io\Loyalty\SDK\Core\Result\AbstractItem;
+use Exception;
+use libphonenumber\PhoneNumber;
+use libphonenumber\PhoneNumberUtil;
+
+
+/**
+ * @property-read PhoneNumber $phoneNumber
+ * @property-read VerificationStatus $verificationStatus
+ */
+class MobilePhoneItemResult extends AbstractItem
+{
+    /**
+     * @param int|string $offset
+     * @throws Exception
+     */
+    public function __get($offset)
+    {
+        switch ($offset) {
+            case 'verificationStatus':
+                return new VerificationStatus($this->data['verification_status']);
+            case 'phoneNumber':
+                $phoneNumberUtil = PhoneNumberUtil::getInstance();
+                if ($phoneNumberUtil === null) {
+                    throw new InvalidArgumentException('cannot create libphonenumber util instance');
+                }
+                return $phoneNumberUtil->parse($this->data['number'], '');
+            default:
+                return parent::__get($offset);
+        }
+    }
+}

src/Common/Result/Transactions/TransactionItemResult.php

@@ -7,6 +7,7 @@
 use B24io\Loyalty\SDK\Common\Reason;
 use B24io\Loyalty\SDK\Common\TransactionType;
 use B24io\Loyalty\SDK\Core\Result\AbstractItem;
+use Carbon\CarbonImmutable;
 use DateTimeImmutable;
 use Exception;
 use Money\Currency;
@@ -19,7 +20,7 @@
  * @property-read string $cardNumber
  * @property-read Money $value
  * @property-read TransactionType $type
- * @property-read DateTimeImmutable $created
+ * @property-read CarbonImmutable $created
  * @property-read Reason $reason
  */
 class TransactionItemResult extends AbstractItem

src/Common/VerificationStatus.php

@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+namespace B24io\Loyalty\SDK\Common;
+
+use B24io\Loyalty\SDK\Core\Exceptions\InvalidArgumentException;
+
+class VerificationStatus
+{
+    private const unverified = 'unverified';
+    private const verified = 'verified';
+    private const in_process = 'in_process';
+    private string $value;
+
+    /**
+     * @throws InvalidArgumentException
+     */
+    public function __construct(string $verificationStatus)
+    {
+        $allowed = [self::unverified, self::verified, self::in_process];
+        if (!in_array($verificationStatus, $allowed)) {
+            throw new InvalidArgumentException(sprintf('unknown verification status %s, use one of %s', $verificationStatus, implode(', ', $allowed)));
+        }
+        $this->value = $verificationStatus;
+    }
+
+    public function __toString()
+    {
+        return $this->value;
+    }
+
+    public static function unverified(): self
+    {
+        return new self(self::unverified);
+    }
+
+    public static function verified(): self
+    {
+        return new self(self::verified);
+    }
+
+    public static function inProcess(): self
+    {
+        return new self(self::in_process);
+    }
+
+    public function equals(self $status): bool
+    {
+        return $this->value === (string)$status;
+    }
+
+    public function isUnverified(): bool
+    {
+        return $this->value === self::unverified;
+    }
+
+    public function isVerified(): bool
+    {
+        return $this->value === self::verified;
+    }
+
+    public function isInProcess(): bool
+    {
+        return $this->value === self::in_process;
+    }
+}

src/Core/ApiClient.php

@@ -69,7 +69,7 @@ public function getResponse(
         $this->logger->info(
             'getResponse.start',
             [
-                'context' => $context,
+                'context' => (string)$context,
                 'apiMethod' => $apiMethod,
                 'domainUrl' => $this->credentials->domainUrl,
                 'parameters' => $parameters,

src/Core/Result/AbstractItem.php

@@ -7,7 +7,7 @@
 use ArrayIterator;
 use B24io\Loyalty\SDK\Common\Reason;
 use B24io\Loyalty\SDK\Core\Exceptions\ImmutableResultViolationException;
-use DateTimeImmutable;
+use Carbon\CarbonImmutable;
 use Exception;
 use IteratorAggregate;
 use Money\Currencies\ISOCurrencies;
@@ -25,7 +25,6 @@ abstract class AbstractItem implements IteratorAggregate
      */
     protected array $data;
     protected DecimalMoneyParser $decimalMoneyParser;
-
     /**
      * @param array<string, mixed> $data
      */
@@ -58,7 +57,7 @@ public function __get($offset)
                 return (string)$this->data['external_id'];
             case 'created':
             case 'modified':
-                return new DateTimeImmutable($this->data[$offset]);
+                return new CarbonImmutable($this->data[$offset]);
             case 'reason':
                 return new Reason(
                     $this->data[$offset]['id'],