feat(metadata): attribute Parameter (#6246)

api-platform · Mar 26, 2024 · 3ad3836 · 3ad3836
1 parent 3cbef6a
commit 3ad3836
Show file tree

Hide file tree

Showing 43 changed files with 1,004 additions and 43 deletions.
diff --git a/src/Metadata/ApiFilter.php b/src/Metadata/ApiFilter.php
@@ -26,13 +26,15 @@ final class ApiFilter
 {
     /**
      * @param string|class-string<FilterInterface>|class-string<LegacyFilterInterface> $filterClass
+     * @param string                                                                   $alias       a filter tag alias to be referenced in a Parameter
      */
     public function __construct(
         public string $filterClass,
         public ?string $id = null,
         public ?string $strategy = null,
         public array $properties = [],
         public array $arguments = [],
+        public ?string $alias = null,
     ) {
         if (!is_a($this->filterClass, FilterInterface::class, true) && !is_a($this->filterClass, LegacyFilterInterface::class, true)) {
             throw new InvalidArgumentException(sprintf('The filter class "%s" does not implement "%s". Did you forget a use statement?', $this->filterClass, FilterInterface::class));

diff --git a/src/Metadata/ApiResource.php b/src/Metadata/ApiResource.php
@@ -960,6 +960,7 @@ public function __construct(
         $provider = null,
         $processor = null,
         protected ?OptionsInterface $stateOptions = null,
+        protected array|Parameters|null $parameters = null,
         protected array $extraProperties = [],
     ) {
         parent::__construct(
@@ -1000,6 +1001,7 @@ class: $class,
             provider: $provider,
             processor: $processor,
             stateOptions: $stateOptions,
+            parameters: $parameters,
             extraProperties: $extraProperties
         );
 

diff --git a/src/Metadata/Delete.php b/src/Metadata/Delete.php
@@ -94,6 +94,7 @@ public function __construct(
         $provider = null,
         $processor = null,
         ?OptionsInterface $stateOptions = null,
+        array|Parameters|null $parameters = null,
         array $extraProperties = [],
     ) {
         parent::__construct(
@@ -170,6 +171,7 @@ class: $class,
             processor: $processor,
             extraProperties: $extraProperties,
             collectDenormalizationErrors: $collectDenormalizationErrors,
+            parameters: $parameters,
             stateOptions: $stateOptions,
         );
     }

diff --git a/src/Metadata/Extractor/XmlResourceExtractor.php b/src/Metadata/Extractor/XmlResourceExtractor.php
@@ -15,11 +15,13 @@
 
 use ApiPlatform\Metadata\Exception\InvalidArgumentException;
 use ApiPlatform\Metadata\GetCollection;
+use ApiPlatform\Metadata\HeaderParameter;
 use ApiPlatform\Metadata\Post;
+use ApiPlatform\Metadata\QueryParameter;
 use ApiPlatform\Metadata\Tests\Fixtures\StateOptions;
 use ApiPlatform\OpenApi\Model\ExternalDocumentation;
 use ApiPlatform\OpenApi\Model\Operation as OpenApiOperation;
-use ApiPlatform\OpenApi\Model\Parameter;
+use ApiPlatform\OpenApi\Model\Parameter as OpenApiParameter;
 use ApiPlatform\OpenApi\Model\RequestBody;
 use ApiPlatform\State\OptionsInterface;
 use Symfony\Component\Config\Util\XmlUtils;
@@ -97,6 +99,7 @@ private function buildExtendedBase(\SimpleXMLElement $resource): array
             'stateOptions' => $this->buildStateOptions($resource),
             'links' => $this->buildLinks($resource),
             'headers' => $this->buildHeaders($resource),
+            'parameters' => $this->buildParameters($resource),
         ]);
     }
 
@@ -200,7 +203,7 @@ private function buildOpenapi(\SimpleXMLElement $resource): bool|OpenApiOperatio
 
         if (isset($openapi->parameters->parameter)) {
             foreach ($openapi->parameters->parameter as $parameter) {
-                $data['parameters'][(string) $parameter->attributes()->name] = new Parameter(
+                $data['parameters'][(string) $parameter->attributes()->name] = new OpenApiParameter(
                     name: $this->phpize($parameter, 'name', 'string'),
                     in: $this->phpize($parameter, 'in', 'string'),
                     description: $this->phpize($parameter, 'description', 'string'),
@@ -494,4 +497,48 @@ private function buildHeaders(\SimpleXMLElement $resource): ?array
 
         return $headers;
     }
+
+    /**
+     * @return array<string, \ApiPlatform\Metadata\Parameter>
+     */
+    private function buildParameters(\SimpleXMLElement $resource): ?array
+    {
+        if (!$resource->parameters) {
+            return null;
+        }
+
+        $parameters = [];
+        foreach ($resource->parameters->parameter as $parameter) {
+            $key = (string) $parameter->attributes()->key;
+            $cl = ('header' === (string) $parameter->attributes()->in) ? HeaderParameter::class : QueryParameter::class;
+            $parameters[$key] = new $cl(
+                key: $key,
+                required: $this->phpize($parameter, 'required', 'bool'),
+                schema: isset($parameter->schema->values) ? $this->buildValues($parameter->schema->values) : null,
+                openApi: isset($parameter->openapi) ? new OpenApiParameter(
+                    name: $this->phpize($parameter->openapi, 'name', 'string'),
+                    in: $this->phpize($parameter->openapi, 'in', 'string'),
+                    description: $this->phpize($parameter->openapi, 'description', 'string'),
+                    required: $this->phpize($parameter->openapi, 'required', 'bool'),
+                    deprecated: $this->phpize($parameter->openapi, 'deprecated', 'bool'),
+                    allowEmptyValue: $this->phpize($parameter->openapi, 'allowEmptyValue', 'bool'),
+                    schema: isset($parameter->openapi->schema->values) ? $this->buildValues($parameter->openapi->schema->values) : null,
+                    style: $this->phpize($parameter->openapi, 'style', 'string'),
+                    explode: $this->phpize($parameter->openapi, 'explode', 'bool'),
+                    allowReserved: $this->phpize($parameter->openapi, 'allowReserved', 'bool'),
+                    example: $this->phpize($parameter->openapi, 'example', 'string'),
+                    examples: isset($parameter->openapi->examples->values) ? new \ArrayObject($this->buildValues($parameter->openapi->examples->values)) : null,
+                    content: isset($parameter->openapi->content->values) ? new \ArrayObject($this->buildValues($parameter->openapi->content->values)) : null,
+                ) : null,
+                provider: $this->phpize($parameter, 'provider', 'string'),
+                filter: $this->phpize($parameter, 'filter', 'string'),
+                property: $this->phpize($parameter, 'property', 'string'),
+                description: $this->phpize($parameter, 'description', 'string'),
+                priority: $this->phpize($parameter, 'priority', 'integer'),
+                extraProperties: $this->buildExtraProperties($parameter, 'extraProperties') ?? [],
+            );
+        }
+
+        return $parameters;
+    }
 }
diff --git a/src/Metadata/Extractor/YamlResourceExtractor.php b/src/Metadata/Extractor/YamlResourceExtractor.php
@@ -15,7 +15,9 @@
 
 use ApiPlatform\Metadata\Exception\InvalidArgumentException;
 use ApiPlatform\Metadata\GetCollection;
+use ApiPlatform\Metadata\HeaderParameter;
 use ApiPlatform\Metadata\Post;
+use ApiPlatform\Metadata\QueryParameter;
 use ApiPlatform\Metadata\Tests\Fixtures\StateOptions;
 use ApiPlatform\OpenApi\Model\ExternalDocumentation;
 use ApiPlatform\OpenApi\Model\Operation as OpenApiOperation;
@@ -124,6 +126,7 @@ private function buildExtendedBase(array $resource): array
             'stateOptions' => $this->buildStateOptions($resource),
             'links' => $this->buildLinks($resource),
             'headers' => $this->buildHeaders($resource),
+            'parameters' => $this->buildParameters($resource),
         ]);
     }
 
@@ -450,4 +453,47 @@ private function buildHeaders(array $resource): ?array
 
         return $headers;
     }
