Доработка коллекций и не только

- коллекция `Items` с покрытием
- вынос коллекций из `AtolOnline\Entities` в `AtolOnline\Collections`
- фикс ] в `AtolException`
- финализирован `CorrectionInfo`
- фиксы по тестам коллекций
- прочие мелочи по phpdoc

src/Collections/EntityCollection.php

@@ -9,16 +9,14 @@
 
 declare(strict_types = 1);
 
-namespace AtolOnline\Entities;
+namespace AtolOnline\Collections;
 
-use Illuminate\Contracts\Support\Arrayable;
-use Illuminate\Contracts\Support\Jsonable;
+use AtolOnline\Exceptions\InvalidEntityInCollectionException;
+use Exception;
 use Illuminate\Support\Collection;
 
 /**
  * Абстрактное описание коллекции любых сущностей
- *
- * @todo вот бы ещё проверять классы добавляемых объектов через static.... ммм мякотка
  */
 abstract class EntityCollection extends Collection
 {
@@ -69,21 +67,14 @@ abstract class EntityCollection extends Collection
 
     /**
      * @inheritDoc
-     * @throws \Exception
+     * @throws Exception
      */
     public function jsonSerialize(): array
     {
-        return array_map(function ($value) {
-            $this->checkEntityClass($value);
-            if ($value instanceof \JsonSerializable) {
-                return $value->jsonSerialize();
-            } elseif ($value instanceof Jsonable) {
-                return json_decode($value->toJson(), true);
-            } elseif ($value instanceof Arrayable) {
-                return $value->toArray();
-            }
-            return $value;
-        }, $this->all());
+        $this->each(function ($item) {
+            $this->checkClass($item);
+        });
+        return parent::jsonSerialize();
     }
 
     /**
@@ -94,26 +85,20 @@ abstract class EntityCollection extends Collection
      */
     private function checkCount(array $items = []): void
     {
-        if (
-            count($items) > static::MAX_COUNT ||
-            $this->count() === static::MAX_COUNT
-        ) {
-            $exception = static::EXCEPTION_CLASS;
-            throw new $exception(static::MAX_COUNT);
+        if (count($items) > static::MAX_COUNT || $this->count() === static::MAX_COUNT) {
+            throw new (static::EXCEPTION_CLASS)(static::MAX_COUNT);
         }
     }
 
     /**
-     * @throws \Exception
+     * Проверяет корректность класса объекта
+     *
+     * @throws InvalidEntityInCollectionException
      */
-    private function checkEntityClass(mixed $item): void
+    private function checkClass(mixed $item): void
     {
         if (!is_object($item) || $item::class !== static::ENTITY_CLASS) {
-            //TODO proper exception
-            throw new \Exception(
-                'Коллекция должна содержать только объекты класса ' .
-                static::ENTITY_CLASS . ', найден ' . $item::class
-            );
+            throw new InvalidEntityInCollectionException(static::class, static::ENTITY_CLASS, $item);
         }
     }
 }

src/Collections/Items.php

@@ -0,0 +1,35 @@
+<?php
+/*
+ * Copyright (c) 2020-2021 Антон Аксенов (Anthony Axenov)
+ *
+ * This code is licensed under MIT.
+ * Этот код распространяется по лицензии MIT.
+ * https://github.com/anthonyaxenov/atol-online/blob/master/LICENSE
+ */
+
+namespace AtolOnline\Collections;
+
+use AtolOnline\Constants\Constraints;
+use AtolOnline\Entities\Item;
+use AtolOnline\Exceptions\TooManyItemsException;
+
+/**
+ * Класс, описывающий коллекцию предметов расчёта для документа
+ */
+final class Items extends EntityCollection
+{
+    /**
+     * Класс объектов, находящихся в коллекции
+     */
+    protected const ENTITY_CLASS = Item::class;
+
+    /**
+     * Максмальное количество объектов в коллекции
+     */
+    protected const MAX_COUNT = Constraints::MAX_COUNT_DOC_ITEMS;
+
+    /**
+     * Класс-наследник TooManyException для выброса при превышении количества
+     */
+    protected const EXCEPTION_CLASS = TooManyItemsException::class;
+}

src/Collections/Payments.php

@@ -7,9 +7,10 @@
  * https://github.com/anthonyaxenov/atol-online/blob/master/LICENSE
  */
 
-namespace AtolOnline\Entities;
+namespace AtolOnline\Collections;
 
 use AtolOnline\Constants\Constraints;
+use AtolOnline\Entities\Payment;
 use AtolOnline\Exceptions\TooManyPaymentsException;
 
 /**

src/Collections/Vats.php

@@ -7,9 +7,10 @@
  * https://github.com/anthonyaxenov/atol-online/blob/master/LICENSE
  */
 
-namespace AtolOnline\Entities;
+namespace AtolOnline\Collections;
 
 use AtolOnline\Constants\Constraints;
+use AtolOnline\Entities\Vat;
 use AtolOnline\Exceptions\TooManyVatsException;
 
 /**
@@ -18,7 +19,12 @@ use AtolOnline\Exceptions\TooManyVatsException;
 final class Vats extends EntityCollection
 {
     /**
-     * Максмальное количество ставок НДС
+     * Класс объектов, находящихся в коллекции
+     */
+    protected const ENTITY_CLASS = Vat::class;
+
+    /**
+     * Максмальное количество объектов в коллекции
      */
     protected const MAX_COUNT = Constraints::MAX_COUNT_DOC_VATS;
 

src/Entities/Company.php

@@ -15,16 +15,14 @@ use AtolOnline\{
     Constants\Constraints,
     Enums\SnoTypes,
     Traits\HasEmail,
-    Traits\HasInn
-};
+    Traits\HasInn};
 use AtolOnline\Exceptions\{
     InvalidEmailException,
     InvalidEnumValueException,
     InvalidInnLengthException,
     InvalidPaymentAddressException,
     TooLongEmailException,
-    TooLongPaymentAddressException
-};
+    TooLongPaymentAddressException};
 use JetBrains\PhpStorm\ArrayShape;
 
 /**
@@ -131,10 +129,10 @@ final class Company extends Entity
      * @throws InvalidPaymentAddressException
      */
     #[ArrayShape([
