feat(metadata): headers configuration

features/main/headers.feature

@@ -6,3 +6,9 @@ Feature: Headers addition
     When I send a "GET" request to "/dummy_cars"
     Then the response status code should be 200
     And the header "Sunset" should be equal to "Sat, 01 Jan 2050 00:00:00 +0000"
+
+  Scenario: Declare headers from resource
+    When I send a "GET" request to "/redirect_to_foobar"
+    Then the response status code should be 301
+    And the header "Location" should be equal to "/foobar"
+    And the header "Hello" should be equal to "World"

src/Metadata/ApiResource.php

@@ -38,6 +38,7 @@ class ApiResource extends Metadata
     /**
      * @param array<int, HttpOperation>|array<string, HttpOperation>|Operations|null $operations   Operations is a list of HttpOperation
      * @param array<string, Link>|array<string, mixed[]>|string[]|string|null        $uriVariables
+     * @param array<string, string>                                                  $headers
      * @param string|callable|null                                                   $provider
      * @param string|callable|null                                                   $processor
      * @param mixed|null                                                             $mercure
@@ -314,6 +315,7 @@ public function __construct(
          * - With GraphQL, the [`isDeprecated` and `deprecationReason` properties](https://facebook.github.io/graphql/June2018/#sec-Deprecation) will be added to the schema
          */
         protected ?string $deprecationReason = null,
+        protected ?array $headers = null,
         protected ?array $cacheHeaders = null,
         protected ?array $normalizationContext = null,
         protected ?array $denormalizationContext = null,
@@ -1280,6 +1282,19 @@ public function withController(string $controller): self
         return $self;
     }
 
+    public function getHeaders(): ?array
+    {
+        return $this->headers;
+    }
+
+    public function withHeaders(array $headers): self
+    {
+        $self = clone $this;
+        $self->headers = $headers;
+
+        return $self;
+    }
+
     public function getCacheHeaders(): ?array
     {
         return $this->cacheHeaders;

src/Metadata/Delete.php

@@ -39,6 +39,7 @@ public function __construct(
         array $schemes = null,
         string $condition = null,
         string $controller = null,
+        array $headers = null,
         array $cacheHeaders = null,
         array $paginationViaCursor = null,
         array $hydraContext = null,
@@ -115,6 +116,7 @@ public function __construct(
             schemes: $schemes,
             condition: $condition,
             controller: $controller,
+            headers: $headers,
             cacheHeaders: $cacheHeaders,
             paginationViaCursor: $paginationViaCursor,
             hydraContext: $hydraContext,

src/Metadata/Error.php

@@ -39,6 +39,7 @@ public function __construct(
         array $schemes = null,
         string $condition = null,
         string $controller = null,
+        array $headers = null,
         array $cacheHeaders = null,
         array $paginationViaCursor = null,
         array $hydraContext = null,
@@ -114,6 +115,7 @@ public function __construct(
             schemes: $schemes,
             condition: $condition,
             controller: $controller,
+            headers: $headers,
             cacheHeaders: $cacheHeaders,
             paginationViaCursor: $paginationViaCursor,
             hydraContext: $hydraContext,

src/Metadata/Extractor/XmlResourceExtractor.php

@@ -96,6 +96,7 @@ private function buildExtendedBase(\SimpleXMLElement $resource): array
             'queryParameterValidationEnabled' => $this->phpize($resource, 'queryParameterValidationEnabled', 'bool'),
             'stateOptions' => $this->buildStateOptions($resource),
             'links' => $this->buildLinks($resource),
+            'headers' => $this->buildHeaders($resource),
         ]);
     }
 
@@ -465,7 +466,6 @@ private function buildStateOptions(\SimpleXMLElement $resource): ?OptionsInterfa
      */
     private function buildLinks(\SimpleXMLElement $resource): ?array
     {
-        $links = $resource->links ?? null;
         if (!$resource->links) {
             return null;
         }
@@ -477,4 +477,21 @@ private function buildLinks(\SimpleXMLElement $resource): ?array
 
         return $links;
     }
+
+    /**
+     * @return array<string, string>
+     */
+    private function buildHeaders(\SimpleXMLElement $resource): ?array
+    {
+        if (!$resource->headers) {
+            return null;
+        }
+
+        $headers = [];
+        foreach ($resource->headers as $header) {
+            $headers[(string) $header->header->attributes()->key] = (string) $header->header->attributes()->value;
+        }
+
+        return $headers;
+    }
 }

src/Metadata/Extractor/YamlResourceExtractor.php

@@ -123,6 +123,7 @@ private function buildExtendedBase(array $resource): array
             'outputFormats' => $this->buildArrayValue($resource, 'outputFormats'),
             'stateOptions' => $this->buildStateOptions($resource),
             'links' => $this->buildLinks($resource),
+            'headers' => $this->buildHeaders($resource),
         ]);
     }
 
