[HttpKernel] Deprecate X-Status-Code for better alternative

James Halsall · James Halsall · commit b742e973752b · 2016-09-02T10:58:54.000+01:00
This marks the X-Status-Code header method of setting a custom response status
code in exception listeners for a better alternative. There is now a new method
on the GetResponseForExceptionEvent that allows successful status codes in
the response sent to the client.
diff --git a/UPGRADE-4.0.md b/UPGRADE-4.0.md
@@ -132,6 +132,11 @@ HttpKernel
    have your own `ControllerResolverInterface` implementation, you should
    inject an `ArgumentResolverInterface` instance.
 
+ * The `X-Status-Code` header method of setting a custom status code in the response
+   when handling exceptions has been removed. There is now a new
+   `GetResponseForExceptionEvent::setAllowSuccessfulResponse()` method instead, which
+   will tell the Kernel to use the response code set on the event's response object.
+
 Serializer
 ----------
 
diff --git a/src/Symfony/Component/HttpKernel/Event/GetResponseForExceptionEvent.php b/src/Symfony/Component/HttpKernel/Event/GetResponseForExceptionEvent.php
@@ -36,11 +36,17 @@ class GetResponseForExceptionEvent extends GetResponseEvent
      */
     private $exception;
 
+    /**
+     * @var bool
+     */
+    private $allowSuccessfulResponse;
+
     public function __construct(HttpKernelInterface $kernel, Request $request, $requestType, \Exception $e)
     {
         parent::__construct($kernel, $request, $requestType);
 
         $this->setException($e);
+        $this->allowSuccessfulResponse = false;
     }
 
     /**
@@ -64,4 +70,24 @@ public function setException(\Exception $exception)
     {
         $this->exception = $exception;
     }
+
+    /**
+     * Mark the event as allowing a successful response code.
+     *
+     * @param bool $allowSuccessfulResponse
+     */
+    public function setAllowSuccessfulResponse($allowSuccessfulResponse)
+    {
+        $this->allowSuccessfulResponse = $allowSuccessfulResponse;
+    }
+
+    /**
+     * Returns true if the event allows a successful response code.
+     *
+     * @return bool
+     */
+    public function allowSuccessfulResponse()
+    {
+        return $this->allowSuccessfulResponse;
+    }
 }
diff --git a/src/Symfony/Component/HttpKernel/HttpKernel.php b/src/Symfony/Component/HttpKernel/HttpKernel.php
@@ -242,10 +242,12 @@ private function handleException(\Exception $e, $request, $type)
 
         // the developer asked for a specific status code
         if ($response->headers->has('X-Status-Code')) {
+            @trigger_error(sprintf('Using the X-Status-Code header is deprecated, use %s::setAllowSuccessfulResponse() instead.', GetResponseForExceptionEvent::class), E_USER_DEPRECATED);
+
             $response->setStatusCode($response->headers->get('X-Status-Code'));
 
             $response->headers->remove('X-Status-Code');
-        } elseif (!$response->isClientError() && !$response->isServerError() && !$response->isRedirect()) {
+        } elseif (!$event->allowSuccessfulResponse() && !$response->isClientError() && !$response->isServerError() && !$response->isRedirect()) {
             // ensure that we actually have an error response
             if ($e instanceof HttpExceptionInterface) {
                 // keep the HTTP status code and headers
diff --git a/src/Symfony/Component/HttpKernel/Tests/Event/GetResponseForExceptionEventTest.php b/src/Symfony/Component/HttpKernel/Tests/Event/GetResponseForExceptionEventTest.php
@@ -0,0 +1,26 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\HttpKernel\Tests\Event;
+
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent;
+use Symfony\Component\HttpKernel\Tests\TestHttpKernel;
+
+class GetResponseForExceptionEventTest extends \PHPUnit_Framework_TestCase
+{
+    public function testAllowSuccessfulResponseIsFalseByDefault()
+    {
+        $event = new GetResponseForExceptionEvent(new TestHttpKernel(), new Request(), 1, new \Exception());
+
+        $this->assertFalse($event->allowSuccessfulResponse());
+    }
+}
diff --git a/src/Symfony/Component/HttpKernel/Tests/HttpKernelTest.php b/src/Symfony/Component/HttpKernel/Tests/HttpKernelTest.php
@@ -16,6 +16,7 @@
 use Symfony\Component\HttpKernel\Controller\ArgumentResolverInterface;
 use Symfony\Component\HttpKernel\Controller\ControllerResolverInterface;
 use Symfony\Component\HttpKernel\Event\FilterControllerArgumentsEvent;
+use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent;
 use Symfony\Component\HttpKernel\HttpKernel;
 use Symfony\Component\HttpKernel\HttpKernelInterface;
 use Symfony\Component\HttpKernel\KernelEvents;
@@ -112,7 +113,7 @@ public function testHandleHttpException()
     /**
      * @dataProvider getStatusCodes
      */
-    public function testHandleWhenAnExceptionIsHandledWithASpecificStatusCode($responseStatusCode, $expectedStatusCode)
+    public function testHandleWhenAnExceptionIsHandledWithASpecificStatusCodeViaXStatusCodeHeader($responseStatusCode, $expectedStatusCode)
     {
         $dispatcher = new EventDispatcher();
         $dispatcher->addListener(KernelEvents::EXCEPTION, function ($event) use ($responseStatusCode, $expectedStatusCode) {
@@ -136,6 +137,32 @@ public function getStatusCodes()
         );
     }
 
+    /**
+     * @dataProvider getStatusCodes
+     */
+    public function testHandleWhenAnExceptionIsHandledWithASpecificStatusCode($expectedStatusCode)
+    {
+        $dispatcher = new EventDispatcher();
+        $dispatcher->addListener(KernelEvents::EXCEPTION, function (GetResponseForExceptionEvent $event) use ($expectedStatusCode) {
+            $event->setAllowSuccessfulResponse(true);
+            $event->setResponse(new Response('', $expectedStatusCode));
+        });
+
+        $kernel = $this->getHttpKernel($dispatcher, function () { throw new \RuntimeException(); });
+        $response = $kernel->handle(new Request());
+
+        $this->assertEquals($expectedStatusCode, $response->getStatusCode());
+    }
+
+    public function getSuccessfulStatusCodes()
+    {
+        return array(
+            array(200),
+            array(204),
+            array(201),
+        );
+    }
+
     public function testHandleWhenAListenerReturnsAResponse()
     {
         $dispatcher = new EventDispatcher();
