HP-2883: Implement Business Central bills import service (#114)

* HP-2883: Implement Business Central bills import service

* HP-2883: added support reversesId to Bill

* HQD-21: fixing "Implicitly marking parameters as nullable is deprecated, the explicit nullable type must be used instead" deprecation warning in Bill

* HQD-21: fixing "Implicitly marking parameters as nullable is deprecated, the explicit nullable type must be used instead" deprecation warning in batch of classes

* HQD-21: fixing "Implicitly marking parameters as nullable is deprecated, the explicit nullable type must be used instead" deprecation warning in SinglePrice

* HQD-21: fixing "Implicitly marking parameters as nullable is deprecated, the explicit nullable type must be used instead" deprecation warning in BillSource

* HQD-21: fixing "Optional parameter $plan declared before required parameter $price is implicitly treated as a required parameter" deprecation warning in SinglePrice

* HQD-129: thightly refectored BillReversesId

Author: VadymHrechukha

src/bill/Bill.php

@@ -64,6 +64,15 @@ class Bill implements BillInterface
     /** @var UsageInterval */
     protected $usageInterval;
 
+    /** @var BillSource|null */
+    protected $source;
+
+    /** @var BillTxn|null */
+    protected $txn;
+
+    /** @var BillReversesId|null */
+    protected $reversesId;
+
     /**
      * @param int|string $id
      */
@@ -77,7 +86,10 @@ public function __construct(
         ?TargetInterface $target = null,
         ?PlanInterface $plan = null,
         array $charges = [],
-        ?BillState $state = null
+        ?BillState $state = null,
+        ?BillSource $source = null,
+        ?BillTxn $txn = null,
+        ?BillReversesId $reversesId = null,
     ) {
         $this->type         = $type;
         $this->time         = $time;
@@ -88,6 +100,9 @@ public function __construct(
         $this->plan         = $plan;
         $this->charges      = $charges;
         $this->state        = $state;
+        $this->source       = $source;
+        $this->txn          = $txn;
+        $this->reversesId   = $reversesId;
     }
 
     /**
@@ -241,6 +256,16 @@ public function getComment()
         return $this->comment;
     }
 
+    public function getSource(): ?BillSource
+    {
+        return $this->source;
+    }
+
+    public function getTxn(): ?BillTxn
+    {
+        return $this->txn;
+    }
+
     public function setComment(string $comment)
     {
         $this->comment = $comment;
@@ -255,4 +280,18 @@ public function setUsageInterval(UsageInterval $usageInterval): void
     {
         $this->usageInterval = $usageInterval;
     }
+
+    public function getReversesId(): ?BillReversesId
+    {
+        return $this->reversesId;
+    }
+
+    /**
+     * @param BillReversesId|null $reversesId
+     * @return void
+     */
+    public function setReversesId($reversesId): void
+    {
+        $this->reversesId = $reversesId;
+    }
 }

src/bill/BillInterface.php

@@ -57,4 +57,10 @@ public function getCharges();
     public function getUsageInterval(): UsageInterval;
 
     public function setUsageInterval(UsageInterval $usageInterval): void;
+
+    public function getSource(): ?BillSource;
+
+    public function getTxn(): ?BillTxn;
+
+    public function getReversesId(): ?BillReversesId;
 }

src/bill/BillReversesId.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace hiqdev\php\billing\bill;
+
+readonly class BillReversesId
+{
+    public function __construct(private ?int $value = null)
+    {
+    }
+
+    public function getId(): ?int
+    {
+        return $this->value;
+    }
+
+    public static function fromInt(int $id): self
+    {
+        return new self($id);
+    }
+}

src/bill/BillSource.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace hiqdev\php\billing\bill;
+
+class BillSource
+{
+    /** @var int|string|null */
+    protected $id;
+
+    protected ?string $name = null;
+
+    public function __construct($id = null, ?string $name = null)
+    {
+        $this->id = $id;
+        $this->name = $name;
+    }
+
+    public function getId()
+    {
+        return $this->id;
+    }
+
+    public function getName(): ?string
+    {
+        return $this->name;
+    }
+}

