add PHPStan template annotations and suppress covariant generics

- Add proper template annotations to test base classes and suppress.
- PHPStan errors for lack of covariant generics support.
- Maintains DRY test structure while ensuring static analysis passes cleanly.

Author: martin-georgiev

ci/phpstan/baselines/range-baseline.neon

@@ -23,3 +23,25 @@ parameters:
 			identifier: new.static
 			count: 4
 			path: ../../../src/MartinGeorgiev/Doctrine/DBAL/Types/ValueObject/Range.php
+
+		# Temporary suppression for PHPStan's lack of covariant generics support
+		# Remove when PHPStan supports covariance (https://github.com/phpstan/phpstan/issues/7427)
+		-
+			message: '#.*Template type R on class.*Range is not covariant#'
+			path: ../../../tests/Unit/MartinGeorgiev/Doctrine/DBAL/Types/ValueObject/
+
+		-
+			message: '#.*should return.*Range<DateTimeInterface\|float\|int>.*but returns.*Range#'
+			path: ../../../tests/Unit/MartinGeorgiev/Doctrine/DBAL/Types/ValueObject/
+
+		-
+			message: '#.*Generator expects value type.*Range<DateTimeInterface\|float\|int>.*given#'
+			path: ../../../tests/Unit/MartinGeorgiev/Doctrine/DBAL/Types/ValueObject/
+
+		-
+			message: '#.*extends generic class.*but does not specify its types#'
+			path: ../../../tests/Unit/MartinGeorgiev/Doctrine/DBAL/Types/ValueObject/
+
+		-
+			message: '#.*should be compatible with return type#'
+			path: ../../../tests/Unit/MartinGeorgiev/Doctrine/DBAL/Types/ValueObject/

tests/Unit/MartinGeorgiev/Doctrine/DBAL/Types/ValueObject/BaseRangeTestCase.php

@@ -9,6 +9,13 @@
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\TestCase;
 
+/**
+ * @template R of int|float|\DateTimeInterface
+ *
+ * TODO: Remove PHPStan suppressions when covariant generics are supported
+ *
+ * @see https://github.com/phpstan/phpstan/issues/7427
+ */
 abstract class BaseRangeTestCase extends TestCase
 {
     #[Test]
@@ -49,13 +56,19 @@ public function can_create_inclusive_range(): void
         self::assertFalse($range->isEmpty());
     }
 
+    /**
+     * @param Range<R> $range
+     */
     #[Test]
     #[DataProvider('provideContainsTestCases')]
     public function can_check_contains(Range $range, mixed $value, bool $expected): void
     {
         self::assertEquals($expected, $range->contains($value));
     }
 
+    /**
+     * @param Range<R> $expectedRange
+     */
     #[Test]
     #[DataProvider('provideFromStringTestCases')]
     public function can_parse_from_string(string $input, Range $expectedRange): void
@@ -89,6 +102,8 @@ public function can_handle_comparison_via_is_empty(): void
 
     /**
      * Create a simple range for basic testing.
+     *
+     * @return Range<R>
      */
     abstract protected function createSimpleRange(): Range;
 
@@ -99,16 +114,22 @@ abstract protected function getExpectedSimpleRangeString(): string;
 
     /**
      * Create an empty range.
+     *
+     * @return Range<R>
      */
     abstract protected function createEmptyRange(): Range;
 
     /**
      * Create an infinite range.
+     *
+     * @return Range<R>
      */
     abstract protected function createInfiniteRange(): Range;
 
     /**
      * Create an inclusive range for testing.
+     *
+     * @return Range<R>
      */
     abstract protected function createInclusiveRange(): Range;
 
@@ -119,11 +140,15 @@ abstract protected function getExpectedInclusiveRangeString(): string;
 
     /**
      * Parse range from string.
+     *
+     * @return Range<R>
      */
     abstract protected function parseFromString(string $input): Range;
 
     /**
      * Create range for boundary testing.
+     *
+     * @return Range<R>
      */
     abstract protected function createBoundaryTestRange(): Range;
 