-        'email' => "string",
-        'sno' => "string",
-        'inn' => "string",
-        'payment_address' => "string",
+        'email' => 'string',
+        'sno' => 'string',
+        'inn' => 'string',
+        'payment_address' => 'string',
     ])]
     public function jsonSerialize(): array
     {

src/Entities/CorrectionInfo.php

@@ -16,21 +16,19 @@ use AtolOnline\Enums\CorrectionTypes;
 use AtolOnline\Exceptions\{
     EmptyCorrectionNumberException,
     InvalidCorrectionDateException,
-    InvalidEnumValueException
-};
+    InvalidEnumValueException};
 use DateTime;
 use Exception;
 use JetBrains\PhpStorm\{
     ArrayShape,
-    Pure
-};
+    Pure};
 
 /**
  * Класс, описывающий данные коррекции
  *
  * @see https://online.atol.ru/files/API_atol_online_v4.pdf Документация, стр 35
  */
-class CorrectionInfo extends Entity
+final class CorrectionInfo extends Entity
 {
     /**
      * @var string|null Тип коррекции (1173)

src/Entities/Payment.php

@@ -13,11 +13,13 @@ namespace AtolOnline\Entities;
 
 use AtolOnline\Constants\Constraints;
 use AtolOnline\Enums\PaymentTypes;
-use AtolOnline\Exceptions\InvalidEnumValueException;
-use AtolOnline\Exceptions\NegativePaymentSumException;
-use AtolOnline\Exceptions\TooHighPaymentSumException;
-use JetBrains\PhpStorm\ArrayShape;
-use JetBrains\PhpStorm\Pure;
+use AtolOnline\Exceptions\{
+    InvalidEnumValueException,
+    NegativePaymentSumException,
+    TooHighPaymentSumException,};
+use JetBrains\PhpStorm\{
+    ArrayShape,
+    Pure};
 
 /**
  * Класс, описывающий оплату
@@ -41,9 +43,9 @@ class Payment extends Entity
      *
      * @param int $type Тип оплаты
      * @param float $sum Сумма оплаты
-     * @throws InvalidEnumValueException
      * @throws NegativePaymentSumException
      * @throws TooHighPaymentSumException
+     * @throws InvalidEnumValueException
      */
     public function __construct(int $type, float $sum)
     {

src/Exceptions/AtolException.php

@@ -33,7 +33,7 @@ class AtolException extends Exception
     {
         $tags = implode(', ', $ffd_tags ?: $this->ffd_tags);
         parent::__construct(
-            ($message ?: $this->message) . ($tags ? ' [Теги ФФД: ' . $tags : '') . ']'
+            ($message ?: $this->message) . ($tags ? ' [Теги ФФД: ' . $tags . ']' : '')
         );
     }
 }

src/Exceptions/InvalidEntityInCollectionException.php

@@ -0,0 +1,37 @@
+<?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 InvalidEntityInCollectionException extends AtolException
+{
+    /**
+     * Конструктор
+     *
+     * @param string $collection_class
+     * @param string $expected_class
+     * @param mixed $actual
+     */
+    public function __construct(string $collection_class, string $expected_class, mixed $actual)
+    {
+        if (is_object($actual)) {
+            $actual = $actual::class;
+        } elseif (is_scalar($actual)) {
+            $actual = '(' . gettype($actual) . ')' . var_export($actual, true);
+        }
+        parent::__construct(
+            "Коллекция $collection_class должна содержать объекты $expected_class, найден $actual"
+        );
+    }
+}