HP-2508 Working on typing for Psalm

src/product/BillingRegistryInterface.php

@@ -13,6 +13,9 @@ interface BillingRegistryInterface extends HasLockInterface
      */
     public function priceTypes(): Generator;
 
+    /**
+     * @return TariffTypeDefinitionInterface[]
+     */
     public function getTariffTypeDefinitions(): array;
 
     public function addTariffType(TariffTypeDefinitionInterface $tariffTypeDefinition): void;

src/product/TariffTypeDefinition.php

@@ -2,16 +2,22 @@
 
 namespace hiqdev\php\billing\product;
 
+use Google\Service\TPU;
+use hiqdev\php\billing\product\behavior\BehaviorCollectionInterface;
 use hiqdev\php\billing\product\behavior\BehaviorTariffTypeCollection;
 use hiqdev\php\billing\product\behavior\TariffTypeBehaviorRegistry;
 use hiqdev\php\billing\product\Domain\Model\TariffTypeInterface;
 use hiqdev\php\billing\product\Exception\ProductNotDefinedException;
+use hiqdev\php\billing\product\price\PriceTypeDefinition;
 use hiqdev\php\billing\product\price\PriceTypeDefinitionCollection;
+use hiqdev\php\billing\product\price\PriceTypeDefinitionCollectionInterface;
 use hiqdev\php\billing\product\price\PriceTypeDefinitionFactory;
 use hiqdev\php\billing\product\trait\HasLock;
 
 /**
- * @implements TariffTypeDefinitionInterface<PriceTypeDefinitionCollection>
+ * @template TPriceTypeDefinitionCollection of PriceTypeDefinitionCollection
+ * @implements TariffTypeDefinitionInterface<TPriceTypeDefinitionCollection>
+ * @psalm-suppress InvalidTemplateParam
  */
 class TariffTypeDefinition implements TariffTypeDefinitionInterface
 {
@@ -39,7 +45,7 @@ public function belongToTariffType(TariffTypeInterface $tariffType): bool
         return $this->tariffType->equals($tariffType);
     }
 
-    public function ofProduct(ProductInterface $product): TariffTypeDefinitionInterface
+    public function ofProduct(ProductInterface $product): static
     {
         $this->ensureNotLocked();
         $this->product = $product;
@@ -51,6 +57,7 @@ public function getProduct(): ProductInterface
     {
         $this->ensureProductExists();
 
+        /** @psalm-suppress NullableReturnStatement */
         return $this->product;
     }
 
@@ -61,22 +68,32 @@ private function ensureProductExists(): void
         }
     }
 
-    public function setPricesSuggester(string $suggesterClass): TariffTypeDefinitionInterface
+    public function setPricesSuggester(string $suggesterClass): static
     {
         $this->ensureNotLocked();
 
         // Validate or store the suggester class
         return $this;
     }
 
-    public function withPrices(): PriceTypeDefinitionCollection
+    /**
+     * @psalm-suppress InvalidReturnType
+     * @psalm-suppress InvalidReturnStatement
+     */
+    public function withPrices()
     {
         $this->ensureNotLocked();
 
         return $this->prices;
     }
 