@@ -137,22 +162,25 @@ abstract protected function getBoundaryTestCases(): array;
     /**
      * Get comparison test cases.
      *
-     * @return array<string, array{range: Range, expectedEmpty: bool}>
+     * @return array<string, array{range: Range<R>, expectedEmpty: bool}>
      */
     abstract protected function getComparisonTestCases(): array;
 
     /**
-     * @return \Generator<string, array{Range, mixed, bool}>
+     * @return \Generator<string, array{Range<R>, mixed, bool}>
      */
     abstract public static function provideContainsTestCases(): \Generator;
 
     /**
-     * @return \Generator<string, array{string, Range}>
+     * @return \Generator<string, array{string, Range<R>}>
      */
     abstract public static function provideFromStringTestCases(): \Generator;
 
     /**
      * Assert that a range equals another range by comparing string representation and isEmpty state.
+     *
+     * @param Range<R> $expected
+     * @param Range<R> $actual
      */
     protected function assertRangeEquals(Range $expected, Range $actual, string $message = ''): void
     {
@@ -163,6 +191,7 @@ protected function assertRangeEquals(Range $expected, Range $actual, string $mes
     /**
      * Assert that a range contains all the given values.
      *
+     * @param Range<R>     $range
      * @param array<mixed> $values
      */
     protected function assertRangeContainsAll(Range $range, array $values, string $message = ''): void
@@ -178,6 +207,7 @@ protected function assertRangeContainsAll(Range $range, array $values, string $m
     /**
      * Assert that a range does not contain any of the given values.
      *
+     * @param Range<R>     $range
      * @param array<mixed> $values
      */
     protected function assertRangeContainsNone(Range $range, array $values, string $message = ''): void
@@ -192,6 +222,8 @@ protected function assertRangeContainsNone(Range $range, array $values, string $
 
     /**
      * Assert that a range has the expected string representation.
+     *
+     * @param Range<R> $range
      */
     protected function assertRangeStringEquals(string $expected, Range $range, string $message = ''): void
     {
@@ -200,6 +232,8 @@ protected function assertRangeStringEquals(string $expected, Range $range, strin
 
     /**
      * Assert that a range is empty.
+     *
+     * @param Range<R> $range
      */
     protected function assertRangeIsEmpty(Range $range, string $message = ''): void
     {
@@ -209,6 +243,8 @@ protected function assertRangeIsEmpty(Range $range, string $message = ''): void
 
     /**
      * Assert that a range is not empty.
+     *
+     * @param Range<R> $range
      */
     protected function assertRangeIsNotEmpty(Range $range, string $message = ''): void
     {
@@ -219,6 +255,7 @@ protected function assertRangeIsNotEmpty(Range $range, string $message = ''): vo
     /**
      * Test boundary conditions for a range with known bounds.
      *
+     * @param Range<R>                                           $range
      * @param array<string, array{value: mixed, expected: bool}> $testCases
      */
     protected function assertBoundaryConditions(Range $range, array $testCases, string $message = ''): void
@@ -257,7 +294,7 @@ protected function generateBoundaryTestCases(
     /**
      * Test that a range correctly handles equal bounds with different bracket combinations.
      *
-     * @param callable $rangeFactory Function that creates a range: fn($lower, $upper, $lowerInc, $upperInc) => Range
+     * @param callable(mixed, mixed, bool, bool): Range<R> $rangeFactory Function that creates a range
      */
     protected function assertEqualBoundsHandling(callable $rangeFactory, mixed $value): void
     {
@@ -278,7 +315,7 @@ protected function assertEqualBoundsHandling(callable $rangeFactory, mixed $valu
     /**
      * Test that a range correctly handles reverse bounds (lower > upper).
      *
-     * @param callable $rangeFactory Function that creates a range: fn($lower, $upper, $lowerInc, $upperInc) => Range
+     * @param callable(mixed, mixed, bool, bool): Range<R> $rangeFactory Function that creates a range
      */
     protected function assertReverseBoundsHandling(callable $rangeFactory, mixed $lower, mixed $upper): void
     {

tests/Unit/MartinGeorgiev/Doctrine/DBAL/Types/ValueObject/BaseTimestampRangeTestCase.php

@@ -12,6 +12,9 @@
  * Base test case for timestamp range types (TsRange, TstzRange).
  * Provides common timestamp-specific test patterns.
  */
+/**
+ * @template R of \DateTimeInterface
+ */
 abstract class BaseTimestampRangeTestCase extends BaseRangeTestCase
 {
     protected function getBoundaryTestCases(): array
@@ -36,6 +39,9 @@ protected function getBoundaryTestCases(): array
         ];
     }
 
+    /**
+     * @return array<string, array{range: Range<R>, expectedEmpty: bool}>
+     */
     protected function getComparisonTestCases(): array
     {
         return [
@@ -73,6 +79,7 @@ public function throws_exception_for_invalid_constructor_input(): void
     {
         $this->expectException(\TypeError::class);
 
+        /* @phpstan-ignore-next-line */
         $this->createRangeWithTimes('invalid', $this->getTestEndTime());
     }
 
@@ -124,6 +131,8 @@ public function can_handle_different_datetime_implementations(): void
 
     /**
      * Create a range with specific DateTimeInterface objects.
+     *
+     * @return Range<R>
      */
     abstract protected function createRangeWithTimes(
         ?\DateTimeInterface $start,

tests/Unit/MartinGeorgiev/Doctrine/DBAL/Types/ValueObject/DateRangeTest.php

@@ -10,6 +10,9 @@
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\Attributes\Test;
 
+/**
+ * @extends BaseRangeTestCase<\DateTimeInterface>
+ */
 final class DateRangeTest extends BaseRangeTestCase
 {
     protected function createSimpleRange(): Range

tests/Unit/MartinGeorgiev/Doctrine/DBAL/Types/ValueObject/Int4RangeTest.php

@@ -8,6 +8,9 @@
 use MartinGeorgiev\Doctrine\DBAL\Types\ValueObject\Range;
 use PHPUnit\Framework\Attributes\Test;
 
+/**
+ * @extends BaseRangeTestCase<int>
+ */
 final class Int4RangeTest extends BaseRangeTestCase
 {
     protected function createSimpleRange(): Range

tests/Unit/MartinGeorgiev/Doctrine/DBAL/Types/ValueObject/Int8RangeTest.php

@@ -8,6 +8,9 @@
 use MartinGeorgiev\Doctrine\DBAL\Types\ValueObject\Range;
 use PHPUnit\Framework\Attributes\Test;
 
+/**
+ * @extends BaseRangeTestCase<int>
+ */
 final class Int8RangeTest extends BaseRangeTestCase
 {
     protected function createSimpleRange(): Range

tests/Unit/MartinGeorgiev/Doctrine/DBAL/Types/ValueObject/NumericRangeTest.php

@@ -9,6 +9,9 @@
 use MartinGeorgiev\Doctrine\DBAL\Types\ValueObject\Range;
 use PHPUnit\Framework\Attributes\Test;
 
+/**
+ * @extends BaseRangeTestCase<float|int>
+ */
 final class NumericRangeTest extends BaseRangeTestCase
 {
     protected function createSimpleRange(): Range

tests/Unit/MartinGeorgiev/Doctrine/DBAL/Types/ValueObject/TsRangeTest.php

@@ -8,6 +8,9 @@
 use MartinGeorgiev\Doctrine\DBAL\Types\ValueObject\TsRange;
 use PHPUnit\Framework\Attributes\Test;
 
+/**
+ * @extends BaseTimestampRangeTestCase<\DateTimeInterface>
+ */
 final class TsRangeTest extends BaseTimestampRangeTestCase
 {
     protected function createSimpleRange(): Range
@@ -230,6 +233,7 @@ public function throws_exception_for_invalid_value_in_constructor(): void
     {
         $this->expectException(\TypeError::class);
 
+        /* @phpstan-ignore-next-line */
         new TsRange('invalid', new \DateTimeImmutable('2023-01-01 18:00:00'));
     }
 

tests/Unit/MartinGeorgiev/Doctrine/DBAL/Types/ValueObject/TstzRangeTest.php

@@ -8,6 +8,9 @@
 use MartinGeorgiev\Doctrine\DBAL\Types\ValueObject\TstzRange;
 use PHPUnit\Framework\Attributes\Test;
 
+/**
+ * @extends BaseTimestampRangeTestCase<\DateTimeInterface>
+ */
 final class TstzRangeTest extends BaseTimestampRangeTestCase
 {
     protected function createSimpleRange(): Range
@@ -180,6 +183,7 @@ public function throws_exception_for_invalid_constructor_input(): void
     {
         $this->expectException(\TypeError::class);
 
+        /* @phpstan-ignore-next-line */
         new TstzRange('invalid', new \DateTimeImmutable('2023-01-01 18:00:00+00:00'));
     }