+
+    /**
+     * @return array<string, \ApiPlatform\Metadata\Parameter>
+     */
+    private function buildParameters(array $resource): ?array
+    {
+        if (!isset($resource['parameters']) || !\is_array($resource['parameters'])) {
+            return null;
+        }
+
+        $parameters = [];
+        foreach ($resource['parameters'] as $key => $parameter) {
+            $cl = ($parameter['in'] ?? 'query') === 'header' ? HeaderParameter::class : QueryParameter::class;
+            $parameters[$key] = new $cl(
+                key: $key,
+                required: $this->phpize($parameter, 'required', 'bool'),
+                schema: $parameter['schema'],
+                openApi: ($parameter['openapi'] ?? null) ? new Parameter(
+                    name: $parameter['openapi']['name'],
+                    in: $parameter['in'] ?? 'query',
+                    description: $parameter['openapi']['description'] ?? '',
+                    required: $parameter['openapi']['required'] ?? $parameter['required'] ?? false,
+                    deprecated: $parameter['openapi']['deprecated'] ?? false,
+                    allowEmptyValue: $parameter['openapi']['allowEmptyValue'] ?? false,
+                    schema: $parameter['openapi']['schema'] ?? $parameter['schema'] ?? [],
+                    style: $parameter['openapi']['style'] ?? null,
+                    explode: $parameter['openapi']['explode'] ?? false,
+                    allowReserved: $parameter['openapi']['allowReserved '] ?? false,
+                    example: $parameter['openapi']['example'] ?? null,
+                    examples: isset($parameter['openapi']['examples']) ? new \ArrayObject($parameter['openapi']['examples']) : null,
+                    content: isset($parameter['openapi']['content']) ? new \ArrayObject($parameter['openapi']['content']) : null
+                ) : null,
+                provider: $this->phpize($parameter, 'provider', 'string'),
+                filter: $this->phpize($parameter, 'filter', 'string'),
+                property: $this->phpize($parameter, 'property', 'string'),
+                description: $this->phpize($parameter, 'description', 'string'),
+                priority: $this->phpize($parameter, 'priority', 'integer'),
+                extraProperties: $this->buildArrayValue($parameter, 'extraProperties') ?? [],
+            );
+        }
+
+        return $parameters;
+    }
 }
