[HttpFoundation] Add support for the 103 status code (Early Hints) and other 1XX statuses

Author: dunglas

CHANGELOG.md

@@ -7,6 +7,7 @@ CHANGELOG
  * Add `ParameterBag::getEnum()`
  * Create migration for session table when pdo handler is used
  * Add support for Relay PHP extension for Redis
+ * The `Response::sendHeaders()` method now takes an optional HTTP status code as parameter, allowing to send informational responses such as Early Hints responses (103 status code)
 
 6.2
 ---

Response.php

@@ -211,6 +211,11 @@ class Response
         511 => 'Network Authentication Required',                             // RFC6585
     ];
 
+    /**
+     * Tracks headers already sent in informational responses.
+     */
+    private array $sentHeaders;
+
     /**
      * @param int $status The HTTP status code (200 "OK" by default)
      *
@@ -326,30 +331,71 @@ public function prepare(Request $request): static
     /**
      * Sends HTTP headers.
      *
+     * @param null|positive-int $statusCode The status code to use, override the statusCode property if set and not null
+     *
      * @return $this
      */
-    public function sendHeaders(): static
+    public function sendHeaders(/* int $statusCode = null */): static
     {
         // headers have already been sent by the developer
         if (headers_sent()) {
             return $this;
         }
 
+        $statusCode = \func_num_args() > 0 ? func_get_arg(0) : null;
+        $informationalResponse = $statusCode >= 100 && $statusCode < 200;
+        if ($informationalResponse && !\function_exists('headers_send')) {
+            // skip informational responses if not supported by the SAPI
+            return $this;
+        }
+
         // headers
         foreach ($this->headers->allPreserveCaseWithoutCookies() as $name => $values) {
-            $replace = 0 === strcasecmp($name, 'Content-Type');
-            foreach ($values as $value) {
+            $newValues = $values;
+            $replace = false;
+
+            // As recommended by RFC 8297, PHP automatically copies headers from previous 103 responses, we need to deal with that if headers changed
+            if (103 === $statusCode) {
+                $previousValues = $this->sentHeaders[$name] ?? null;
+                if ($previousValues === $values) {
+                    // Header already sent in a previous response, it will be automatically copied in this response by PHP
+                    continue;
+                }
+
+                $replace = 0 === strcasecmp($name, 'Content-Type');
+
+                if (null !== $previousValues && array_diff($previousValues, $values)) {
+                    header_remove($name);
+                    $previousValues = null;
+                }
+
+                $newValues = null === $previousValues ? $values : array_diff($values, $previousValues);
+            }
+
+            foreach ($newValues  as $value) {
                 header($name.': '.$value, $replace, $this->statusCode);
             }
+
+            if ($informationalResponse) {
+                $this->sentHeaders[$name] = $values;
+            }
         }
 
         // cookies
         foreach ($this->headers->getCookies() as $cookie) {
             header('Set-Cookie: '.$cookie, false, $this->statusCode);
         }
 
+        if ($informationalResponse) {
+            headers_send($statusCode);
+
+            return $this;
+        }
+
+        $statusCode ??= $this->statusCode;
+
         // status
-        header(sprintf('HTTP/%s %s %s', $this->version, $this->statusCode, $this->statusText), true, $this->statusCode);
+        header(sprintf('HTTP/%s %s %s', $this->version, $statusCode, $this->statusText), true, $statusCode);
 
         return $this;
     }

StreamedResponse.php

@@ -59,17 +59,22 @@ public function setCallback(callable $callback): static
     /**
      * This method only sends the headers once.
      *
+     * @param null|positive-int $statusCode The status code to use, override the statusCode property if set and not null
+     *
      * @return $this
      */
-    public function sendHeaders(): static
+    public function sendHeaders(/* int $statusCode = null */): static
     {
         if ($this->headersSent) {
             return $this;
         }
 
-        $this->headersSent = true;
+        $statusCode = \func_num_args() > 0 ? func_get_arg(0) : null;
+        if ($statusCode < 100 || $statusCode >= 200) {
+            $this->headersSent = true;
+        }
 
-        return parent::sendHeaders();
+        return parent::sendHeaders($statusCode);
     }
 
     /**

Tests/ResponseTest.php

@@ -42,6 +42,17 @@ public function testSendHeaders()
         $this->assertSame($response, $headers);
     }
 
+    public function testSendInformationalResponse()
+    {
+        $response = new Response();
+        $response->sendHeaders(103);
+
+        // Informational responses must not override the main status code
+        $this->assertSame(200, $response->getStatusCode());
+
+        $response->sendHeaders();
+    }
+
     public function testSend()
     {
         $response = new Response();

Tests/StreamedResponseTest.php

@@ -124,4 +124,15 @@ public function testSetNotModified()
         $string = ob_get_clean();
         $this->assertEmpty($string);
     }
+
+    public function testSendInformationalResponse()
+    {
+        $response = new StreamedResponse();
+        $response->sendHeaders(103);
+
+        // Informational responses must not override the main status code
+        $this->assertSame(200, $response->getStatusCode());
+
+        $response->sendHeaders();
+    }
 }