chore: better PHP types (#4886)

Author: alanpoulain

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;
 }