diff --git a/src/Metadata/Extractor/schema/resources.xsd b/src/Metadata/Extractor/schema/resources.xsd
@@ -433,6 +433,29 @@
         </xsd:sequence>
     </xsd:group>
 
+    <xsd:element name="parameter">
+        <xsd:complexType>
+            <xsd:sequence maxOccurs="unbounded">
+                <xsd:element name="openApi" minOccurs="0" type="openApiOperation"/>
+                <xsd:element name="schema" minOccurs="0" type="sequenceWithValues"/>
+                <xsd:element name="extraProperties" minOccurs="0" type="sequenceWithValues"/>
+            </xsd:sequence>
+            <xsd:attribute type="xsd:string" name="key" use="required"/>
+            <xsd:attribute type="xsd:string" name="in"/>
+            <xsd:attribute type="xsd:string" name="provider"/>
+            <xsd:attribute type="xsd:string" name="filter"/>
+            <xsd:attribute type="xsd:string" name="property"/>
+            <xsd:attribute type="xsd:string" name="description"/>
+            <xsd:attribute type="xsd:boolean" name="required"/>
+        </xsd:complexType>
+    </xsd:element>
+
+    <xsd:complexType name="parameters">
+        <xsd:sequence maxOccurs="unbounded">
+            <xsd:element ref="parameter"/>
+        </xsd:sequence>
+    </xsd:complexType>
+
     <xsd:group name="extendedBase">
         <xsd:sequence>
             <xsd:group ref="base"/>
@@ -444,6 +467,7 @@
             <xsd:element name="inputFormats" minOccurs="0" type="formats"/>
             <xsd:element name="openapiContext" minOccurs="0" type="sequenceWithValues"/> <!-- TODO Remove in 4.0 -->
             <xsd:element name="openapi" minOccurs="0" type="openApiOperation"/>
+            <xsd:element name="parameters" minOccurs="0" type="parameters"/>
             <xsd:element name="options" minOccurs="0" type="sequenceWithValues"/>
             <xsd:element name="outputFormats" minOccurs="0" type="formats"/>
             <xsd:element name="paginationViaCursor" minOccurs="0" type="paginationViaCursor"/>

diff --git a/src/Metadata/FilterInterface.php b/src/Metadata/FilterInterface.php
@@ -63,6 +63,8 @@ interface FilterInterface
          * The description can contain additional data specific to a filter.
          *
          * @see \ApiPlatform\OpenApi\Factory\OpenApiFactory::getFiltersParameters
+         *
+         * @return array<string, array{property: string, type: string, required: bool, strategy: string, is_collection: bool, openapi: array<string, mixed>, schema: array<string, mixed>}>
          */
         public function getDescription(string $resourceClass): array;
     }

diff --git a/src/Metadata/Get.php b/src/Metadata/Get.php
@@ -94,6 +94,7 @@ public function __construct(
         $provider = null,
         $processor = null,
         ?OptionsInterface $stateOptions = null,
+        array|Parameters|null $parameters = null,
         array $extraProperties = [],
     ) {
         parent::__construct(
@@ -169,6 +170,7 @@ class: $class,
             provider: $provider,
             processor: $processor,
             stateOptions: $stateOptions,
+            parameters: $parameters,
             extraProperties: $extraProperties,
         );
     }

