Новая сущность Kkt для ответов мониторинга (#8) + мелкий рефакторинг

- enum-константы перенесены в своё пространство Enums
- новые исключения EmptyMonitorDataException + NotEnoughMonitorDataException
- KktMonitor::getAll() теперь возвращает коллекцию объектов Kkt
- KktMonitor::getOne() теперь возвращает объект Kkt
- местами актуализированы return types + phpdoc

Покрытие тестами:
- 61% исключений
- 98% AtolClient (пока хз как покрыть 208-ую строку)
- 100% KktMonitor
- 100% Kkt
- 100% Client
- 100% Company
- 100% Entity

src/Api/KktMonitor.php

@@ -11,9 +11,11 @@ declare(strict_types = 1);
 
 namespace AtolOnline\Api;
 
+use AtolOnline\Entities\Kkt;
+use AtolOnline\Exceptions\EmptyMonitorDataException;
+use AtolOnline\Exceptions\NotEnoughMonitorDataException;
 use GuzzleHttp\Exception\GuzzleException;
 use Illuminate\Support\Collection;
-use stdClass;
 
 /**
  * Класс для мониторинга ККТ
@@ -85,7 +87,8 @@ class KktMonitor extends AtolClient
      */
     public function getAll(?int $limit = null, ?int $offset = null): Collection
     {
-        return collect($this->fetchAll($limit, $offset)->getContent());
+        $collection = collect($this->fetchAll($limit, $offset)->getContent());
+        return $collection->map(fn($data) => new Kkt($data));
     }
 
     /**
@@ -114,12 +117,14 @@ class KktMonitor extends AtolClient
      *
      * @todo кастовать к отдельному классу со своими геттерами
      * @param string $serial_number
-     * @return stdClass
+     * @return Kkt
      * @throws GuzzleException
+     * @throws EmptyMonitorDataException
+     * @throws NotEnoughMonitorDataException
      * @see https://online.atol.ru/files/API_service_information.pdf Документация, стр 11
      */
-    public function getOne(string $serial_number): stdClass
+    public function getOne(string $serial_number): Kkt
     {
-        return $this->fetchOne($serial_number)->getContent()->data;
+        return new Kkt($this->fetchOne($serial_number)->getContent()->data);
     }
 }

src/Entities/Company.php

@@ -13,7 +13,7 @@ namespace AtolOnline\Entities;
 
 use AtolOnline\{
     Constants\Constraints,
-    Constants\SnoTypes,
+    Enums\SnoTypes,
     Exceptions\InvalidEmailException,
     Exceptions\InvalidInnLengthException,
     Exceptions\InvalidPaymentAddressException,

src/Entities/Entity.php

@@ -28,4 +28,4 @@ abstract class Entity implements JsonSerializable, Stringable
     {
         return json_encode($this->jsonSerialize(), JSON_UNESCAPED_UNICODE);
     }
-}
+}

src/Entities/Kkt.php

