Further reflection api improvements

Reflection/ReflectionAttribute.php

@@ -5,7 +5,7 @@
 /**
  * @since 8.0
  *
- * @template TAttributeClass of object
+ * @template-covariant TAttributeClass of object
  */
 class ReflectionAttribute implements Reflector
 {

Reflection/ReflectionClass.php

@@ -11,7 +11,7 @@
  * The <b>ReflectionClass</b> class reports information about a class.
  *
  * @link https://php.net/manual/en/class.reflectionclass.php
- * @template TReflectedClass of object
+ * @template-covariant TReflectedClass of object
  */
 class ReflectionClass implements Reflector
 {
@@ -62,7 +62,7 @@ class ReflectionClass implements Reflector
      * Constructs a ReflectionClass
      *
      * @link https://php.net/manual/en/reflectionclass.construct.php
-     * @param class-string<TReflectedClass>|TReflectedClass $objectOrClass Either a string containing the name of
+     * @param TReflectedClass|class-string<TReflectedClass> $objectOrClass Either a string containing the name of
      * the class to reflect, or an object.
      * @throws ReflectionException if the class does not exist.
      */
@@ -210,7 +210,7 @@ public function hasMethod(#[LanguageLevelTypeAware(['8.0' => 'string'], default:
      * Gets a <b>ReflectionMethod</b> for a class method.
      *
      * @link https://php.net/manual/en/reflectionclass.getmethod.php
-     * @param non-empty-string $name The method name to reflect.
+     * @param non-falsy-string $name The method name to reflect.
      * @return ReflectionMethod<TReflectedClass> A {@see ReflectionMethod}
      * @throws ReflectionException if the method does not exist.
      */
@@ -494,7 +494,7 @@ public function newInstanceWithoutConstructor(): object {}
      * Creates a new class instance from given arguments.
      *
      * @link https://php.net/manual/en/reflectionclass.newinstanceargs.php
-     * @param array $args The parameters to be passed to the class constructor as an array.
+     * @param array<int|string, mixed> $args The parameters to be passed to the class constructor as an array.
      * @return TReflectedClass|null a new instance of the class.
      * @throws ReflectionException if the class constructor is not public or if
      * the class does not have a constructor and the $args parameter contains
@@ -672,7 +672,7 @@ public function getShortName(): string {}
      * @template TAttributeClass of object
      * @param class-string<TAttributeClass>|null $name Name of an attribute class
      * @param int $flags Сriteria by which the attribute is searched.
-     * @return list<ReflectionAttribute<TAttributeClass>>
+     * @return ($name is null ? list<ReflectionAttribute<object>> : list<ReflectionAttribute<TAttributeClass>>)
      * @since 8.0
      */
     #[Pure]
@@ -700,42 +700,56 @@ private function __clone(): void {}
     public function isEnum(): bool {}
 
     /**
+     * @param (callable(TReflectedClass): void) $initializer
+     * @return TReflectedClass
      * @since 8.4
      */
     public function newLazyGhost(callable $initializer, int $options = 0): object {}
 
     /**
+     * @param (callable(TReflectedClass): TReflectedClass) $factory
      * @return TReflectedClass
      * @since 8.4
      */
     public function newLazyProxy(callable $factory, int $options = 0): object {}
 
     /**
+     * @param TReflectedClass $object
+     * @param (callable(TReflectedClass): void) $initializer
      * @since 8.4
      */
     public function resetAsLazyGhost(object $object, callable $initializer, int $options = 0): void {}
 
     /**
+     * @param TReflectedClass $object
+     * @param (callable(TReflectedClass): TReflectedClass) $factory
      * @since 8.4
      */
     public function resetAsLazyProxy(object $object, callable $factory, int $options = 0): void {}
 
     /**
+     * @param TReflectedClass $object
+     * @return TReflectedClass
      * @since 8.4
      */
     public function initializeLazyObject(object $object): object {}
 
     /**
+     * @param TReflectedClass $object
+     * @return TReflectedClass
      * @since 8.4
      */
     public function isUninitializedLazyObject(object $object): bool {}
 
     /**
+     * @param TReflectedClass $object
      * @since 8.4
      */
     public function markLazyObjectAsInitialized(object $object): object {}
 
     /**
+     * @param TReflectedClass $object
+     * @return null|(callable(TReflectedClass): void)
      * @since 8.4
      */
     public function getLazyInitializer(object $object): ?callable {}

Reflection/ReflectionClassConstant.php

@@ -89,7 +89,7 @@ public static function export($class, $name, $return = false) {}
     /**
      * Gets declaring class
      *
-     * @return ReflectionClass
+     * @return ReflectionClass<TReflectedClass>
      * @link https://php.net/manual/en/reflectionclassconstant.getdeclaringclass.php
      * @since 7.1
      */
@@ -190,7 +190,7 @@ public function __toString(): string {}
      * @template TAttributeClass of object
      * @param class-string<TAttributeClass>|null $name Name of an attribute class
      * @param int $flags Сriteria by which the attribute is searched.
-     * @return list<ReflectionAttribute<TAttributeClass>>
+     * @return ($name is null ? list<ReflectionAttribute<object>> : list<ReflectionAttribute<TAttributeClass>>)
      * @since 8.0
      */
     #[Pure]

Reflection/ReflectionConstant.php

@@ -41,7 +41,7 @@ public function getExtensionName(): string|false {}
      * @template TAttributeClass of object
      * @param class-string<TAttributeClass>|null $name Name of an attribute class
      * @param int $flags Сriteria by which the attribute is searched.
-     * @return list<ReflectionAttribute<TAttributeClass>>
+     * @return ($name is null ? list<ReflectionAttribute<object>> : list<ReflectionAttribute<TAttributeClass>>)
      * @since 8.5
      */
     public function getAttributes(?string $name = null, int $flags = 0): array {}

Reflection/ReflectionEnum.php

@@ -5,7 +5,8 @@
 /**
  * @link https://php.net/manual/en/class.reflectionenum.php
  * @since 8.1
- * @template TReflectedClass of UnitEnum
+ * @template-covariant TReflectedClass of UnitEnum
+ * @extends ReflectionClass<TReflectedClass>
  */
 class ReflectionEnum extends ReflectionClass
 {

Reflection/ReflectionEnumBackedCase.php

@@ -6,6 +6,7 @@
  * @link https://php.net/manual/en/class.reflectionenumbackedcase.php
  * @since 8.1
  * @template TReflectedClass of BackedEnum
+ * @extends ReflectionEnumUnitCase<TReflectedClass>
  */
 class ReflectionEnumBackedCase extends ReflectionEnumUnitCase
 {

Reflection/ReflectionEnumUnitCase.php

@@ -6,6 +6,7 @@
  * @link https://php.net/manual/en/class.reflectionenumunitcase.php
  * @since 8.1
  * @template TReflectedClass of UnitEnum
+ * @extends ReflectionClassConstant<TReflectedClass>
  */
 class ReflectionEnumUnitCase extends ReflectionClassConstant
 {

Reflection/ReflectionExtension.php

@@ -80,7 +80,7 @@ public function getVersion(): ?string {}
      * Gets extension functions
      *
      * @link https://php.net/manual/en/reflectionextension.getfunctions.php
-     * @return ReflectionFunction[] An associative array of {@see ReflectionFunction} objects,
+     * @return array<string, ReflectionFunction> An associative array of {@see ReflectionFunction} objects,
      * for each function defined in the extension with the keys being the function
      * names. If no function are defined, an empty array is returned.
      */
@@ -92,7 +92,7 @@ public function getFunctions(): array {}
      * Gets constants
      *
      * @link https://php.net/manual/en/reflectionextension.getconstants.php
-     * @return array An associative array with constant names as keys.
+     * @return array<string, mixed> An associative array with constant names as keys.
      */
     #[Pure]
     #[TentativeType]
@@ -102,7 +102,7 @@ public function getConstants(): array {}
      * Gets extension ini entries
      *
      * @link https://php.net/manual/en/reflectionextension.getinientries.php
-     * @return array An associative array with the ini entries as keys,
+     * @return array<string, mixed> An associative array with the ini entries as keys,
      * with their defined values as values.
      */
     #[Pure]
@@ -113,7 +113,7 @@ public function getINIEntries(): array {}
      * Gets classes
      *
      * @link https://php.net/manual/en/reflectionextension.getclasses.php
-     * @return ReflectionClass[] An array of {@see ReflectionClass} objects, one
+     * @return array<string, ReflectionClass<object>> An array of {@see ReflectionClass} objects, one
      * for each class within the extension. If no classes are defined,
      * an empty array is returned.
      */
@@ -125,7 +125,7 @@ public function getClasses(): array {}
      * Gets class names
      *
      * @link https://php.net/manual/en/reflectionextension.getclassnames.php
-     * @return string[] An array of class names, as defined in the extension.
+     * @return list<class-string<object>> An array of class names, as defined in the extension.
      * If no classes are defined, an empty array is returned.
      */
     #[Pure]
@@ -136,7 +136,7 @@ public function getClassNames(): array {}
      * Gets dependencies
      *
      * @link https://php.net/manual/en/reflectionextension.getdependencies.php
-     * @return string[] An associative array with dependencies as keys and
+     * @return array<string, 'Required'|'Optional'|'Conflicts'> An associative array with dependencies as keys and
      * either Required, Optional or Conflicts as the values.
      */
     #[Pure]

Reflection/ReflectionFunctionAbstract.php

@@ -124,7 +124,7 @@ public function getClosureThis(): ?object {}
      * Returns the scope associated to the closure
      *
      * @link https://php.net/manual/en/reflectionfunctionabstract.getclosurescopeclass.php
-     * @return ReflectionClass|null Returns the class on success or {@see null}
+     * @return ReflectionClass<object>|null Returns the class on success or {@see null}
      * on failure.
      * @since 5.4
      */
@@ -133,7 +133,7 @@ public function getClosureThis(): ?object {}
     public function getClosureScopeClass(): ?ReflectionClass {}
 
     /**
-     * @return ReflectionClass|null Returns the class on success or {@see null}
+     * @return ReflectionClass<object>|null Returns the class on success or {@see null}
      * on failure.
      * @since 8.0
      */
@@ -321,7 +321,7 @@ public function hasReturnType(): bool {}
      * @template TAttributeClass of object
      * @param class-string<TAttributeClass>|null $name Name of an attribute class
      * @param int $flags Сriteria by which the attribute is searched.
-     * @return list<ReflectionAttribute<TAttributeClass>>
+     * @return ($name is null ? list<ReflectionAttribute<object>> : list<ReflectionAttribute<TAttributeClass>>)
      * @since 8.0
      */
     #[Pure]

Reflection/ReflectionMethod.php

@@ -17,7 +17,7 @@
 class ReflectionMethod extends ReflectionFunctionAbstract
 {
     /**
-     * @var string Name of the method, same as calling the {@see ReflectionMethod::getName()} method
+     * @var non-falsy-string Name of the method, same as calling the {@see ReflectionMethod::getName()} method
      */
     #[Immutable]
     #[LanguageLevelTypeAware(['8.1' => 'string'], default: '')]
@@ -73,7 +73,7 @@ class ReflectionMethod extends ReflectionFunctionAbstract
      * @param non-empty-string|class-string<TReflectedClass>|TReflectedClass $objectOrMethod Classname, object
      * (instance of the class) that contains the method or class name and
      * method name delimited by ::.
-     * @param non-empty-string|null $method Name of the method if the first argument is a
+     * @param non-falsy-string|null $method Name of the method if the first argument is a
      * classname or an object.
      * @throws ReflectionException if the class or method does not exist.
      */
@@ -264,7 +264,7 @@ public function invokeArgs(#[LanguageLevelTypeAware(['8.0' => 'object|null'], de
      * Gets declaring class for the reflected method.
      *
      * @link https://php.net/manual/en/reflectionmethod.getdeclaringclass.php
-     * @return ReflectionClass A {@see ReflectionClass} object of the class that the
+     * @return ReflectionClass<TReflectedClass> A {@see ReflectionClass} object of the class that the
      * reflected method is part of.
      */
     #[Pure]
@@ -275,7 +275,7 @@ public function getDeclaringClass(): ReflectionClass {}
      * Gets the method prototype (if there is one).
      *
      * @link https://php.net/manual/en/reflectionmethod.getprototype.php
-     * @return ReflectionMethod A {@see ReflectionMethod} instance of the method prototype.
+     * @return ReflectionMethod<object> A {@see ReflectionMethod} instance of the method prototype.
      * @throws ReflectionException if the method does not have a prototype
      */
     #[Pure]

Reflection/ReflectionParameter.php

@@ -102,7 +102,7 @@ public function getDeclaringFunction(): ReflectionFunctionAbstract {}
      * Gets declaring class
      *
      * @link https://php.net/manual/en/reflectionparameter.getdeclaringclass.php
-     * @return ReflectionClass|null A {@see ReflectionClass} object or {@see null} if
+     * @return ReflectionClass<object>|null A {@see ReflectionClass} object or {@see null} if
      * called on function.
      */
     #[Pure]
@@ -113,7 +113,7 @@ public function getDeclaringClass(): ?ReflectionClass {}
      * Gets the class type hinted for the parameter as a ReflectionClass object.
      *
      * @link https://php.net/manual/en/reflectionparameter.getclass.php
-     * @return ReflectionClass|null A {@see ReflectionClass} object.
+     * @return ReflectionClass<object>|null A {@see ReflectionClass} object.
      * @see ReflectionParameter::getType()
      */
     #[Deprecated(reason: "Use ReflectionParameter::getType() and the ReflectionType APIs should be used instead.", since: "8.0")]
@@ -281,7 +281,7 @@ public function isPromoted(): bool {}
      * @template TAttributeClass of object
      * @param class-string<TAttributeClass>|null $name Name of an attribute class
      * @param int $flags Сriteria by which the attribute is searched.
-     * @return list<ReflectionAttribute<TAttributeClass>>
+     * @return ($name is null ? list<ReflectionAttribute<object>> : list<ReflectionAttribute<TAttributeClass>>)
      * @since 8.0
      */
     #[Pure]

Reflection/ReflectionProperty.php

@@ -230,7 +230,7 @@ public function getModifiers(): int {}
      * Gets declaring class
      *
      * @link https://php.net/manual/en/reflectionproperty.getdeclaringclass.php
-     * @return ReflectionClass A {@see ReflectionClass} object.
+     * @return ReflectionClass<TReflectedClass> A {@see ReflectionClass} object.
      */
     #[Pure]
     #[TentativeType]
@@ -359,7 +359,7 @@ public function getDefaultValue(): mixed {}
      * @template TAttributeClass of object
      * @param class-string<TAttributeClass>|null $name Name of an attribute class
      * @param int $flags Сriteria by which the attribute is searched.
-     * @return list<ReflectionAttribute<TAttributeClass>>
+     * @return ($name is null ? list<ReflectionAttribute<object>> : list<ReflectionAttribute<TAttributeClass>>)
      * @since 8.0
      */
     #[Pure]

Reflection/Reflector.php

@@ -15,7 +15,8 @@ interface Reflector extends Stringable
      *
      * @link https://php.net/manual/en/reflector.export.php
      * @return string|null
-     * @removed 7.4
+     * @deprecated 7.4
+     * @removed 8.0
      */
     public static function export();