Allow to enable/disable header replacement

Author: natanfelles

guide/index.rst

@@ -364,6 +364,41 @@ Also, you can use constants from the **ResponseHeader** class:
     $response->setHeader(ResponseHeader::CONTENT_TYPE, 'text/xml'); // static
     $response->setContentType('text/xml'); // static
 
+Repeated Header Names
+^^^^^^^^^^^^^^^^^^^^^
+
+The HTTP response allows some headers to be repeated, such as the
+**X-Robot-Tag** header.
+
+See the example below setting the header and appending one more:
+
+.. code-block:: php
+
+    $response->setHeader('X-Robots-Tag', 'nofollow')
+             ->appendHeader('X-Robots-Tag', 'googlebot: noindex')
+
+Then the response will send multiple headers with the same name:
+
+.. code-block:: http
+
+    X-Robots-Tag: nofollow
+    X-Robots-Tag: googlebot: noindex
+
+If you need to replace the headers, call the ``setReplaceHeaders`` method before
+sending the response:
+
+.. code-block:: php
+
+    $response->setReplaceHeaders();
+    $response->setHeader('X-Robots-Tag', 'nofollow')
+             ->appendHeader('X-Robots-Tag', 'googlebot: noindex')
+
+Then the headers will be replaced. And only the last one is sent in the response:
+
+.. code-block:: http
+
+    X-Robots-Tag: googlebot: noindex
+
 Response Body
 #############
 

src/Debug/HTTPCollector.php

@@ -243,6 +243,9 @@ protected function renderResponse() : string
         <?php
         endif;
         echo $this->renderHeadersTable($this->response->getHeaderLines());
+        if ($this->response->isReplacingHeaders()) {
+            echo '<p><small>* Note that the Response is replacing headers.</small></p>';
+        }
         echo '<p><small>* Note that some headers can be set outside the Response';
         echo ' class, for example by the session or the server.';
         echo ' So they don\'t appear here.</small></p>';

src/Response.php

@@ -49,6 +49,7 @@ class Response extends Message implements ResponseInterface
     protected HTTPCollector $debugCollector;
     protected CSP $csp;
     protected CSP $cspReportOnly;
+    protected bool $replaceHeaders = false;
 
     /**
      * Response constructor.
@@ -524,13 +525,44 @@ protected function sendHeaders() : void
         }
         $this->negotiateCsp();
         $code = $this->getStatusCode();
+        $replace = $this->isReplacingHeaders();
         \header($this->getStartLine(), true, $code);
         foreach ($this->getHeaderLines() as $line) {
-            \header($line, true, $code);
+            \header($line, $replace, $code);
         }
         $this->headersSent = true;
     }
 
+    /**
+     * The replace parameter indicates whether the header should replace a
+     * previous similar header, or add a next header of the same type.
+     * By default, it will replace, but if you pass in false as the first
+     * argument you can force multiple headers of the same type.
+     *
+     * @param bool $replace
+     *
+     * @see Response::sendHeaders()
+     *
+     * @return static
+     */
+    public function setReplaceHeaders(bool $replace = true) : static
+    {
+        $this->replaceHeaders = $replace;
+        return $this;
+    }
+
+    /**
+     * Tells if headers are being replaced.
+     *
+     * @see Response::setReplaceHeaders()
+     *
+     * @return bool
+     */
+    public function isReplacingHeaders() : bool
+    {
+        return $this->replaceHeaders;
+    }
+
     /**
      * Set the Content-Security-Policy and Content-Security-Policy-Report-Only
      * headers if the CSP classes are set and the response has not downloads.

tests/Debug/HTTPCollectorTest.php

@@ -213,4 +213,29 @@ public function testGetActivities() : void
             'end',
         ], \array_keys($this->collector->getActivities()[0])); // @phpstan-ignore-line
     }
+
+    public function testResponseReplaceHeadersDisabled() : void
+    {
+        $response = $this->prepare();
+        \ob_start();
+        $response->send();
+        \ob_end_clean();
+        self::assertStringNotContainsString(
+            'Note that the Response is replacing headers',
+            $this->collector->getContents()
+        );
+    }
+
+    public function testResponseReplaceHeadersEnabled() : void
+    {
+        $response = $this->prepare();
+        $response->setReplaceHeaders();
+        \ob_start();
+        $response->send();
+        \ob_end_clean();
+        self::assertStringContainsString(
+            'Note that the Response is replacing headers',
+            $this->collector->getContents()
+        );
+    }
 }

tests/ResponseTest.php

@@ -343,6 +343,40 @@ public function sendHeaders() : void
         $response->sendHeaders();
     }
 
+    public function testReplaceHeadersDisabled() : void
+    {
+        self::assertFalse($this->response->isReplacingHeaders());
+        $this->response
+            ->setHeader('Date', 'foo')
+            ->appendHeader('Date', 'bar')
+            ->appendHeader('Date', 'baz');
+        \ob_start();
+        $this->response->send();
+        \ob_get_clean();
+        $headers = xdebug_get_headers();
+        self::assertContains('Date: foo', $headers);
+        self::assertContains('Date: bar', $headers);
+        self::assertContains('Date: baz', $headers);
+    }
+
+    public function testReplaceHeadersEnabled() : void
+    {
+        self::assertFalse($this->response->isReplacingHeaders());
+        $this->response->setReplaceHeaders();
+        self::assertTrue($this->response->isReplacingHeaders());
+        $this->response
+            ->setHeader('Date', 'foo')
+            ->appendHeader('Date', 'bar')
+            ->appendHeader('Date', 'baz');
+        \ob_start();
+        $this->response->send();
+        \ob_get_clean();
+        $headers = xdebug_get_headers();
+        self::assertNotContains('Date: foo', $headers);
+        self::assertNotContains('Date: bar', $headers);
+        self::assertContains('Date: baz', $headers);
+    }
+
     public function testInvalidStatusCode() : void
     {
         $this->expectException(\InvalidArgumentException::class);