feat: support unions in arrays

src/Metadata/Driver/DocBlockDriver/DocBlockTypeResolver.php

@@ -21,6 +21,8 @@
 use PHPStan\PhpDocParser\Parser\TokenIterator;
 use PHPStan\PhpDocParser\Parser\TypeParser;
 
+use function sprintf;
+
 /**
  * @internal
  */
@@ -116,19 +118,42 @@ private function getDocBlocTypeHint($reflector): ?string
 
         // Generic array syntax: array<Product> | array<\Foo\Bar\Product> | array<int,Product>
         if ($type instanceof GenericTypeNode) {
-            if ($this->isSimpleType($type->type, 'array')) {
-                $resolvedTypes = array_map(fn (TypeNode $node) => $this->resolveTypeFromTypeNode($node, $reflector), $type->genericTypes);
+            $isSimpleTypeArray = $this->isSimpleType($type->type, 'array');
+            $isSimpleTypeList = $this->isSimpleType($type->type, 'list');
+            if (!$isSimpleTypeArray && !$isSimpleTypeList) {
+                throw new \InvalidArgumentException(sprintf("Can't use non-array generic type %s for collection in %s:%s", (string) $type->type, $reflector->getDeclaringClass()->getName(), $reflector->getName()));
+            }
+
+            if ($isSimpleTypeList) {
+                $keyType = 'int';
+                $valuesIndex = 0;
+            } else {
+                if (1 === count($type->genericTypes)) {
+                    $keyType = null;
+                    $valuesIndex = 0;
+                } else {
+                    $keyType = $this->resolveTypeFromTypeNode($type->genericTypes[0], $reflector);
+                    $valuesIndex = 1;
+                }
+            }
 
-                return 'array<' . implode(',', $resolvedTypes) . '>';
+            if ($type->genericTypes[$valuesIndex] instanceof UnionTypeNode) {
+                $valueTypes = array_map(
+                    fn (TypeNode $node) => $this->resolveTypeFromTypeNode($node, $reflector),
+                    $type->genericTypes[$valuesIndex]->types,
+                );
+            } else {
+                $valueType = $this->resolveTypeFromTypeNode($type->genericTypes[$valuesIndex], $reflector);
+                $valueTypes = [$valueType];
             }
 
-            if ($this->isSimpleType($type->type, 'list')) {
-                $resolvedTypes = array_map(fn (TypeNode $node) => $this->resolveTypeFromTypeNode($node, $reflector), $type->genericTypes);
+            $valueType = implode('|', $valueTypes);
 
-                return 'array<int, ' . implode(',', $resolvedTypes) . '>';
+            if (null === $keyType) {
+                return sprintf('array<%s>', $valueType);
             }
 
-            throw new \InvalidArgumentException(sprintf("Can't use non-array generic type %s for collection in %s:%s", (string) $type->type, $reflector->getDeclaringClass()->getName(), $reflector->getName()));
+            return sprintf('array<%s, %s>', $keyType, $valueType);
         }
 
         // Primitives and class names: Collection | \Foo\Bar\Product | string

src/Type/Lexer.php

@@ -23,6 +23,7 @@ final class Lexer extends AbstractLexer
     public const T_TYPE_END = 8;
     public const T_IDENTIFIER = 9;
     public const T_NULL = 10;
+    public const T_UNION_SEPARATOR = 11;
 
     public function parse(string $type)
     {
@@ -103,6 +104,9 @@ protected function getType(&$value)
             case '[' === $value:
                 return self::T_ARRAY_START;
 
+            case '|' === $value:
+                return self::T_UNION_SEPARATOR;
+
             // Default
             default:
                 // Do nothing

src/Type/Parser.php

@@ -95,6 +95,12 @@ private function visitCompoundType(): array
                     break;
                 }
 
+                if ($this->lexer->isNextToken(Lexer::T_UNION_SEPARATOR)) {
+                    $this->match(Lexer::T_UNION_SEPARATOR);
+
+                    continue;
+                }
+
                 $this->match(Lexer::T_COMMA);
             }
         }

tests/Fixtures/DocBlockType/Collection/MapTypedAsGenericClass.php

@@ -10,4 +10,14 @@ class MapTypedAsGenericClass
      * @var array<int, Product>
      */
     public array $productIds;
+
+    /**
+     * @var array<Product|Vehicle>
+     */
+    public array $productOrVehicleIds;
+
+    /**
+     * @var array<int, Product|Vehicle>
+     */
+    public array $productOrVehicleIdsWithKey;
 }

tests/Metadata/Driver/DocBlockDriverTest.php

@@ -131,6 +131,27 @@
             ['name' => 'array', 'params' => [['name' => 'int', 'params' => []], ['name' => Product::class, 'params' => []]]],
             $m->propertyMetadata['productIds']->type,
         );
+        self::assertEquals(
+            [
+                'name' => 'array',
+                'params' => [
+                    ['name' => Product::class, 'params' => []],
+                    ['name' => Vehicle::class, 'params' => []],
+                ]
+            ],
+            $m->propertyMetadata['productOrVehicleIds']->type,
+        );
+        self::assertEquals(
+            [
+                'name' => 'array',
+                'params' => [
+                    ['name' => 'int', 'params' => []],
+                    ['name' => Product::class, 'params' => []],
+                    ['name' => Vehicle::class, 'params' => []],
+                ]
+            ],
+            $m->propertyMetadata['productOrVehicleIdsWithKey']->type,
+        );
     }
 
     public function testInferDocBlockCollectionOfClassesIgnoringNullTypeHint()