@@ -432,4 +433,21 @@ private function buildLinks(array $resource): ?array
 
         return $links;
     }
+
+    /**
+     * @return array<string, string>
+     */
+    private function buildHeaders(array $resource): ?array
+    {
+        if (!isset($resource['headers']) || !\is_array($resource['headers'])) {
+            return null;
+        }
+
+        $headers = [];
+        foreach ($resource['headers'] as $key => $value) {
+            $headers[$key] = $value;
+        }
+
+        return $headers;
+    }
 }

src/Metadata/Extractor/schema/resources.xsd

@@ -407,6 +407,19 @@
         </xsd:sequence>
     </xsd:complexType>
 
+    <xsd:element name="header">
+        <xsd:complexType>
+            <xsd:attribute name="key" type="xsd:string"/>
+            <xsd:attribute name="value" type="xsd:string"/>
+        </xsd:complexType>
+    </xsd:element>
+
+    <xsd:complexType name="headers">
+        <xsd:sequence>
+            <xsd:element ref="header"/>
+        </xsd:sequence>
+    </xsd:complexType>
+
     <xsd:group name="base">
         <xsd:sequence>
             <xsd:element name="denormalizationContext" minOccurs="0" type="sequenceWithValues"/>
@@ -439,6 +452,7 @@
             <xsd:element name="types" minOccurs="0" type="types"/>
             <xsd:element name="uriVariables" minOccurs="0" type="uriVariables"/>
             <xsd:element name="links" minOccurs="0" type="links"/>
+            <xsd:element name="headers" minOccurs="0" type="headers"/>
         </xsd:sequence>
     </xsd:group>
 

src/Metadata/Get.php

