Класс документа коррекции Correction с покрытием и всякая мелочёвка

- финализация Receipt + Payment
- фиксы phpdoc

src/Collections/EntityCollection.php

@@ -20,7 +20,7 @@ use Illuminate\Support\Collection;
 abstract class EntityCollection extends Collection
 {
     /**
-     * @return array
+     * @inheritDoc
      * @throws InvalidEntityInCollectionException
      */
     public function jsonSerialize(): array

src/Entities/Company.php

@@ -11,18 +11,14 @@ declare(strict_types = 1);
 
 namespace AtolOnline\Entities;
 
-use AtolOnline\{
-    Constants\Constraints,
-    Enums\SnoTypes,
-    Traits\HasEmail,
-    Traits\HasInn};
-use AtolOnline\Exceptions\{
-    InvalidEmailException,
+use AtolOnline\{Constants\Constraints, Enums\SnoTypes, Traits\HasEmail, Traits\HasInn};
+use AtolOnline\Exceptions\{InvalidEmailException,
     InvalidEnumValueException,
     InvalidInnLengthException,
     InvalidPaymentAddressException,
     TooLongEmailException,
-    TooLongPaymentAddressException};
+    TooLongPaymentAddressException
+};
 use JetBrains\PhpStorm\ArrayShape;
 
 /**
@@ -59,8 +55,8 @@ final class Company extends Entity
      * @throws TooLongPaymentAddressException
      */
     public function __construct(
-        string $email,
-        string $sno,
+        string $email, //TODO сделать необязательным здесь
+        string $sno, //TODO сделать необязательным здесь
         string $inn,
         string $payment_address,
     ) {

src/Entities/Correction.php

@@ -0,0 +1,215 @@
+<?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\Entities;
+
+use AtolOnline\Collections\{Payments, Vats};
+use AtolOnline\Constants\Constraints;
+use AtolOnline\Exceptions\{InvalidEntityInCollectionException, TooLongCashierException};
+use Exception;
+use JetBrains\PhpStorm\ArrayShape;
+
+/**
+ * Класс, описывающий документ коррекции
+ *
+ * @see https://online.atol.ru/files/API_atol_online_v4.pdf Документация, стр 35
+ */
+class Correction extends Entity
+{
+    /**
+     * @var Company Продавец
+     */
+    protected Company $company;
+
+    /**
+     * @var string|null ФИО кассира
+     * @todo вынести в трейт
+     */
+    protected ?string $cashier = null;
+
+    /**
+     * @var CorrectionInfo Данные коррекции
+     */
+    protected CorrectionInfo $correction_info;
+
+    /**
+     * @var Payments Коллекция оплат
+     */
+    protected Payments $payments;
+
+    /**
+     * @var Vats Коллекция ставок НДС
+     */
+    protected Vats $vats;
+
+    /**
+     * Конструктор
+     *
+     * @param Company $company
+     * @param CorrectionInfo $correction_info
+     * @param Payments $payments
+     * @param Vats $vats
+     * @throws InvalidEntityInCollectionException
+     * @throws Exception
+     */
+    public function __construct(
+        Company $company,
+        CorrectionInfo $correction_info,
+        Payments $payments,
+        Vats $vats,
+    ) {
+        $this->setCompany($company)->setCorrectionInfo($correction_info)->setPayments($payments)->setVats($vats);
+    }
+
+    /**
+     * Возвращает установленного продавца
+     *
+     * @return Company
+     */
+    public function getCompany(): Company
+    {
+        return $this->company;
+    }
+
+    /**
+     * Устанаваливает продавца
+     *
+     * @param Company $company
+     * @return $this
+     */
+    public function setCompany(Company $company): self
+    {
+        $this->company = $company;
+        return $this;
+    }
+
+    /**
+     * Возвращает установленного кассира
+     *
+     * @return string|null
+     */
+    public function getCashier(): ?string
+    {
+        return $this->cashier;
+    }
+
+    /**
+     * Устанаваливает кассира
+     *
+     * @param string|null $cashier
+     * @return $this
+     * @throws TooLongCashierException
+     */
+    public function setCashier(?string $cashier): self
+    {
+        if (is_string($cashier)) {
+            $cashier = trim($cashier);
+            if (mb_strlen($cashier) > Constraints::MAX_LENGTH_CASHIER_NAME) {
+                throw new TooLongCashierException($cashier);
+            }
+        }
+        $this->cashier = $cashier ?: null;
+        return $this;
+    }
+
+    /**
+     * Возвращает установленные данные коррекции
+     *
+     * @return CorrectionInfo
+     */
+    public function getCorrectionInfo(): CorrectionInfo
+    {
+        return $this->correction_info;
+    }
+
+    /**
+     * Устанавливает данные коррекции
+     *
+     * @param CorrectionInfo $correction_info
+     * @return Correction
+     */
+    public function setCorrectionInfo(CorrectionInfo $correction_info): Correction
+    {
+        $this->correction_info = $correction_info;
+        return $this;
+    }
+
+    /**
+     * Возвращает установленную коллекцию оплат
+     *
+     * @return Payments
+     */
+    public function getPayments(): Payments
+    {
+        return $this->payments;
+    }
+
+    /**
+     * Устанаваливает коллекцию оплат
+     *
+     * @param Payments $payments
+     * @return $this
+     * @throws InvalidEntityInCollectionException
+     */
+    public function setPayments(Payments $payments): self
+    {
+        $payments->checkCount();
+        $payments->checkItemsClasses();
+        $this->payments = $payments;
+        return $this;
+    }
+
+    /**
+     * Возвращает установленную коллекцию ставок НДС
+     *
+     * @return Vats|null
+     */
+    public function getVats(): ?Vats
+    {
+        return $this->vats ?? new Vats();
+    }
+
+    /**
+     * Устанаваливает коллекцию ставок НДС
+     *
+     * @param Vats|null $vats
+     * @return $this
+     * @throws Exception
+     */
+    public function setVats(?Vats $vats): self
+    {
+        $vats->checkCount();
+        $vats->checkItemsClasses();
+        $this->vats = $vats;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     * @throws InvalidEntityInCollectionException
+     */
+    #[ArrayShape([
+        'company' => "\AtolOnline\Entities\Company",
+        'correction_info' => "\AtolOnline\Entities\CorrectionInfo",
+        'payments' => "array",
+        'vats' => "\AtolOnline\Collections\Vats|null",
+        'cashier' => "null|string"
+    ])]
+    public function jsonSerialize(): array
+    {
+        $json = [
+            'company' => $this->getCompany(),
+            'correction_info' => $this->getCorrectionInfo(),
+            'payments' => $this->getPayments()->jsonSerialize(),
+            'vats' => $this->getVats(),
+        ];
+        !is_null($this->getCashier()) && $json['cashier'] = $this->getCashier();
+        return $json;
+    }
+}