src/bill/BillTxn.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace hiqdev\php\billing\bill;
+
+/**
+ * BillTxn
+ *
+ * Represents an immutable external payment transaction identifier.
+ *
+ * A TransactionId uniquely identifies a financial transaction
+ * as defined by an external payment or accounting system
+ * (e.g. Business Central, merchant gateways, banks).
+ *
+ * This value:
+ * - Is created by an external system, never generated internally
+ * - Is stable across retries, webhooks, and re-imports
+ * - Is used for idempotency and reconciliation
+ * - Has meaning outside of the database and application boundaries
+ *
+ * Uniqueness is guaranteed only within the scope of a source system
+ * (see Source / external system).
+ *
+ * Typical examples:
+ * - UUIDs
+ * - Gateway transaction references
+ * - Accounting document numbers
+ */
+class BillTxn
+{
+    /** @var int|string|null */
+    protected $value;
+
+    public function __construct($txn = null)
+    {
+        $this->value = $txn;
+    }
+
+    public function getValue()
+    {
+        return $this->value;
+    }
+
+    public static function fromString(string $txn): self
+    {
+        return new self($txn);
+    }
+}

src/charge/modifiers/Installment.php

@@ -41,7 +41,7 @@ public function buildPrice(Money $sum)
         $target = $this->getTarget();
         $prepaid = Quantity::create('items', 0);
 
-        return new SinglePrice(null, $type, $target, null, $prepaid, $sum);
+        return new SinglePrice(null, $type, $target, $prepaid, $sum);
     }
 
     public function getType()

src/price/PriceFactory.php

@@ -91,7 +91,7 @@ public function createRatePrice(PriceCreationDto $dto)
 
     public function createSinglePrice(PriceCreationDto $dto)
     {
-        return new SinglePrice($dto->id, $dto->type, $dto->target, $dto->plan, $dto->prepaid, $dto->price);
+        return new SinglePrice($dto->id, $dto->type, $dto->target, $dto->prepaid, $dto->price, $dto->plan);
     }
 
     public function createProgressivePrice(PriceCreationDto $dto): ProgressivePrice

src/price/SinglePrice.php

@@ -36,9 +36,9 @@ public function __construct(
         $id,
         TypeInterface $type,
         TargetInterface $target,
-        ?PlanInterface $plan = null,
         ?QuantityInterface $prepaid = null,
-        ?Money $price = null
+        ?Money $price = null,
+        ?PlanInterface $plan = null,
     ) {
         parent::__construct($id, $type, $target, $plan);
         $this->prepaid  = $prepaid;

tests/behat/bootstrap/FeatureContext.php

@@ -97,7 +97,7 @@ public function priceIs($target, $type, $sum, $currency, $unit, $quantity = 0)
         $target = new Target(Target::ANY, $target);
         $quantity = Quantity::create($unit, $quantity);
         $sum = $this->moneyParser->parse($sum, new Currency($currency));
-        $this->setPrice(new SinglePrice(null, $type, $target, null, $quantity, $sum));
+        $this->setPrice(new SinglePrice(null, $type, $target, $quantity, $sum));
     }
 
     protected array $progressivePrice = [];

tests/unit/action/ActionTest.php

@@ -87,7 +87,7 @@ protected function setUp(): void
         $this->target   = new Target(2, 'server');
         $this->prepaid  = Quantity::gigabyte(1);
         $this->money    = Money::USD(10000);
-        $this->price    = new SinglePrice(5, $this->type, $this->target, null, $this->prepaid, $this->money);
+        $this->price    = new SinglePrice(5, $this->type, $this->target, $this->prepaid, $this->money);
         $this->customer = new Customer(2, 'client');
         $this->time     = new DateTimeImmutable('now');
         $this->generalizer = new Generalizer();