Update to PHPStan 2

composer.json

@@ -37,9 +37,11 @@
         "phpmd/phpmd": "^2.15",
         "phpstan/phpstan": "^1.12",
         "phpstan/phpstan-phpunit": "^1.4",
+        "phpstan/phpstan": "^2.1",
+        "phpstan/phpstan-phpunit": "^2.0",
         "phpunit/phpunit": "^10.5",
         "slevomat/coding-standard": "^8.15",
-        "squizlabs/php_codesniffer": "^3.11 || ^4.0"
+        "squizlabs/php_codesniffer": "^4.0"
     },
     "config": {
         "sort-packages": true,

src/InnerList.php

@@ -4,6 +4,9 @@
 
 namespace gapple\StructuredFields;
 
+/**
+ * @method array<TupleInterface|list{mixed,object}> getValue()
+ */
 class InnerList implements TupleInterface
 {
     use TupleTrait;

src/Item.php

@@ -4,6 +4,9 @@
 
 namespace gapple\StructuredFields;
 
+/**
+ * @method mixed getValue()
+ */
 class Item implements TupleInterface
 {
     use TupleTrait;

src/Serializer.php

@@ -39,27 +39,27 @@ public static function serializeItem(mixed $value, ?object $parameters = null):
     }
 
     /**
-     * @param iterable<TupleInterface|array{mixed, object}> $value
+     * @param iterable<TupleInterface|list{TupleInterface|list{mixed, object}, object}> $value
      */
     public static function serializeList(iterable $value): string
     {
         if ($value instanceof \Traversable) {
-            // @todo Checking for Traversable is not required for PHP ^8.2.0.
             $value = iterator_to_array($value);
         }
 
         $returnValue = array_map(function ($item) {
-            if ($item instanceof TupleInterface) {
-                $itemValue = $item->getValue();
-                $itemParameters = $item->getParameters();
-            } elseif (is_array($item) && count($item) === 2) {
+            if (is_array($item) && count($item) === 2) {
                 $itemValue = $item[0];
                 $itemParameters = $item[1];
+            } elseif ($item instanceof TupleInterface) {
+                $itemValue = $item->getValue();
+                $itemParameters = $item->getParameters();
             } else {
                 throw new SerializeException("Invalid item in list");
             }
 
             if (is_array($itemValue)) {
+                /** @var array<TupleInterface|list{mixed, object}> $itemValue */
                 return self::serializeInnerList($itemValue, $itemParameters);
             } else {
                 return self::serializeItem($itemValue, $itemParameters);
@@ -73,8 +73,6 @@ public static function serializeList(iterable $value): string
      * Serialize an object as a dictionary.
      *
      * Either a Traversable object can be provided, or the public properties of the object will be extracted.
-     *
-     * @param Dictionary|object $value
      */
     public static function serializeDictionary(object $value): string
     {
@@ -84,6 +82,10 @@ public static function serializeDictionary(object $value): string
             $value = get_object_vars($value);
         }
 
+        /**
+         * @var string $key
+         * @var TupleInterface|list{TupleInterface|list{mixed,object}, object} $item
+         */
         foreach ($value as $key => $item) {
             if (!empty($returnValue)) {
                 $returnValue .= ', ';
@@ -102,6 +104,7 @@ public static function serializeDictionary(object $value): string
             if ($itemValue === true) {
                 $returnValue .= self::serializeParameters($itemParameters);
             } elseif (is_array($itemValue)) {
+                /** @var array<TupleInterface|list{mixed, object}> $itemValue */
                 $returnValue .= '=' . self::serializeInnerList($itemValue, $itemParameters);
             } else {
                 $returnValue .= '=' . self::serializeItem($itemValue, $itemParameters);
@@ -189,7 +192,7 @@ private static function serializeDecimal(float $value): string
 
         // Casting to a string loses a digit on long numbers, but is preserved
         // by json_encode (e.g. 111111111111.111).
-        /** @var string $result */
+        /** @var non-empty-string $result */
         $result = json_encode(round($value, 3, PHP_ROUND_HALF_EVEN));
 
         if (!str_contains($result, '.')) {
@@ -250,6 +253,7 @@ private static function serializeParameters(object $value): string
             $value = get_object_vars($value);
         }
 
+        /** @var string $key */
         foreach ($value as $key => $item) {
             $returnValue .= ';' . self::serializeKey($key);
 

tests/Httpwg/HttpwgTestBase.php

@@ -6,6 +6,15 @@
 use gapple\Tests\StructuredFields\RulesetTestBase;
 use gapple\Tests\StructuredFields\SerializingRulesetTrait;
 
+/**
+ * @phpstan-import-type ExpectedItem from HttpwgRuleExpectedConverter
+ * @phpstan-import-type ExpectedOuterList from HttpwgRuleExpectedConverter
+ * @phpstan-import-type ExpectedDictionary from HttpwgRuleExpectedConverter
+ * @phpstan-type RuleDefinition object{
+ *     header_type: 'item'|'list'|'dictionary',
+ *     expected: ExpectedItem|ExpectedOuterList|ExpectedDictionary
+ *   }
+ */
 abstract class HttpwgTestBase extends RulesetTestBase
 {
     use SerializingRulesetTrait;
@@ -27,7 +36,7 @@ protected static function rulesetDataProvider(): array
             throw new \RuntimeException("Unable to read ruleset JSON file.");
         }
 
-        /** @var array<\stdClass>|null $rules */
+        /** @var array<RuleDefinition&\stdClass>|null $rules */
         $rules = json_decode($rulesJson);
         if (is_null($rules) || json_last_error() !== JSON_ERROR_NONE) {
             throw new \RuntimeException("Unable to parse ruleset JSON file.");
@@ -38,8 +47,11 @@ protected static function rulesetDataProvider(): array
             if (isset($rawRule->expected)) {
                 try {
                     $rawRule->expected = match ($rawRule->header_type) {
+                        // @phpstan-ignore argument.type
                         'item' => HttpwgRuleExpectedConverter::item($rawRule->expected),
+                        // @phpstan-ignore argument.type
                         'list' => HttpwgRuleExpectedConverter::list($rawRule->expected),
+                        // @phpstan-ignore argument.type
                         'dictionary' => HttpwgRuleExpectedConverter::dictionary($rawRule->expected),
                         default => throw new \UnexpectedValueException('Unknown header type'),
                     };

tests/ItemTest.php

@@ -41,7 +41,7 @@ public function testArraySet(): void
         $item[0] = 'Modified Value';
         $item[1] = (object) ['paramKey' => 'Modified param value'];
         $this->assertEquals('Modified Value', $item[0]);
-        $this->assertEquals('Modified param value', $item[1]->paramKey); // @phpstan-ignore-line
+        $this->assertEquals('Modified param value', $item[1]->paramKey);
     }
 
     public function testArrayIndexIsset(): void

tests/OuterListTest.php

@@ -85,6 +85,7 @@ public function testIteration(): void
         $this->assertIsIterable($list);
 
         $iterated = 0;
+        /** @var int $key */
         foreach ($list as $key => $value) {
             $this->assertEquals($listValues[$key], $value);
             $iterated++;

tests/ParsingRulesetTrait.php

@@ -23,6 +23,9 @@ public static function parseRulesetDataProvider(): array
     public function testParsing(Rule $record): void
     {
         try {
+            if (is_null($record->raw)) {
+                throw new \RuntimeException("Raw value not defined for parsing test");
+            }
             $raw = implode(', ', $record->raw);
             $parsedValue = Parser::{'parse' . ucfirst($record->header_type)}($raw);
 

tests/SerializeListTest.php

@@ -140,6 +140,6 @@ public function testNestedInnerListObject(): void
 
         $this->expectException(SerializeException::class);
         $this->expectExceptionMessage("Inner lists cannot be nested");
-        Serializer::serializeList($list);
+        Serializer::serializeList($list); // @phpstan-ignore argument.type
     }
 }

tests/SerializingRulesetTrait.php

@@ -23,14 +23,15 @@ public static function serializeRulesetDataProvider(): array
     public function testSerializing(Rule $record): void
     {
         try {
+            // @phpstan-ignore argument.type
             $serializedValue = Serializer::{'serialize' . ucfirst($record->header_type)}($record->expected);
 
             if ($record->must_fail) {
                 $this->fail('"' . $record->name . '" must fail serializing');
             }
 
             $this->assertEquals(
-                implode(', ', $record->canonical ?? $record->raw),
+                implode(', ', $record->canonical ?? $record->raw ?? []),
                 $serializedValue,
                 '"' . $record->name . '" was not serialized to expected value'
             );