-    public function withBehaviors(): BehaviorTariffTypeCollection
+    /**
+     * @return BehaviorCollectionInterface<TariffTypeDefinition>
+     * @psalm-suppress ImplementedReturnTypeMismatch
+     * @psalm-suppress InvalidReturnType
+     * @psalm-suppress InvalidReturnStatement
+     */
+    public function withBehaviors()
     {
         $this->ensureNotLocked();
 

src/product/TariffTypeDefinitionInterface.php

@@ -8,7 +8,10 @@
 use hiqdev\php\billing\product\trait\HasLockInterface;
 
 /**
- * @template T of PriceTypeDefinitionCollectionInterface
+ * @template-covariant TPriceTypeDefinitionCollection of PriceTypeDefinitionCollectionInterface
+ * @extends HasBehaviorsInterface<static>
+ * @psalm-consistent-templates
+ * @psalm-suppress InvalidTemplateParam
  */
 interface TariffTypeDefinitionInterface extends HasBehaviorsInterface, HasLockInterface
 {
@@ -22,17 +25,16 @@ public function tariffType(): TariffTypeInterface;
      */
     public function belongToTariffType(TariffTypeInterface $tariffType): bool;
 
-    public function ofProduct(ProductInterface $product): self;
+    public function ofProduct(ProductInterface $product): static;
 
     public function getProduct(): ProductInterface;
 
-    public function setPricesSuggester(string $suggesterClass): self;
+    public function setPricesSuggester(string $suggesterClass): static;
 
     /**
-     * @return PriceTypeDefinitionCollectionInterface
-     * @psalm-return T
+     * @return TPriceTypeDefinitionCollection
      */
-    public function withPrices(): PriceTypeDefinitionCollectionInterface;
+    public function withPrices();
 
-    public function end(): self;
+    public function end();
 }

src/product/behavior/BehaviorCollection.php

@@ -3,8 +3,15 @@
 namespace hiqdev\php\billing\product\behavior;
 
 use hiqdev\php\billing\product\Domain\Model\TariffTypeInterface;
+use hiqdev\php\billing\product\price\PriceTypeDefinitionInterface;
+use hiqdev\php\billing\product\TariffTypeDefinitionInterface;
 use hiqdev\php\billing\product\trait\HasLock;
 
+/**
+ * @template-covariant TParentContext of TariffTypeDefinitionInterface|PriceTypeDefinitionInterface
+ * @implements BehaviorCollectionInterface<TParentContext>
+ * @psalm-consistent-templates
+ */
 abstract class BehaviorCollection implements BehaviorCollectionInterface
 {
     use HasLock;
@@ -21,7 +28,7 @@ public function getIterator(): \Traversable
         return new \ArrayIterator($this->behaviors);
     }
 
-    public function attach(BehaviorInterface $behavior): self
+    public function attach(BehaviorInterface $behavior): static
     {
         $this->ensureNotLocked();
 

src/product/behavior/BehaviorCollectionInterface.php

@@ -9,7 +9,9 @@
 use Traversable;
 
 /**
+ * @template-covariant TParentContext of TariffTypeDefinitionInterface|PriceTypeDefinitionInterface
  * @extends IteratorAggregate<int, BehaviorInterface>
+ * @psalm-consistent-templates
  */
 interface BehaviorCollectionInterface extends IteratorAggregate, HasLockInterface
 {
@@ -18,10 +20,10 @@ interface BehaviorCollectionInterface extends IteratorAggregate, HasLockInterfac
      */
     public function getIterator(): Traversable;
 
-    public function attach(BehaviorInterface $behavior): self;
+    public function attach(BehaviorInterface $behavior): static;
 
     /**
-     * @return TariffTypeDefinitionInterface|PriceTypeDefinitionInterface
+     * @return TParentContext
      */
-    public function end(): TariffTypeDefinitionInterface|PriceTypeDefinitionInterface;
+    public function end();
 }

src/product/behavior/BehaviorPriceTypeDefinitionCollection.php

@@ -5,14 +5,35 @@
 use hiqdev\php\billing\product\Domain\Model\TariffTypeInterface;
 use hiqdev\php\billing\product\price\PriceTypeDefinitionInterface;
 
+/**
+ * @template TPriceDefinition
+ * @extends BehaviorCollection<TPriceDefinition>
+ * @psalm-consistent-templates
+ * @psalm-suppress InvalidTemplateParam
+ */
 class BehaviorPriceTypeDefinitionCollection extends BehaviorCollection
 {
-    public function __construct(private readonly PriceTypeDefinitionInterface $parent, TariffTypeInterface $tariffType)
-    {
+    /**
+     * @psalm-var TPriceDefinition
+     */
+    private readonly PriceTypeDefinitionInterface $parent;
+
+    /**
+     * @psalm-param TPriceDefinition $parent
+     */
+    public function __construct(
+        PriceTypeDefinitionInterface $parent,
+        TariffTypeInterface $tariffType
+    ) {
+        $this->parent = $parent;
+
         parent::__construct($tariffType);
     }
 
-    public function end(): PriceTypeDefinitionInterface
+    /**
+     * @return TPriceDefinition
+     */
+    public function end()
     {
         return $this->parent;
     }

src/product/behavior/BehaviorTariffTypeCollection.php

@@ -5,13 +5,30 @@
 use hiqdev\php\billing\product\Domain\Model\TariffTypeInterface;
 use hiqdev\php\billing\product\TariffTypeDefinitionInterface;
 
+/**
+ * @template T
+ * @psalm-suppress MissingTemplateParam
+ * @psalm-suppress InvalidTemplateParam
+ */
 class BehaviorTariffTypeCollection extends BehaviorCollection
 {
-    public function __construct(private readonly TariffTypeDefinitionInterface $parent, TariffTypeInterface $tariffType)
-    {
+    /**
+     * @psalm-param T $parent
+     */
+    public function __construct(
+        /**
+         * @var T
+         */
+        private readonly TariffTypeDefinitionInterface $parent,
+        TariffTypeInterface $tariffType
+    ) {
         parent::__construct($tariffType);
     }
 
+    /**
+     * @psalm-return T
+     * @psalm-suppress LessSpecificImplementedReturnType
+     */
     public function end(): TariffTypeDefinitionInterface
     {
         return $this->parent;

src/product/behavior/HasBehaviorsInterface.php

@@ -2,9 +2,20 @@
 
 namespace hiqdev\php\billing\product\behavior;
 
+use hiqdev\php\billing\product\invoice\RepresentationCollection;
+use hiqdev\php\billing\product\price\PriceTypeDefinitionInterface;
+use hiqdev\php\billing\product\TariffTypeDefinitionInterface;
+
+/**
+ * @template TParentCollection of PriceTypeDefinitionInterface|TariffTypeDefinitionInterface
+ * @psalm-consistent-templates
+ */
 interface HasBehaviorsInterface
 {
-    public function withBehaviors(): BehaviorCollectionInterface;
+    /**
+     * @return BehaviorCollectionInterface<TParentCollection>
+     */
+    public function withBehaviors();
 
     public function hasBehavior(string $behaviorClassName): bool;
 }

src/product/behavior/TariffTypeBehaviorRegistry.php

@@ -23,16 +23,27 @@
  *  - To avoid code duplication of behavior-related methods in multiple classes.
  *  - To separate concerns by handling behavior-related logic in a dedicated class.
  *  - To improve maintainability and testability of tariff behavior handling.
+ *
+ * @template-covariant T of TariffTypeDefinitionInterface
  */
 final class TariffTypeBehaviorRegistry implements HasLockInterface
 {
+    /**
+     * @var BehaviorTariffTypeCollection<T>
+     */
     private BehaviorTariffTypeCollection $behaviorCollection;
 
+    /**
+     * @psalm-param T $tariffTypeDefinition
+     */
     public function __construct(TariffTypeDefinitionInterface $tariffTypeDefinition, TariffTypeInterface $tariffType)
     {
         $this->behaviorCollection = new BehaviorTariffTypeCollection($tariffTypeDefinition, $tariffType);
     }
 
+    /**
+     * @return BehaviorTariffTypeCollection<T>
+     */
     public function getBehaviors(): BehaviorTariffTypeCollection
     {
         return $this->behaviorCollection;

src/product/invoice/RepresentationCollection.php

@@ -9,8 +9,9 @@
 use Traversable;
 
 /**
- * @template T of PriceTypeDefinition
+ * @template T
  * @implements IteratorAggregate<int, RepresentationInterface>
+ * @psalm-consistent-templates
  */
 class RepresentationCollection implements IteratorAggregate, HasLockInterface
 {
@@ -20,8 +21,18 @@ class RepresentationCollection implements IteratorAggregate, HasLockInterface
 
     private RepresentationUniquenessGuard $uniquenessGuard;
 
-    public function __construct(private readonly PriceTypeDefinition $priceTypeDefinition)
-    {
+    /**
+     * @psalm-var T
+     */
+    private readonly PriceTypeDefinition $priceTypeDefinition;
+
+    /**
+     * @psalm-param T $priceTypeDefinition
+     */
+    public function __construct(
+        PriceTypeDefinition $priceTypeDefinition,
+    ) {
+        $this->priceTypeDefinition = $priceTypeDefinition;
         $this->uniquenessGuard = new RepresentationUniquenessGuard();
     }
 
@@ -33,7 +44,7 @@ public function getIterator(): Traversable
         return new \ArrayIterator($this->representations);
     }
 
-    public function attach(RepresentationInterface $representation): self
+    public function attach(RepresentationInterface $representation): static
     {
         $this->ensureNotLocked();
 
@@ -49,7 +60,7 @@ public function attach(RepresentationInterface $representation): self
     /**
      * @psalm-return T
      */
-    public function end(): PriceTypeDefinition
+    public function end()
     {
         return $this->priceTypeDefinition;
     }