Merge pull request #790 from kukulich/types

Improved precision of declared types in internal code and exposed return values

src/Reflection/Adapter/ReflectionFunction.php

@@ -255,7 +255,7 @@ public function invoke(mixed ...$args)
     }
 
     /**
-     * @param mixed[] $args
+     * @param list<mixed> $args
      */
     public function invokeArgs(array $args)
     {

src/Reflection/Adapter/ReflectionMethod.php

@@ -340,7 +340,7 @@ public function invoke(?object $object = null, mixed ...$args)
     }
 
     /**
-     * @param mixed[] $args
+     * @param list<mixed> $args
      */
     public function invokeArgs(?object $object = null, array $args = [])
     {

src/Reflection/ReflectionClass.php

@@ -236,7 +236,7 @@ public function getExtensionName(): ?string
     }
 
     /**
-     * @return ReflectionMethod[]
+     * @return list<ReflectionMethod>
      */
     private function createMethodsFromTrait(ReflectionMethod $method): array
     {
@@ -435,11 +435,11 @@ public function getMethods(?int $filter = null): array
      *
      * @see ReflectionClass::getMethods for the usage of $filter
      *
-     * @return ReflectionMethod[]
+     * @return array<string, ReflectionMethod>
      */
     public function getImmediateMethods(?int $filter = null): array
     {
-        /** @var ReflectionMethod[] $methods */
+        /** @var list<ReflectionMethod> $methods */
         $methods = array_map(
             fn (ClassMethod $methodNode): ReflectionMethod => ReflectionMethod::createFromNode(
                 $this->reflector,
@@ -603,7 +603,7 @@ public function getReflectionConstants(): array
     {
         // Note: constants are not merged via their name as array index, since internal PHP constant
         //       sorting does not follow `\array_merge()` semantics
-        /** @var ReflectionClassConstant[] $allReflectionConstants */
+        /** @var list<ReflectionClassConstant> $allReflectionConstants */
         $allReflectionConstants = array_merge(
             array_values($this->getImmediateReflectionConstants()),
             ...array_map(
@@ -1014,7 +1014,7 @@ private function reflectClassForNamedNode(Node\Name $node): self
      * defined. If this class does not have any defined traits, this will
      * return an empty array.
      *
-     * @return string[]
+     * @return list<string>
      */
     public function getTraitNames(): array
     {
@@ -1351,7 +1351,7 @@ private function getCurrentClassImplementedInterfacesIndexedByName(): array
     }
 
     /**
-     * @return ReflectionClass[] ordered from inheritance root to leaf (this class)
+     * @return list<ReflectionClass> ordered from inheritance root to leaf (this class)
      */
     private function getInheritanceClassHierarchy(): array
     {

src/Reflection/ReflectionFunction.php

@@ -102,7 +102,7 @@ public function invoke(mixed ...$args): mixed
     }
 
     /**
-     * @param mixed[] $args
+     * @param list<mixed> $args
      *
      * @throws NotImplemented
      * @throws FunctionDoesNotExist

src/Reflection/ReflectionFunctionAbstract.php

@@ -349,7 +349,7 @@ public function returnsReference(): bool
      * when you type hint pipe-separated "string|null", in which case this
      * would return an array of Type objects, one for string, one for null.
      *
-     * @return Type[]
+     * @return list<Type>
      */
     public function getDocBlockReturnTypes(): array
     {

src/Reflection/ReflectionMethod.php

@@ -289,7 +289,7 @@ public function invoke(?object $object = null, mixed ...$args): mixed
     }
 
     /**
-     * @param mixed[] $args
+     * @param list<mixed> $args
      *
      * @throws ClassDoesNotExist
      * @throws NoObjectProvided
@@ -309,7 +309,7 @@ public function invokeArgs(?object $object = null, array $args = []): mixed
     }
 
     /**
-     * @param mixed[] $args
+     * @param list<mixed> $args
      */
     private function callStaticMethod(array $args): mixed
     {
@@ -324,7 +324,7 @@ private function callStaticMethod(array $args): mixed
     }
 
     /**
-     * @param mixed[] $args
+     * @param list<mixed> $args
      */
     private function callObjectMethod(object $object, array $args): mixed
     {

src/Reflection/ReflectionParameter.php

@@ -322,7 +322,7 @@ public function allowsNull(): bool
     /**
      * Get the DocBlock type hints as an array of strings.
      *
-     * @return string[]
+     * @return list<string>
      */
     public function getDocBlockTypeStrings(): array
     {
@@ -343,7 +343,7 @@ public function getDocBlockTypeStrings(): array
      *
      * @see getTypeHint()
      *
-     * @return Type[]
+     * @return list<Type>
      */
     public function getDocBlockTypes(): array
     {

src/Reflection/ReflectionProperty.php

@@ -228,7 +228,7 @@ public function isInitialized(?object $object = null): bool
     /**
      * Get the DocBlock type hints as an array of strings.
      *
-     * @return string[]
+     * @return list<string>
      */
     public function getDocBlockTypeStrings(): array
     {
@@ -247,7 +247,7 @@ public function getDocBlockTypeStrings(): array
      * when you type hint pipe-separated "string|null", in which case this
      * would return an array of Type objects, one for string, one for null.
      *
-     * @return Type[]
+     * @return list<Type>
      */
     public function getDocBlockTypes(): array
     {

src/Reflection/StringCast/ReflectionClassStringCast.php

@@ -128,7 +128,7 @@ private static function fileAndLinesToString(ReflectionClass $classReflection):
     }
 
     /**
-     * @param ReflectionClassConstant[] $constants
+     * @param array<ReflectionClassConstant> $constants
      */
     private static function constantsToString(array $constants): string
     {
@@ -140,7 +140,7 @@ private static function constantsToString(array $constants): string
     }
 
     /**
-     * @param ReflectionProperty[] $properties
+     * @param array<ReflectionProperty> $properties
      */
     private static function propertiesToString(array $properties): string
     {
@@ -152,7 +152,7 @@ private static function propertiesToString(array $properties): string
     }
 
     /**
-     * @param ReflectionMethod[] $methods
+     * @param array<ReflectionMethod> $methods
      */
     private static function methodsToString(ReflectionClass $classReflection, array $methods, int $emptyLinesAmongItems = 1): string
     {
@@ -164,7 +164,7 @@ private static function methodsToString(ReflectionClass $classReflection, array
     }
 
     /**
-     * @param string[] $items
+     * @param array<string> $items
      */
     private static function itemsToString(array $items, int $emptyLinesAmongItems = 1): string
     {
@@ -179,39 +179,39 @@ private static function indent(): string
     }
 
     /**
-     * @return ReflectionProperty[]
+     * @return array<ReflectionProperty>
      */
     private static function getStaticProperties(ReflectionClass $classReflection): array
     {
         return array_filter($classReflection->getProperties(), static fn (ReflectionProperty $propertyReflection): bool => $propertyReflection->isStatic());
     }
 
     /**
-     * @return ReflectionMethod[]
+     * @return array<ReflectionMethod>
      */
     private static function getStaticMethods(ReflectionClass $classReflection): array
     {
         return array_filter($classReflection->getMethods(), static fn (ReflectionMethod $methodReflection): bool => $methodReflection->isStatic());
     }
 
     /**
-     * @return ReflectionProperty[]
+     * @return array<ReflectionProperty>
      */
     private static function getDefaultProperties(ReflectionClass $classReflection): array
     {
         return array_filter($classReflection->getProperties(), static fn (ReflectionProperty $propertyReflection): bool => ! $propertyReflection->isStatic() && $propertyReflection->isDefault());
     }
 
     /**
-     * @return ReflectionProperty[]
+     * @return array<ReflectionProperty>
      */
     private static function getDynamicProperties(ReflectionClass $classReflection): array
     {
         return array_filter($classReflection->getProperties(), static fn (ReflectionProperty $propertyReflection): bool => ! $propertyReflection->isStatic() && ! $propertyReflection->isDefault());
     }
 
     /**
-     * @return ReflectionMethod[]
+     * @return array<ReflectionMethod>
      */
     private static function getMethods(ReflectionClass $classReflection): array
     {

src/SourceLocator/Ast/Locator.php

@@ -50,7 +50,7 @@ public function findReflection(
     /**
      * Get an array of reflections found in some code.
      *
-     * @return Reflection[]
+     * @return list<Reflection>
      *
      * @throws Exception\ParseToAstFailure
      */
@@ -74,7 +74,7 @@ public function findReflectionsOfType(
     /**
      * Given an array of Reflections, try to find the identifier.
      *
-     * @param Reflection[] $reflections
+     * @param list<Reflection> $reflections
      *
      * @throws IdentifierNotFound
      */

src/SourceLocator/Ast/Parser/MemoizingParser.php

@@ -18,7 +18,7 @@
  */
 final class MemoizingParser implements Parser
 {
-    /** @var string[] indexed by source hash */
+    /** @var array<string, string> indexed by source hash */
     private array $sourceHashToAst = [];
 
     public function __construct(private Parser $wrappedParser)

src/SourceLocator/SourceStubber/AggregateSourceStubber.php

@@ -6,15 +6,16 @@
 
 use function array_merge;
 use function array_reduce;
+use function array_values;
 
 class AggregateSourceStubber implements SourceStubber
 {
-    /** @var SourceStubber[] */
+    /** @var list<SourceStubber> */
     private array $sourceStubbers;
 
     public function __construct(SourceStubber $sourceStubber, SourceStubber ...$otherSourceStubbers)
     {
-        $this->sourceStubbers = array_merge([$sourceStubber], $otherSourceStubbers);
+        $this->sourceStubbers = array_values(array_merge([$sourceStubber], $otherSourceStubbers));
     }
 
     public function generateClassStub(string $className): ?StubData

src/SourceLocator/SourceStubber/PhpStormStubsSourceStubber.php

@@ -406,7 +406,7 @@ private function updateConstantValue(Node\Expr\FuncCall|Node\Const_ $node, strin
                 }
 
                 // @ because access to deprecated constant throws deprecated warning
-                /** @var scalar|scalar[]|null $constantValue */
+                /** @var scalar|list<scalar>|null $constantValue */
                 $constantValue           = @constant($constantName);
                 $normalizedConstantValue = BuilderHelpers::normalizeValue($constantValue);
 

src/SourceLocator/SourceStubber/ReflectionSourceStubber.php

@@ -152,7 +152,7 @@ public function generateConstantStub(string $constantName): ?StubData
     }
 
     /**
-     * @return array{0: scalar|scalar[]|null, 1: string}|null
+     * @return array{0: scalar|list<scalar>|null, 1: string}|null
      */
     private function findConstantData(string $constantName): ?array
     {

src/SourceLocator/Type/AggregateSourceLocator.php

@@ -14,11 +14,11 @@
 
 class AggregateSourceLocator implements SourceLocator
 {
-    /** @var SourceLocator[] */
+    /** @var list<SourceLocator> */
     private array $sourceLocators;
 
     /**
-     * @param SourceLocator[] $sourceLocators
+     * @param list<SourceLocator> $sourceLocators
      */
     public function __construct(array $sourceLocators = [])
     {

src/SourceLocator/Type/AnonymousClassObjectSourceLocator.php

@@ -89,7 +89,7 @@ private function getReflectionClass(Reflector $reflector, IdentifierType $identi
 
         $nodeVisitor = new class ($fileName, $this->coreClassReflection->getStartLine()) extends NodeVisitorAbstract
         {
-            /** @var Class_[] */
+            /** @var list<Class_> */
             private array $anonymousClassNodes = [];
 
             public function __construct(private string $fileName, private int $startLine)
@@ -112,7 +112,7 @@ public function enterNode(Node $node)
 
             public function getAnonymousClassNode(): Class_
             {
-                /** @var Class_[] $anonymousClassNodesOnSameLine */
+                /** @var list<Class_> $anonymousClassNodesOnSameLine */
                 $anonymousClassNodesOnSameLine = array_values(array_filter($this->anonymousClassNodes, fn (Class_ $node): bool => $node->getLine() === $this->startLine));
 
                 if (! $anonymousClassNodesOnSameLine) {

src/SourceLocator/Type/AutoloadSourceLocator/FileReadTrapStreamWrapper.php

@@ -31,7 +31,7 @@ final class FileReadTrapStreamWrapper
         'phar',
     ];
 
-    /** @var string[]|null */
+    /** @var list<string>|null */
     private static ?array $registeredStreamWrapperProtocols;
 
     /**
@@ -44,7 +44,7 @@ final class FileReadTrapStreamWrapper
 
     /**
      * @param callable() : ExecutedMethodReturnType $executeMeWithinStreamWrapperOverride
-     * @param string[]                              $streamWrapperProtocols
+     * @param list<string>                          $streamWrapperProtocols
      *
      * @psalm-return ExecutedMethodReturnType
      *