@@ -39,6 +39,7 @@ public function __construct(
         array $schemes = null,
         string $condition = null,
         string $controller = null,
+        array $headers = null,
         array $cacheHeaders = null,
         array $paginationViaCursor = null,
         array $hydraContext = null,
@@ -114,6 +115,7 @@ public function __construct(
             schemes: $schemes,
             condition: $condition,
             controller: $controller,
+            headers: $headers,
             cacheHeaders: $cacheHeaders,
             paginationViaCursor: $paginationViaCursor,
             hydraContext: $hydraContext,

src/Metadata/GetCollection.php

@@ -39,6 +39,7 @@ public function __construct(
         array $schemes = null,
         string $condition = null,
         string $controller = null,
+        array $headers = null,
         array $cacheHeaders = null,
         array $paginationViaCursor = null,
         array $hydraContext = null,
@@ -115,6 +116,7 @@ public function __construct(
             schemes: $schemes,
             condition: $condition,
             controller: $controller,
+            headers: $headers,
             cacheHeaders: $cacheHeaders,
             paginationViaCursor: $paginationViaCursor,
             hydraContext: $hydraContext,

src/Metadata/HttpOperation.php

@@ -55,6 +55,7 @@ class HttpOperation extends Operation
      *     stale_while_revalidate?: int,
      *     stale-if-error?: int,
      * }|null $cacheHeaders {@see https://api-platform.com/docs/core/performance/#setting-custom-http-cache-headers}
+     * @param array<string, string>|null $headers
      * @param array{
      *     field: string,
      *     direction: string,
@@ -144,6 +145,7 @@ public function __construct(
         protected ?array $schemes = null,
         protected ?string $condition = null,
         protected ?string $controller = null,
+        protected ?array $headers = null,
         protected ?array $cacheHeaders = null,
         protected ?array $paginationViaCursor = null,
         protected ?array $hydraContext = null,
@@ -511,6 +513,19 @@ public function withController(string $controller): self
         return $self;
     }
 
+    public function getHeaders(): ?array
+    {
+        return $this->headers;
+    }
+
+    public function withHeaders(array $headers): self
+    {
+        $self = clone $this;
+        $self->headers = $headers;
+
+        return $self;
+    }
+
     public function getCacheHeaders(): ?array
     {
         return $this->cacheHeaders;

src/Metadata/NotExposed.php

@@ -50,6 +50,7 @@ public function __construct(
         array $schemes = null,
         string $condition = null,
         ?string $controller = 'api_platform.action.not_exposed',
+        array $headers = null,
         array $cacheHeaders = null,
         array $paginationViaCursor = null,
 
@@ -128,6 +129,7 @@ public function __construct(
             schemes: $schemes,
             condition: $condition,
             controller: $controller,
+            headers: $headers,
             cacheHeaders: $cacheHeaders,
             paginationViaCursor: $paginationViaCursor,
             hydraContext: $hydraContext,

src/Metadata/Patch.php

@@ -39,6 +39,7 @@ public function __construct(
         array $schemes = null,
         string $condition = null,
         string $controller = null,
+        array $headers = null,
         array $cacheHeaders = null,
         array $paginationViaCursor = null,
         array $hydraContext = null,
@@ -115,6 +116,7 @@ public function __construct(
             schemes: $schemes,
             condition: $condition,
             controller: $controller,
+            headers: $headers,
             cacheHeaders: $cacheHeaders,
             paginationViaCursor: $paginationViaCursor,
             hydraContext: $hydraContext,

src/Metadata/Post.php

@@ -39,6 +39,7 @@ public function __construct(
         array $schemes = null,
         string $condition = null,
         string $controller = null,
+        array $headers = null,
         array $cacheHeaders = null,
         array $paginationViaCursor = null,
         array $hydraContext = null,
@@ -116,6 +117,7 @@ public function __construct(
             schemes: $schemes,
             condition: $condition,
             controller: $controller,
+            headers: $headers,
             cacheHeaders: $cacheHeaders,
             paginationViaCursor: $paginationViaCursor,
             hydraContext: $hydraContext,

src/Metadata/Put.php

@@ -39,6 +39,7 @@ public function __construct(
         array $schemes = null,
         string $condition = null,
         string $controller = null,
+        array $headers = null,
         array $cacheHeaders = null,
         array $paginationViaCursor = null,
         array $hydraContext = null,
@@ -116,6 +117,7 @@ public function __construct(
             schemes: $schemes,
             condition: $condition,
             controller: $controller,
+            headers: $headers,
             cacheHeaders: $cacheHeaders,
             paginationViaCursor: $paginationViaCursor,
             hydraContext: $hydraContext,

src/Metadata/Tests/Extractor/Adapter/XmlResourceAdapter.php

@@ -507,6 +507,20 @@ private function buildLinks(\SimpleXMLElement $resource, array $values = null):
         $childNode->addAttribute('href', $values[0]['href']);
     }
 
+    private function buildHeaders(\SimpleXMLElement $resource, array $values = null): void
+    {
+        if (!$values) {
+            return;
+        }
+
+        $node = $resource->addChild('headers');
+        foreach ($values as $key => $value) {
+            $childNode = $node->addChild('header');
+            $childNode->addAttribute('key', $key);
+            $childNode->addAttribute('value', $value);
+        }
+    }
+
     private function parse($value): ?string
     {
         if (null === $value) {