diff --git a/src/Metadata/GetCollection.php b/src/Metadata/GetCollection.php
@@ -94,6 +94,7 @@ public function __construct(
         $provider = null,
         $processor = null,
         ?OptionsInterface $stateOptions = null,
+        array|Parameters|null $parameters = null,
         array $extraProperties = [],
         private ?string $itemUriTemplate = null,
     ) {
@@ -169,6 +170,7 @@ class: $class,
             name: $name,
             provider: $provider,
             processor: $processor,
+            parameters: $parameters,
             extraProperties: $extraProperties,
             stateOptions: $stateOptions,
         );

diff --git a/src/Metadata/GraphQl/Operation.php b/src/Metadata/GraphQl/Operation.php
@@ -15,6 +15,7 @@
 
 use ApiPlatform\Metadata\Link;
 use ApiPlatform\Metadata\Operation as AbstractOperation;
+use ApiPlatform\Metadata\Parameters;
 use ApiPlatform\State\OptionsInterface;
 
 class Operation extends AbstractOperation
@@ -84,6 +85,7 @@ public function __construct(
         $provider = null,
         $processor = null,
         ?OptionsInterface $stateOptions = null,
+        array|Parameters|null $parameters = null,
         array $extraProperties = []
     ) {
         parent::__construct(
@@ -131,6 +133,7 @@ class: $class,
             provider: $provider,
             processor: $processor,
             stateOptions: $stateOptions,
+            parameters: $parameters,
             extraProperties: $extraProperties
         );
     }

diff --git a/src/Metadata/GraphQl/Query.php b/src/Metadata/GraphQl/Query.php
@@ -13,6 +13,7 @@
 
 namespace ApiPlatform\Metadata\GraphQl;
 
+use ApiPlatform\Metadata\Parameters;
 use ApiPlatform\State\OptionsInterface;
 
 #[\Attribute(\Attribute::TARGET_CLASS | \Attribute::IS_REPEATABLE)]
@@ -68,6 +69,7 @@ public function __construct(
         $provider = null,
         $processor = null,
         ?OptionsInterface $stateOptions = null,
+        array|Parameters|null $parameters = null,
         array $extraProperties = [],
 
         protected ?bool $nested = null,
@@ -121,6 +123,7 @@ class: $class,
             provider: $provider,
             processor: $processor,
             stateOptions: $stateOptions,
+            parameters: $parameters,
             extraProperties: $extraProperties
         );
     }

diff --git a/src/Metadata/GraphQl/QueryCollection.php b/src/Metadata/GraphQl/QueryCollection.php
@@ -14,6 +14,7 @@
 namespace ApiPlatform\Metadata\GraphQl;
 
 use ApiPlatform\Metadata\CollectionOperationInterface;
+use ApiPlatform\Metadata\Parameters;
 use ApiPlatform\State\OptionsInterface;
 
 #[\Attribute(\Attribute::TARGET_CLASS | \Attribute::IS_REPEATABLE)]
@@ -69,6 +70,7 @@ public function __construct(
         $provider = null,
         $processor = null,
         protected ?OptionsInterface $stateOptions = null,
+        array|Parameters|null $parameters = null,
         array $extraProperties = [],
 
         ?bool $nested = null,
@@ -121,6 +123,7 @@ class: $class,
             name: $name ?: 'collection_query',
             provider: $provider,
             processor: $processor,
+            parameters: $parameters,
             extraProperties: $extraProperties,
             nested: $nested,
         );

diff --git a/src/Metadata/GraphQl/Subscription.php b/src/Metadata/GraphQl/Subscription.php
@@ -13,6 +13,7 @@
 
 namespace ApiPlatform\Metadata\GraphQl;
 
+use ApiPlatform\Metadata\Parameters;
 use ApiPlatform\State\OptionsInterface;
 
 #[\Attribute(\Attribute::TARGET_CLASS | \Attribute::IS_REPEATABLE)]
@@ -68,6 +69,7 @@ public function __construct(
         $provider = null,
         $processor = null,
         ?OptionsInterface $stateOptions = null,
+        array|Parameters|null $parameters = null,
         array $extraProperties = [],
     ) {
         parent::__construct(
@@ -119,6 +121,7 @@ class: $class,
             provider: $provider,
             processor: $processor,
             stateOptions: $stateOptions,
+            parameters: $parameters,
             extraProperties: $extraProperties,
         );
     }

diff --git a/src/Metadata/HeaderParameter.php b/src/Metadata/HeaderParameter.php
@@ -0,0 +1,22 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace ApiPlatform\Metadata;
+
+/**
+ * @experimental
+ */
+#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::IS_REPEATABLE)]
+class HeaderParameter extends Parameter implements HeaderParameterInterface
+{
+}