src/Entities/Payment.php

@@ -13,20 +13,15 @@ namespace AtolOnline\Entities;
 
 use AtolOnline\Constants\Constraints;
 use AtolOnline\Enums\PaymentTypes;
-use AtolOnline\Exceptions\{
-    InvalidEnumValueException,
-    NegativePaymentSumException,
-    TooHighPaymentSumException,};
-use JetBrains\PhpStorm\{
-    ArrayShape,
-    Pure};
+use AtolOnline\Exceptions\{InvalidEnumValueException, NegativePaymentSumException, TooHighPaymentSumException,};
+use JetBrains\PhpStorm\{ArrayShape, Pure};
 
 /**
  * Класс, описывающий оплату
  *
  * @see https://online.atol.ru/files/API_atol_online_v4.pdf Документация, стр 30
  */
-class Payment extends Entity
+final class Payment extends Entity
 {
     /**
      * @var int Тип оплаты

src/Entities/Receipt.php

@@ -26,7 +26,7 @@ use Exception;
  *
  * @see https://online.atol.ru/files/API_atol_online_v4.pdf Документация, стр 17
  */
-class Receipt extends Entity
+final class Receipt extends Entity
 {
     /**
      * @var Client Покупатель
@@ -35,6 +35,7 @@ class Receipt extends Entity
 
     /**
      * @var Company Продавец
+     * @todo вынести в трейт
      */
     protected Company $company;
 
@@ -55,6 +56,7 @@ class Receipt extends Entity
 
     /**
      * @var Payments Коллекция оплат
+     * @todo вынести в трейт
      */
     protected Payments $payments;
 
@@ -70,6 +72,7 @@ class Receipt extends Entity
 
     /**
      * @var string|null ФИО кассира
+     * @todo вынести в трейт
      */
     protected ?string $cashier = null;
 
@@ -112,7 +115,7 @@ class Receipt extends Entity
      * Устанаваливает покупателя
      *
      * @param Client $client
-     * @return Receipt
+     * @return $this
      */
     public function setClient(Client $client): self
     {
@@ -134,7 +137,7 @@ class Receipt extends Entity
      * Устанаваливает продавца
      *
      * @param Company $company
-     * @return Receipt
+     * @return $this
      */
     public function setCompany(Company $company): self
     {
@@ -156,7 +159,7 @@ class Receipt extends Entity
      * Устанаваливает агента
      *
      * @param AgentInfo|null $agent_info
-     * @return Receipt
+     * @return $this
      */
     public function setAgentInfo(?AgentInfo $agent_info): self
     {
@@ -178,7 +181,7 @@ class Receipt extends Entity
      * Поставщика
      *
      * @param Supplier|null $supplier
-     * @return Receipt
+     * @return $this
      */
     public function setSupplier(?Supplier $supplier): self
     {
@@ -199,12 +202,12 @@ class Receipt extends Entity
     /**
      * Устанаваливает коллекцию предметов расчёта
      *
-     * @todo исключение при пустой коллекции
      * @param Items $items
-     * @return Receipt
+     * @return $this
      * @throws EmptyItemsException
      * @throws InvalidEntityInCollectionException
      * @throws Exception
+     * @todo исключение при пустой коллекции
      */
     public function setItems(Items $items): self
     {
@@ -230,7 +233,7 @@ class Receipt extends Entity
      * Устанаваливает коллекцию оплат
      *
      * @param Payments $payments
-     * @return Receipt
+     * @return $this
      * @throws InvalidEntityInCollectionException
      */
     public function setPayments(Payments $payments): self
@@ -255,7 +258,7 @@ class Receipt extends Entity
      * Устанаваливает коллекцию ставок НДС
      *
      * @param Vats|null $vats
-     * @return Receipt
+     * @return $this
      * @throws Exception
      */
     public function setVats(?Vats $vats): self
@@ -292,7 +295,7 @@ class Receipt extends Entity
      * Устанаваливает кассира
      *
      * @param string|null $cashier
-     * @return Receipt
+     * @return $this
      * @throws TooLongCashierException
      */
     public function setCashier(?string $cashier): self
@@ -321,7 +324,7 @@ class Receipt extends Entity
      * Устанаваливает дополнительный реквизит чека
      *
      * @param string|null $add_check_props
-     * @return Receipt
+     * @return $this
      * @throws TooLongAddCheckPropException
      */
     public function setAddCheckProps(?string $add_check_props): self
@@ -350,7 +353,7 @@ class Receipt extends Entity
      * Устанаваливает дополнительный реквизит пользователя
      *
      * @param AdditionalUserProps|null $add_user_props
-     * @return Receipt
+     * @return $this
      */
     public function setAddUserProps(?AdditionalUserProps $add_user_props): self
     {

src/Enums/DocumentTypes.php

@@ -17,12 +17,12 @@ namespace AtolOnline\Enums;
 final class DocumentTypes extends Enum
 {
     /**
-     * Чек прихода, возврата прихода, расхода, возврата расхода
+     * Документ прихода, возврата прихода, расхода, возврата расхода
      */
     const RECEIPT = 'receipt';
 
     /**
-     * Чек коррекции
+     * Документ коррекции
      */
     const CORRECTION = 'correction';
 

tests/AtolOnline/Tests/Entities/CorrectionTest.php

@@ -0,0 +1,138 @@
+<?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\Tests\Entities;
+
+use AtolOnline\{Constants\Constraints, Helpers, Tests\BasicTestCase};
+use AtolOnline\Collections\{Payments, Vats,};
+use AtolOnline\Entities\{Company, Correction, CorrectionInfo};
+use AtolOnline\Enums\{CorrectionTypes, SnoTypes};
+use AtolOnline\Exceptions\{EmptyCorrectionNumberException,
+    InvalidCorrectionDateException,
+    InvalidEntityInCollectionException,
+    InvalidEnumValueException,
+    NegativePaymentSumException,
+    TooHighPaymentSumException,
+    TooLongCashierException
+};
+use Exception;
+
+/**
+ * Набор тестов для проверки работы класса чека коррекции
+ */
+class CorrectionTest extends BasicTestCase
+{
+    /**
+     * Тестирует конструктор и корректное приведение к json
+     *
+     * @return void
+     * @covers \AtolOnline\Entities\Correction
+     * @covers \AtolOnline\Entities\Correction::setCompany
+     * @covers \AtolOnline\Entities\Correction::setCorrectionInfo
+     * @covers \AtolOnline\Entities\Correction::setPayments
+     * @covers \AtolOnline\Entities\Correction::setVats
+     * @covers \AtolOnline\Entities\Correction::jsonSerialize
+     * @throws EmptyCorrectionNumberException
+     * @throws InvalidCorrectionDateException
+     * @throws InvalidEntityInCollectionException
+     * @throws InvalidEnumValueException
+     * @throws NegativePaymentSumException
+     * @throws TooHighPaymentSumException
+     * @throws Exception
+     */
+    public function testConstructor(): void
+    {
+        $correction = $this->newCorrection();
+        $this->assertIsAtolable($correction);
+    }
+
+    /**
+     * Тестирует установку валидного кассира
+     *
+     * @return void
+     * @covers \AtolOnline\Entities\Correction::setCashier
+     * @covers \AtolOnline\Entities\Correction::getCashier
+     * @covers \AtolOnline\Entities\Correction::jsonSerialize
+     * @throws EmptyCorrectionNumberException
+     * @throws InvalidCorrectionDateException
+     * @throws InvalidEntityInCollectionException
+     * @throws InvalidEnumValueException
+     * @throws NegativePaymentSumException
+     * @throws TooHighPaymentSumException
+     * @throws TooLongCashierException
+     */
+    public function testCashier(): void
+    {
+        $correction = $this->newCorrection()->setCashier(Helpers::randomStr());
+        $this->assertArrayHasKey('cashier', $correction->jsonSerialize());
+        $this->assertEquals($correction->getCashier(), $correction->jsonSerialize()['cashier']);
+    }
+
+    /**
+     * Тестирует обнуление кассира
+     *
+     * @param mixed $param
+     * @return void
+     * @dataProvider providerNullableStrings
+     * @covers       \AtolOnline\Entities\Correction::setCashier
+     * @covers       \AtolOnline\Entities\Correction::getCashier
+     * @throws EmptyCorrectionNumberException
+     * @throws InvalidCorrectionDateException
+     * @throws InvalidEntityInCollectionException
+     * @throws InvalidEnumValueException
+     * @throws NegativePaymentSumException
+     * @throws TooHighPaymentSumException
+     * @throws TooLongCashierException
+     */
+    public function testNullableCashier(mixed $param): void
+    {
+        $this->assertNull($this->newCorrection()->setCashier($param)->getCashier());
+    }
+
+    /**
+     * Тестирует выброс исключения при установке слишком длинного кассира (лол)
+     *
+     * @return void
+     * @covers \AtolOnline\Entities\Correction::setCashier
+     * @covers \AtolOnline\Exceptions\TooLongCashierException
+     * @throws EmptyCorrectionNumberException
+     * @throws InvalidCorrectionDateException
+     * @throws InvalidEntityInCollectionException
+     * @throws InvalidEnumValueException
+     * @throws NegativePaymentSumException
+     * @throws TooHighPaymentSumException
+     * @throws TooLongCashierException
+     */
+    public function testTooLongCashierException(): void
+    {
+        $this->expectException(TooLongCashierException::class);
+        $this->newCorrection()->setCashier(Helpers::randomStr(Constraints::MAX_LENGTH_CASHIER_NAME + 1));
+    }
+
+    /**
+     * Возвращает валидный тестовый объект чека
+     *
+     * @return Correction
+     * @throws InvalidEntityInCollectionException
+     * @throws InvalidEnumValueException
+     * @throws NegativePaymentSumException
+     * @throws TooHighPaymentSumException
+     * @throws EmptyCorrectionNumberException
+     * @throws InvalidCorrectionDateException
+     */
+    protected function newCorrection(): Correction
+    {
+        return new Correction(
+            new Company('company@example.com', SnoTypes::OSN, '1234567890', 'https://example.com'),
+            new CorrectionInfo(CorrectionTypes::SELF, '01.01.2021', Helpers::randomStr()),
+            new Payments($this->generatePaymentObjects(2)),
+            new Vats($this->generateVatObjects(2)),
+        );
+    }
+}