fix(metadata): interface breaking in 3.2 (#5883)

To ease subtree split we move the `Api` to `Metadata` namespace.

src/Api/FilterInterface.php

@@ -13,6 +13,44 @@
 
 namespace ApiPlatform\Api;
 
-interface FilterInterface extends \ApiPlatform\Metadata\FilterInterface
+/**
+ * Filters applicable on a resource.
+ *
+ * @author Kévin Dunglas <[email protected]>
+ */
+interface FilterInterface
 {
+    /**
+     * Gets the description of this filter for the given resource.
+     *
+     * Returns an array with the filter parameter names as keys and array with the following data as values:
+     *   - property: the property where the filter is applied
+     *   - type: the type of the filter
+     *   - required: if this filter is required
+     *   - strategy (optional): the used strategy
+     *   - is_collection (optional): if this filter is for collection
+     *   - swagger (optional): additional parameters for the path operation,
+     *     e.g. 'swagger' => [
+     *       'description' => 'My Description',
+     *       'name' => 'My Name',
+     *       'type' => 'integer',
+     *     ]
+     *   - openapi (optional): additional parameters for the path operation in the version 3 spec,
+     *     e.g. 'openapi' => [
+     *       'description' => 'My Description',
+     *       'name' => 'My Name',
+     *       'schema' => [
+     *          'type' => 'integer',
+     *       ]
+     *     ]
+     *   - schema (optional): schema definition,
+     *     e.g. 'schema' => [
+     *       'type' => 'string',
+     *       'enum' => ['value_1', 'value_2'],
+     *     ]
+     * The description can contain additional data specific to a filter.
+     *
+     * @see \ApiPlatform\OpenApi\Factory\OpenApiFactory::getFiltersParameters
+     */
+    public function getDescription(string $resourceClass): array;
 }

src/Api/FilterLocatorTrait.php

@@ -14,7 +14,7 @@
 namespace ApiPlatform\Api;
 
 use ApiPlatform\Exception\InvalidArgumentException;
-use ApiPlatform\Metadata\FilterInterface;
+use ApiPlatform\Metadata\FilterInterface as MetadataFilterInterface;
 use Psr\Container\ContainerInterface;
 
 /**
@@ -45,7 +45,7 @@ private function setFilterLocator(?ContainerInterface $filterLocator, bool $allo
     /**
      * Gets a filter with a backward compatibility.
      */
-    private function getFilter(string $filterId): ?FilterInterface
+    private function getFilter(string $filterId): null|FilterInterface|MetadataFilterInterface
     {
         if ($this->filterLocator && $this->filterLocator->has($filterId)) {
             return $this->filterLocator->get($filterId);

src/Api/IdentifiersExtractorInterface.php

@@ -13,15 +13,20 @@
 
 namespace ApiPlatform\Api;
 
-class_exists(\ApiPlatform\Metadata\IdentifiersExtractorInterface::class);
+use ApiPlatform\Metadata\Exception\RuntimeException;
+use ApiPlatform\Metadata\Operation;
 
-class_alias(
-    \ApiPlatform\Metadata\IdentifiersExtractorInterface::class,
-    __NAMESPACE__.'\IdentifiersExtractorInterface'
-);
-
-if (false) { // @phpstan-ignore-line
-    interface IdentifiersExtractorInterface extends \ApiPlatform\Metadata\IdentifiersExtractorInterface
-    {
-    }
+/**
+ * Extracts identifiers for a given Resource according to the retrieved Metadata.
+ *
+ * @author Antoine Bluchet <[email protected]>
+ */
+interface IdentifiersExtractorInterface
+{
+    /**
+     * Finds identifiers from an Item (object).
+     *
+     * @throws RuntimeException
+     */
+    public function getIdentifiersFromItem(object $item, Operation $operation = null, array $context = []): array;
 }

src/Api/IriConverterInterface.php

@@ -13,15 +13,33 @@
 
 namespace ApiPlatform\Api;
 
-class_exists(\ApiPlatform\Metadata\IriConverterInterface::class);
+use ApiPlatform\Metadata\Exception\InvalidArgumentException;
+use ApiPlatform\Metadata\Exception\ItemNotFoundException;
+use ApiPlatform\Metadata\Exception\RuntimeException;
+use ApiPlatform\Metadata\Operation;
 
-class_alias(
-    \ApiPlatform\Metadata\IriConverterInterface::class,
-    __NAMESPACE__.'\IriConverterInterface'
-);
+/**
+ * Converts item and resources to IRI and vice versa.
+ *
+ * @author Kévin Dunglas <[email protected]>
+ */
+interface IriConverterInterface
+{
+    /**
+     * Retrieves an item from its IRI.
+     *
+     * @throws InvalidArgumentException
+     * @throws ItemNotFoundException
+     */
+    public function getResourceFromIri(string $iri, array $context = [], Operation $operation = null): object;
 
-if (false) { // @phpstan-ignore-line
-    interface IriConverterInterface extends \ApiPlatform\Metadata\IriConverterInterface
-    {
-    }
+    /**
+     * Gets the IRI associated with the given item.
+     *
+     * @param object|class-string $resource
+     *
+     * @throws InvalidArgumentException
+     * @throws RuntimeException
+     */
+    public function getIriFromResource(object|string $resource, int $referenceType = UrlGeneratorInterface::ABS_PATH, Operation $operation = null, array $context = []): ?string;
 }

src/Api/ResourceClassResolverInterface.php

@@ -13,10 +13,27 @@
 
 namespace ApiPlatform\Api;
 
-class_exists(\ApiPlatform\Metadata\ResourceClassResolverInterface::class);
+use ApiPlatform\Metadata\Exception\InvalidArgumentException;
 
-if (false) { // @phpstan-ignore-line
-    interface ResourceClassResolverInterface extends \ApiPlatform\Metadata\ResourceClassResolverInterface
-    {
-    }
+/**
+ * Guesses which resource is associated with a given object.
+ *
+ * @author Kévin Dunglas <[email protected]>
+ */
+interface ResourceClassResolverInterface
+{
+    /**
+     * Guesses the associated resource.
+     *
+     * @param string $resourceClass The expected resource class
+     * @param bool   $strict        If true, value must match the expected resource class
+     *
+     * @throws InvalidArgumentException
+     */
+    public function getResourceClass(mixed $value, string $resourceClass = null, bool $strict = false): string;
+
+    /**
+     * Is the given class a resource class?
+     */
+    public function isResourceClass(string $type): bool;
 }

src/Api/UriVariableTransformerInterface.php

@@ -13,6 +13,27 @@
 
 namespace ApiPlatform\Api;
 
-interface UriVariableTransformerInterface extends \ApiPlatform\Metadata\UriVariableTransformerInterface
+use ApiPlatform\Exception\InvalidUriVariableException;
+
+interface UriVariableTransformerInterface
 {
+    /**
+     * 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 array $context Options available to the transformer
+     *
+     * @throws InvalidUriVariableException Occurs when the URI variable could not be transformed
+     */
+    public function transform(mixed $value, array $types, array $context = []);
+
+    /**
+     * 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 URI variable value should be transformed
+     * @param array $context Options available to the transformer
+     */
+    public function supportsTransformation(mixed $value, array $types, array $context = []): bool;
 }

src/Api/UriVariablesConverterInterface.php

@@ -13,15 +13,24 @@
 
 namespace ApiPlatform\Api;
 
-class_exists(\ApiPlatform\Metadata\UriVariablesConverterInterface::class);
+use ApiPlatform\Metadata\Exception\InvalidIdentifierException;
 
-class_alias(
-    \ApiPlatform\Metadata\UriVariablesConverterInterface::class,
-    __NAMESPACE__.'\UriVariablesConverterInterface'
-);
-
-if (false) { // @phpstan-ignore-line
-    interface UriVariablesConverterInterface extends \ApiPlatform\Metadata\UriVariablesConverterInterface
-    {
-    }
+/**
+ * Identifier converter.
+ *
+ * @author Antoine Bluchet <[email protected]>
+ */
+interface UriVariablesConverterInterface
+{
+    /**
+     * Takes an array of strings representing URI variables (identifiers) and transform their values to the expected type.
+     *
+     * @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 Array indexed by identifiers properties with their values denormalized
+     */
+    public function convert(array $data, string $class, array $context = []): array;
 }

src/Api/UrlGeneratorInterface.php

@@ -13,13 +13,72 @@
 
 namespace ApiPlatform\Api;
 
-class_alias(
-    \ApiPlatform\Metadata\UrlGeneratorInterface::class,
-    __NAMESPACE__.'\UrlGeneratorInterface'
-);
-
-if (false) { // @phpstan-ignore-line
-    interface UrlGeneratorInterface extends \ApiPlatform\Metadata\UrlGeneratorInterface
-    {
-    }
+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.
+ *
+ * This interface has been imported and adapted from the Symfony project.
+ *
+ * The constants in this interface define the different types of resource references that
+ * are declared in RFC 3986: http://tools.ietf.org/html/rfc3986
+ * We are using the term "URL" instead of "URI" as this is more common in web applications
+ * and we do not need to distinguish them as the difference is mostly semantical and
+ * less technical. Generating URIs, i.e. representation-independent resource identifiers,
+ * is also possible.
+ *
+ * @author Fabien Potencier <[email protected]>
+ * @author Tobias Schultze <http://tobion.de>
+ * @copyright Fabien Potencier
+ */
+interface UrlGeneratorInterface
+{
+    /**
+     * Generates an absolute URL, e.g. "http://example.com/dir/file".
+     */
+    public const ABS_URL = 0;
+
+    /**
+     * Generates an absolute path, e.g. "/dir/file".
+     */
+    public const ABS_PATH = 1;
+
+    /**
+     * Generates a relative path based on the current request path, e.g. "../parent-file".
+     *
+     * @see UrlGenerator::getRelativePath()
+     */
+    public const REL_PATH = 2;
+
+    /**
+     * Generates a network path, e.g. "//example.com/dir/file".
+     * Such reference reuses the current scheme but specifies the host.
+     */
+    public const NET_PATH = 3;
+
+    /**
+     * Generates a URL or path for a specific route based on the given parameters.
+     *
+     * Parameters that reference placeholders in the route pattern will substitute them in the
+     * path or host. Extra params are added as query string to the URL.
+     *
+     * When the passed reference type cannot be generated for the route because it requires a different
+     * host or scheme than the current one, the method will return a more comprehensive reference
+     * that includes the required params. For example, when you call this method with $referenceType = ABSOLUTE_PATH
+     * but the route requires the https scheme whereas the current scheme is http, it will instead return an
+     * ABSOLUTE_URL with the https scheme and the current host. This makes sure the generated URL matches
+     * the route in any case.
+     *
+     * If there is no route with the given name, the generator must throw the RouteNotFoundException.
+     *
+     * The special parameter _fragment will be used as the document fragment suffixed to the final 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(string $name, array $parameters = [], int $referenceType = self::ABS_PATH): string;
 }

src/Doctrine/Odm/Filter/SearchFilter.php

@@ -149,7 +149,7 @@ public function __construct(ManagerRegistry $managerRegistry, IriConverterInterf
         $this->propertyAccessor = $propertyAccessor ?: PropertyAccess::createPropertyAccessor();
     }
 
-    protected function getIriConverter(): IriConverterInterface
+    protected function getIriConverter(): LegacyIriConverterInterface|IriConverterInterface
     {
         return $this->iriConverter;
     }

src/Doctrine/Orm/Filter/SearchFilter.php

@@ -148,7 +148,7 @@ public function __construct(ManagerRegistry $managerRegistry, IriConverterInterf
         $this->propertyAccessor = $propertyAccessor ?: PropertyAccess::createPropertyAccessor();
     }
 
-    protected function getIriConverter(): IriConverterInterface
+    protected function getIriConverter(): IriConverterInterface|LegacyIriConverterInterface
     {
         return $this->iriConverter;
     }

src/Hydra/Serializer/CollectionFiltersNormalizer.php

@@ -13,7 +13,9 @@
 
 namespace ApiPlatform\Hydra\Serializer;
 
+use ApiPlatform\Api\FilterInterface as LegacyFilterInterface;
 use ApiPlatform\Api\FilterLocatorTrait;
+use ApiPlatform\Api\ResourceClassResolverInterface as LegacyResourceClassResolverInterface;
 use ApiPlatform\Doctrine\Odm\State\Options as ODMOptions;
 use ApiPlatform\Doctrine\Orm\State\Options;
 use ApiPlatform\Metadata\FilterInterface;
@@ -40,7 +42,7 @@ final class CollectionFiltersNormalizer implements NormalizerInterface, Normaliz
     /**
      * @param ContainerInterface $filterLocator The new filter locator or the deprecated filter collection
      */
-    public function __construct(private readonly NormalizerInterface $collectionNormalizer, private readonly ResourceMetadataCollectionFactoryInterface $resourceMetadataCollectionFactory, private readonly ResourceClassResolverInterface $resourceClassResolver, ContainerInterface $filterLocator)
+    public function __construct(private readonly NormalizerInterface $collectionNormalizer, private readonly ResourceMetadataCollectionFactoryInterface $resourceMetadataCollectionFactory, private readonly LegacyResourceClassResolverInterface|ResourceClassResolverInterface $resourceClassResolver, ContainerInterface $filterLocator)
     {
         $this->setFilterLocator($filterLocator);
     }
@@ -142,7 +144,7 @@ public function setNormalizer(NormalizerInterface $normalizer): void
     /**
      * Returns the content of the Hydra search property.
      *
-     * @param FilterInterface[] $filters
+     * @param LegacyFilterInterface[]|FilterInterface[] $filters
      */
     private function getSearch(string $resourceClass, array $parts, array $filters): array
     {