chore: better PHP types (#4886)

composer.json

@@ -53,6 +53,7 @@
         "justinrainbow/json-schema": "^5.2.1",
         "phpdocumentor/reflection-docblock": "^3.0 || ^4.0 || ^5.1",
         "phpdocumentor/type-resolver": "^0.3 || ^0.4 || ^1.4",
+        "phpspec/prophecy-phpunit": "^2.0",
         "phpstan/extension-installer": "^1.1",
         "phpstan/phpstan": "^1.1",
         "phpstan/phpstan-doctrine": "^1.0",

src/Api/IdentifiersExtractor.php

@@ -47,7 +47,7 @@ public function __construct(ResourceMetadataCollectionFactoryInterface $resource
      *
      * TODO: 3.0 identifiers should be stringable?
      */
-    public function getIdentifiersFromItem($item, Operation $operation = null, array $context = []): array
+    public function getIdentifiersFromItem(object $item, Operation $operation = null, array $context = []): array
     {
         $identifiers = [];
 
@@ -84,7 +84,7 @@ public function getIdentifiersFromItem($item, Operation $operation = null, array
     /**
      * Gets the value of the given class property.
      */
-    private function getIdentifierValue($item, string $class, string $property, string $parameterName)
+    private function getIdentifierValue(object $item, string $class, string $property, string $parameterName): float|bool|int|string
     {
         if ($item instanceof $class) {
             return $this->resolveIdentifierValue($this->propertyAccessor->getValue($item, $property), $parameterName);
@@ -124,10 +124,10 @@ private function getIdentifierValue($item, string $class, string $property, stri
      *
      * @param mixed|\Stringable $identifierValue
      */
-    private function resolveIdentifierValue($identifierValue, string $parameterName)
+    private function resolveIdentifierValue(mixed $identifierValue, string $parameterName): float|bool|int|string
     {
         if (null === $identifierValue) {
-            throw new RuntimeException('No identifier value found, did you forgot to persist the entity?');
+            throw new RuntimeException('No identifier value found, did you forget to persist the entity?');
         }
 
         if (\is_scalar($identifierValue)) {

src/Api/IdentifiersExtractorInterface.php

@@ -26,9 +26,7 @@ interface IdentifiersExtractorInterface
     /**
      * Finds identifiers from an Item (object).
      *
-     * @param object $item
-     *
      * @throws RuntimeException
      */
-    public function getIdentifiersFromItem($item, ?Operation $operation = null, array $context = []): array;
+    public function getIdentifiersFromItem(object $item, ?Operation $operation = null, array $context = []): array;
 }

src/Api/IriConverterInterface.php

@@ -30,10 +30,8 @@ interface IriConverterInterface
      *
      * @throws InvalidArgumentException
      * @throws ItemNotFoundException
-     *
-     * @return object
      */
-    public function getResourceFromIri(string $iri, array $context = [], ?Operation $operation = null);
+    public function getResourceFromIri(string $iri, array $context = [], ?Operation $operation = null): object;
 
     /**
      * Gets the IRI associated with the given item.
@@ -43,5 +41,5 @@ public function getResourceFromIri(string $iri, array $context = [], ?Operation
      * @throws InvalidArgumentException
      * @throws RuntimeException
      */
-    public function getIriFromResource($resource, int $referenceType = UrlGeneratorInterface::ABS_PATH, ?Operation $operation = null, array $context = []): ?string;
+    public function getIriFromResource(object|string $resource, int $referenceType = UrlGeneratorInterface::ABS_PATH, ?Operation $operation = null, array $context = []): ?string;
 }

src/Api/QueryParameterValidator/QueryParameterValidator.php

@@ -33,7 +33,7 @@ class QueryParameterValidator
 {
     use FilterLocatorTrait;
 
-    private $validators;
+    private array $validators;
 
     public function __construct(ContainerInterface $filterLocator)
     {

src/Api/ResourceClassResolver.php

@@ -36,7 +36,7 @@ public function __construct(private readonly ResourceNameCollectionFactoryInterf
     /**
      * {@inheritdoc}
      */
-    public function getResourceClass($value, string $resourceClass = null, bool $strict = false): string
+    public function getResourceClass(mixed $value, string $resourceClass = null, bool $strict = false): string
     {
         if ($strict && null === $resourceClass) {
             throw new InvalidArgumentException('Strict checking is only possible when resource class is specified.');

src/Api/ResourceClassResolverInterface.php

@@ -30,7 +30,7 @@ interface ResourceClassResolverInterface
      *
      * @throws InvalidArgumentException
      */
-    public function getResourceClass($value, string $resourceClass = null, bool $strict = false): string;
+    public function getResourceClass(mixed $value, string $resourceClass = null, bool $strict = false): string;
 
     /**
      * Is the given class a resource class?

src/Api/UriVariableTransformer/DateTimeUriVariableTransformer.php

@@ -27,7 +27,7 @@ public function __construct()
         $this->dateTimeNormalizer = new DateTimeNormalizer();
     }
 
-    public function transform($value, array $types, array $context = [])
+    public function transform(mixed $value, array $types, array $context = []): \DateTimeInterface
     {
         try {
             return $this->dateTimeNormalizer->denormalize($value, $types[0], null, $context);
@@ -36,7 +36,7 @@ public function transform($value, array $types, array $context = [])
         }
     }
 
-    public function supportsTransformation($value, array $types, array $context = []): bool
+    public function supportsTransformation(mixed $value, array $types, array $context = []): bool
     {
         return $this->dateTimeNormalizer->supportsDenormalization($value, $types[0]);
     }

src/Api/UriVariableTransformer/IntegerUriVariableTransformer.php

@@ -18,12 +18,12 @@
 
 final class IntegerUriVariableTransformer implements UriVariableTransformerInterface
 {
-    public function transform($value, array $types, array $context = [])
+    public function transform(mixed $value, array $types, array $context = []): int
     {
         return (int) $value;
     }
 
-    public function supportsTransformation($value, array $types, array $context = []): bool
+    public function supportsTransformation(mixed $value, array $types, array $context = []): bool
     {
         return Type::BUILTIN_TYPE_INT === $types[0] && \is_string($value);
     }

src/Api/UriVariableTransformerInterface.php

@@ -18,22 +18,22 @@
 interface UriVariableTransformerInterface
 {
     /**
-     * Denormalizes data back into an object of the given class.
+     * Transforms the value of a URI variable (identifier) to its type.
      *
-     * @param mixed $value   The uri variable value to transform
-     * @param array $types   The guessed type behind the uri variable
+     * @param mixed $value   The URI variable value to transform
+     * @param array $types   The guessed type behind the URI variable
      * @param array $context Options available to the transformer
      *
-     * @throws InvalidUriVariableException Occurs when the uriVariable could not be transformed
+     * @throws InvalidUriVariableException Occurs when the URI variable could not be transformed
      */
-    public function transform($value, array $types, array $context = []);
+    public function transform(mixed $value, array $types, array $context = []);
 
     /**
-     * Checks whether the given class is supported for denormalization by this normalizer.
+     * Checks whether the value of a URI variable can be transformed to its type by this transformer.
      *
-     * @param mixed $value   The uri variable value to transform
-     * @param array $types   The types to which the data should be transformed
+     * @param mixed $value   The URI variable value to transform
+     * @param array $types   The types to which the URI variable value should be transformed
      * @param array $context Options available to the transformer
      */
-    public function supportsTransformation($value, array $types, array $context = []): bool;
+    public function supportsTransformation(mixed $value, array $types, array $context = []): bool;
 }

src/Api/UriVariablesConverter.php

@@ -39,7 +39,7 @@ public function __construct(private readonly PropertyMetadataFactoryInterface $p
     public function convert(array $uriVariables, string $class, array $context = []): array
     {
         $operation = $context['operation'] ?? $this->resourceMetadataCollectionFactory->create($class)->getOperation();
-        $context = $context + ['operation' => $operation];
+        $context += ['operation' => $operation];
         $uriVariablesDefinitions = $operation->getUriVariables() ?? [];
 
         foreach ($uriVariables as $parameterName => $value) {

src/Api/UriVariablesConverterInterface.php

@@ -23,14 +23,14 @@
 interface UriVariablesConverterInterface
 {
     /**
-     * Takes an array of strings representing identifiers and transform their values to the expected type.
+     * Takes an array of strings representing URI variables (identifiers) and transform their values to the expected type.
      *
-     * @param array  $data  Identifier to convert to php values
-     * @param string $class The class to which the identifiers belong to
+     * @param array  $data  URI variables to convert to PHP values
+     * @param string $class The class to which the URI variables belong to
      *
      * @throws InvalidIdentifierException
      *
-     * @return array indexed by identifiers properties with their values denormalized
+     * @return array Array indexed by identifiers properties with their values denormalized
      */
     public function convert(array $data, string $class, array $context = []): array;
 }

src/Api/UrlGeneratorInterface.php

@@ -13,6 +13,10 @@
 
 namespace ApiPlatform\Api;
 
+use Symfony\Component\Routing\Exception\InvalidParameterException;
+use Symfony\Component\Routing\Exception\MissingMandatoryParametersException;
+use Symfony\Component\Routing\Exception\RouteNotFoundException;
+
 /**
  * UrlGeneratorInterface is the interface that all URL generator classes must implement.
  *
@@ -69,11 +73,12 @@ interface UrlGeneratorInterface
      *
      * If there is no route with the given name, the generator must throw the RouteNotFoundException.
      *
-     * @param string $name          The name of the route
-     * @param mixed  $parameters    An array of parameters
-     * @param int    $referenceType The type of reference to be generated (one of the constants)
+     * The special parameter _fragment will be used as the document fragment suffixed to the final URL.
      *
-     * @return string The generated URL
+     * @throws RouteNotFoundException              If the named route doesn't exist
+     * @throws MissingMandatoryParametersException When some parameters are missing that are mandatory for the route
+     * @throws InvalidParameterException           When a parameter value for a placeholder is not correct because
+     *                                             it does not match the requirement
      */
-    public function generate($name, $parameters = [], $referenceType = self::ABS_PATH);
+    public function generate(string $name, array $parameters = [], int $referenceType = self::ABS_PATH): string;
 }

src/Doctrine/Common/Filter/BooleanFilterTrait.php

@@ -65,7 +65,7 @@ abstract protected function getProperties(): ?array;
 
     abstract protected function getLogger(): LoggerInterface;
 
-    abstract protected function normalizePropertyName($property): string;
+    abstract protected function normalizePropertyName(string $property): string;
 
     /**
      * Determines whether the given property refers to a boolean field.

src/Doctrine/Common/Filter/DateFilterTrait.php

@@ -55,7 +55,7 @@ public function getDescription(string $resourceClass): array
 
     abstract protected function getProperties(): ?array;
 
-    abstract protected function normalizePropertyName($property): string;
+    abstract protected function normalizePropertyName(string $property): string;
 
     /**
      * Determines whether the given property refers to a date field.

src/Doctrine/Common/Filter/ExistsFilterTrait.php

@@ -68,7 +68,7 @@ abstract protected function getProperties(): ?array;
 
     abstract protected function getLogger(): LoggerInterface;
 
-    abstract protected function normalizePropertyName($property): string;
+    abstract protected function normalizePropertyName(string $property): string;
 
     private function normalizeValue($value, string $property): ?bool
     {

src/Doctrine/Common/Filter/NumericFilterTrait.php

@@ -69,7 +69,7 @@ abstract protected function getProperties(): ?array;
 
     abstract protected function getLogger(): LoggerInterface;
 
-    abstract protected function normalizePropertyName($property): string;
+    abstract protected function normalizePropertyName(string $property): string;
 
     /**
      * Determines whether the given property refers to a numeric field.

src/Doctrine/Common/Filter/OrderFilterTrait.php

@@ -67,7 +67,7 @@ public function getDescription(string $resourceClass): array
 
     abstract protected function getProperties(): ?array;
 
-    abstract protected function normalizePropertyName($property): string;
+    abstract protected function normalizePropertyName(string $property): string;
 
     private function normalizeValue($value, string $property): ?string
     {

src/Doctrine/Common/Filter/RangeFilterTrait.php

@@ -58,7 +58,7 @@ abstract protected function getProperties(): ?array;
 
     abstract protected function getLogger(): LoggerInterface;
 
-    abstract protected function normalizePropertyName($property): string;
+    abstract protected function normalizePropertyName(string $property): string;
 
     /**
      * Gets filter description.
@@ -123,10 +123,8 @@ private function normalizeBetweenValues(array $values): ?array
 
     /**
      * Normalize the value.
-     *
-     * @return int|float|null
      */
-    private function normalizeValue(string $value, string $operator)
+    private function normalizeValue(string $value, string $operator): float|int|null
     {
         if (!is_numeric($value)) {
             $this->getLogger()->notice('Invalid filter ignored', [

src/Doctrine/Common/Filter/SearchFilterTrait.php

@@ -113,12 +113,12 @@ abstract protected function getIriConverter(): IriConverterInterface;
 
     abstract protected function getPropertyAccessor(): PropertyAccessorInterface;
 
-    abstract protected function normalizePropertyName($property): string;
+    abstract protected function normalizePropertyName(string $property): string;
 
     /**
      * Gets the ID from an IRI or a raw ID.
      */
-    protected function getIdFromValue(string $value)
+    protected function getIdFromValue(string $value): mixed
     {
         try {
             $iriConverter = $this->getIriConverter();
@@ -156,12 +156,10 @@ protected function normalizeValues(array $values, string $property): ?array
 
     /**
      * When the field should be an integer, check that the given value is a valid one.
-     *
-     * @param mixed|null $type
      */
-    protected function hasValidValues(array $values, $type = null): bool
+    protected function hasValidValues(array $values, ?string $type = null): bool
     {
-        foreach ($values as $key => $value) {
+        foreach ($values as $value) {
             if (null !== $value && \in_array($type, (array) self::DOCTRINE_INTEGER_TYPE, true) && false === filter_var($value, \FILTER_VALIDATE_INT)) {
                 return false;
             }

src/Doctrine/Common/PropertyHelperTrait.php

@@ -13,7 +13,6 @@
 
 namespace ApiPlatform\Doctrine\Common;
 
-use Doctrine\DBAL\Types\Type;
 use Doctrine\Persistence\ManagerRegistry;
 use Doctrine\Persistence\Mapping\ClassMetadata;
 
@@ -98,10 +97,8 @@ protected function splitPropertyParts(string $property, string $resourceClass):
 
     /**
      * Gets the Doctrine Type of a given property/resourceClass.
-     *
-     * @return Type|string|null
      */
-    protected function getDoctrineFieldType(string $property, string $resourceClass)
+    protected function getDoctrineFieldType(string $property, string $resourceClass): ?string
     {
         $propertyParts = $this->splitPropertyParts($property, $resourceClass);
         $metadata = $this->getNestedMetadata($resourceClass, $propertyParts['associations']);

src/Doctrine/Common/State/LinksHandlerTrait.php

@@ -74,7 +74,7 @@ private function getLinks(string $resourceClass, Operation $operation, array $co
         return $newLinks;
     }
 
-    private function getIdentifierValue(array &$identifiers, string $name = null)
+    private function getIdentifierValue(array &$identifiers, string $name = null): mixed
     {
         if (isset($identifiers[$name])) {
             $value = $identifiers[$name];

src/Doctrine/Common/State/PersistProcessor.php

@@ -29,7 +29,14 @@ public function __construct(private readonly ManagerRegistry $managerRegistry)
     {
     }
 
-    public function process($data, Operation $operation, array $uriVariables = [], array $context = [])
+    /**
+     * @template T
+     *
+     * @param T $data
+     *
+     * @return T
+     */
+    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): mixed
     {
         if (!$manager = $this->getManager($data)) {
             return $data;

src/Doctrine/Common/State/RemoveProcessor.php

@@ -27,7 +27,7 @@ public function __construct(private readonly ManagerRegistry $managerRegistry)
     {
     }
 
-    public function process($data, Operation $operation, array $uriVariables = [], array $context = []): void
+    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): void
     {
         if (!$manager = $this->getManager($data)) {
             return;