@@ -0,0 +1,149 @@
+<?php
+/*
+ * Copyright (c) 2020-2021 Антон Аксенов (Anthony Axenov)
+ *
+ * This code is licensed under MIT.
+ * Этот код распространяется по лицензии MIT.
+ * https://github.com/anthonyaxenov/atol-online/blob/master/LICENSE
+ */
+
+declare(strict_types = 1);
+
+namespace AtolOnline\Entities;
+
+use AtolOnline\Exceptions\EmptyMonitorDataException;
+use AtolOnline\Exceptions\NotEnoughMonitorDataException;
+use DateTime;
+use Exception;
+
+/**
+ * Класс сущности ККТ, получаемой от монитора
+ *
+ * @property string|null serialNumber Заводской номер ККТ
+ * @property string|null registrationNumber Регистрационный номер машины (РНМ)
+ * @property string|null deviceNumber Номер автоматического устройства (внутренний идентификатор устройства)
+ * @property DateTime|string|null fiscalizationDate Дата активации (фискализации) ФН с указанием таймзоны
+ * @property DateTime|string|null fiscalStorageExpiration Дата замены ФН (Срок действия ФН), с указанием таймзоны
+ * @property int|null signedDocuments Количество подписанных документов в ФН
+ * @property float|null fiscalStoragePercentageUse Наполненость ФН в %
+ * @property string|null fiscalStorageINN ИНН компании (указанный в ФН)
+ * @property string|null fiscalStorageSerialNumber Заводской (серийный) номер ФН
+ * @property string|null fiscalStoragePaymentAddress Адрес расчёта, указанный в ФН
+ * @property string|null groupCode Код группы кассы
+ * @property DateTime|string|null timestamp Время и дата формирования данных, UTC
+ * @property bool|null isShiftOpened Признак открыта смена (true) или закрыта (false)
+ * @property int|null shiftNumber Номер смены (или "Номер закрытой смены", когда смена закрыта)
+ * @property int|null shiftReceipt Номер документа за смену (или "Кол-во чеков закрытой смены", когда смена закрыта)
+ * @property int|null unsentDocs Количество неотправленных документов. Указывается, если значение отлично от 0.
+ * @property DateTime|string|null firstUnsetDocTimestamp Дата первого неотправленного документа. Указывается, если
+ * есть неотправленные документы.
+ * @property int|null networkErrorCode Код ошибки сети
+ * @see https://online.atol.ru/files/API_service_information.pdf Документация, стр 11
+ */
+final class Kkt extends Entity
+{
+    /**
+     * Сопоставление кодов сетевых ошибок ККТ с их описаниями
+     */
+     public const ERROR_CODES = [
+        0 => 'Нет ошибок',
+        1 => 'Отсутствует физический канал связи',
+        2 => 'Ошибка сетевых настроек или нет соединения с сервером ОФД',
+        3 => 'Разрыв соединения при передаче документа на сервер',
+        4 => 'Некорректный заголовок сессионного пакета',
+        5 => 'Превышен таймаут ожидания квитанции',
+        6 => 'Разрыв соединения при приеме квитанции',
+        7 => 'Превышен таймаут передачи документа на сервер',
+        8 => 'ОФД-процесс не иницилизирован',
+    ];
+
+    /**
+     * @var string[] Список обязательных атрибутов
+     */
+    private array $properties = [
+        'serialNumber',
+        'registrationNumber',
+        'deviceNumber',
+        'fiscalizationDate',
+        'fiscalStorageExpiration',
+        'signedDocuments',
+        'fiscalStoragePercentageUse',
+        'fiscalStorageINN',
+        'fiscalStorageSerialNumber',
+        'fiscalStoragePaymentAddress',
+        'groupCode',
+        'timestamp',
+        'isShiftOpened',
+        'shiftNumber',
+        'shiftReceipt',
+        //'unsentDocs',
+        //'firstUnsetDocTimestamp',
+        'networkErrorCode',
+    ];
+
+    /**
+     * @var string[] Массив атрибутов, которые кастуются к DateTime
+     */
+    private array $timestamps = [
+        'fiscalizationDate',
+        'fiscalStorageExpiration',
+        'firstUnsetDocTimestamp',
+        'timestamp',
+    ];
+
+    /**
+     * Конструктор
+     *
+     * @throws EmptyMonitorDataException
+     * @throws NotEnoughMonitorDataException
+     */
+    public function __construct(protected \stdClass $data)
+    {
+        if (empty((array)$data)) {
+            throw new EmptyMonitorDataException();
+        }
+        $diff = array_diff($this->properties, array_keys((array)$data));
+        if (count($diff) !== 0) {
+            throw new NotEnoughMonitorDataException($diff);
+        }
+    }
+
+    /**
+     * Эмулирует обращение к атрибутам
+     *
+     * @param string $name
+     * @return null
+     * @throws Exception
+     */
+    public function __get(string $name)
+    {
+        if (empty($this->data?->$name)) {
+            return null;
+        }
+        if (in_array($name, $this->timestamps)) {
+            return new DateTime($this->data->$name);
+        }
+        return $this->data->$name;
+    }
+
+    /**
+     * Возвращает объект с информацией о сетевой ошибке
+     *
+     * @return object
+     */
+    public function getNetworkError(): object
+    {
+        return (object)[
+            'code' => $this->data->networkErrorCode,
+            'text' => self::ERROR_CODES[$this->data->networkErrorCode],
+        ];
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function jsonSerialize()
+    {
+        return $this->data;
+    }
+}

src/Entities/Payment.php

@@ -11,7 +11,7 @@ declare(strict_types = 1);
 
 namespace AtolOnline\Entities;
 
-use AtolOnline\Constants\PaymentTypes;
+use AtolOnline\Enums\PaymentTypes;
 
 /**
  * Класс, описывающий оплату. Тег ФФД - 1031, 1081, 1215, 1216, 1217.

src/Entities/Vat.php

@@ -11,7 +11,7 @@ declare(strict_types = 1);
 
 namespace AtolOnline\Entities;
 
-use AtolOnline\Constants\VatTypes;
+use AtolOnline\Enums\VatTypes;
 
 /**
  * Класс, описывающий ставку НДС

src/Enums/CorrectionTypes.php

@@ -9,7 +9,7 @@
 
 declare(strict_types = 1);
 
-namespace AtolOnline\Constants;
+namespace AtolOnline\Enums;
 
 use MyCLabs\Enum\Enum;
 

src/Enums/DocumentTypes.php

@@ -9,7 +9,7 @@
 
 declare(strict_types = 1);
 
-namespace AtolOnline\Constants;
+namespace AtolOnline\Enums;
 
 use MyCLabs\Enum\Enum;
 

src/Enums/PaymentMethods.php

@@ -9,7 +9,7 @@
 
 declare(strict_types = 1);
 
-namespace AtolOnline\Constants;
+namespace AtolOnline\Enums;
 
 use MyCLabs\Enum\Enum;
 

src/Enums/PaymentObjects.php

@@ -9,7 +9,7 @@
 
 declare(strict_types = 1);
 
-namespace AtolOnline\Constants;
+namespace AtolOnline\Enums;
 
 use MyCLabs\Enum\Enum;
 

src/Enums/PaymentTypes.php

@@ -9,7 +9,7 @@
 
 declare(strict_types = 1);
 
-namespace AtolOnline\Constants;
+namespace AtolOnline\Enums;
 
 use MyCLabs\Enum\Enum;
 

src/Enums/ReceiptOperationTypes.php

@@ -9,7 +9,7 @@
 
 declare(strict_types = 1);
 
-namespace AtolOnline\Constants;
+namespace AtolOnline\Enums;
 
 use MyCLabs\Enum\Enum;
 

src/Enums/SnoTypes.php

@@ -9,7 +9,7 @@
 
 declare(strict_types = 1);
 
-namespace AtolOnline\Constants;
+namespace AtolOnline\Enums;
 
 use MyCLabs\Enum\Enum;
 

src/Enums/VatTypes.php

@@ -9,7 +9,7 @@
 
 declare(strict_types = 1);
 
-namespace AtolOnline\Constants;
+namespace AtolOnline\Enums;
 
 use MyCLabs\Enum\Enum;
 

src/Exceptions/EmptyMonitorDataException.php

@@ -0,0 +1,23 @@
+<?php
+/*
+ * Copyright (c) 2020-2021 Антон Аксенов (Anthony Axenov)
+ *
+ * This code is licensed under MIT.
+ * Этот код распространяется по лицензии MIT.
+ * https://github.com/anthonyaxenov/atol-online/blob/master/LICENSE
+ */
+
+declare(strict_types = 1);
+
+namespace AtolOnline\Exceptions;
+
+/**
+ * Исключение, возникающее при попытке создать объект ККТ без данных от монитора
+ */
+class EmptyMonitorDataException extends AtolException
+{
+    /**
+     * @var string Сообщение об ошибке
+     */
+    protected $message = 'Cannot create KKT entity without data from monitor';
+}

src/Exceptions/InvalidDocumentTypeException.php

@@ -11,7 +11,7 @@ declare(strict_types = 1);
 
 namespace AtolOnline\Exceptions;
 
-use AtolOnline\Constants\DocumentTypes;
+use AtolOnline\Enums\DocumentTypes;
 use Throwable;
 
 /**

src/Exceptions/InvalidSnoException.php

@@ -11,7 +11,7 @@ declare(strict_types = 1);
 
 namespace AtolOnline\Exceptions;
 
-use AtolOnline\Constants\SnoTypes;
+use AtolOnline\Enums\SnoTypes;
 use Throwable;
 
 /**

src/Exceptions/NotEnoughMonitorDataException.php

@@ -0,0 +1,38 @@
+<?php
+/*
+ * Copyright (c) 2020-2021 Антон Аксенов (Anthony Axenov)
+ *
+ * This code is licensed under MIT.
+ * Этот код распространяется по лицензии MIT.
+ * https://github.com/anthonyaxenov/atol-online/blob/master/LICENSE
+ */
+
+declare(strict_types = 1);
+
+namespace AtolOnline\Exceptions;
+
+use Throwable;
+
+/**
+ * Исключение, возникающее при попытке создать объект ККТ с неполными данными от монитора
+ */
+class NotEnoughMonitorDataException extends AtolException
+{
+    /**
+     * @var string Сообщение об ошибке
+     */
+    protected $message = 'Cannot create KKT entity without these properties: ';
+
+    /**
+     * Конструктор
+     *
+     * @param array $props_diff
+     * @param string $message
+     * @param int $code
+     * @param Throwable|null $previous
+     */
+    public function __construct(array $props_diff, $message = "", int $code = 0, Throwable $previous = null)
+    {
+        parent::__construct($message ?: $this->message . implode(', ', $props_diff), $code, $previous);
+    }
+}