feature #19822 [HttpKernel] Deprecate X-Status-Code for better alternative (jameshalsall)

This PR was merged into the 3.3-dev branch.

Discussion
----------

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

| Q | A |
| --- | --- |
| Branch? | master |
| Bug fix? | no |
| New feature? | yes |
| BC breaks? | no |
| Deprecations? | yes |
| Tests pass? | yes |
| Fixed tickets | #12343 |
| License | MIT |
| Doc PR | symfony/symfony-docs#6948 |

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.

The old method of setting the X-Status-Code header will now throw a deprecation warning.

Instead, in your exception listener you simply call `GetResponseForExceptionEvent::allowCustomResponseCode()` which will tell the Kernel not to override the status code of the event's response object.

Currenty the `X-Status-Code` header will still be removed, so as not to change the existing behaviour, but this is something we can remove in 4.0.

TODO:
- [x] Replace usage of X-Status-Code in `FormAuthenticationEntryPoint`
- [x] Open Silex issue
- [x] Rename method on the response
- [x] Ensure correct response code is set in `AuthenticationEntryPointInterface` implementations
- [x] Ensure the exception listeners are marking `GetResponseForExceptionEvent` as allowing a custom response code
- [x] In the Security component we should only use the new method of setting a custom response code if it is available, and fall back to the `X-Status-Code` method

Commits
-------

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

Author: fabpot

EntryPoint/FormAuthenticationEntryPoint.php

@@ -54,7 +54,7 @@ public function start(Request $request, AuthenticationException $authException =
 
             $response = $this->httpKernel->handle($subRequest, HttpKernelInterface::SUB_REQUEST);
             if (200 === $response->getStatusCode()) {
-                $response->headers->set('X-Status-Code', 401);
+                $response->setStatusCode(401);
             }
 
             return $response;

Firewall/ExceptionListener.php

@@ -112,6 +112,7 @@ private function handleAuthenticationException(GetResponseForExceptionEvent $eve
 
         try {
             $event->setResponse($this->startAuthentication($event->getRequest(), $exception));
+            $event->allowCustomResponseCode();
         } catch (\Exception $e) {
             $event->setException($e);
         }
@@ -155,6 +156,7 @@ private function handleAccessDeniedException(GetResponseForExceptionEvent $event
                 $subRequest->attributes->set(Security::ACCESS_DENIED_ERROR, $exception);
 
                 $event->setResponse($event->getKernel()->handle($subRequest, HttpKernelInterface::SUB_REQUEST, true));
+                $event->allowCustomResponseCode();
             }
         } catch (\Exception $e) {
             if (null !== $this->logger) {

Tests/EntryPoint/FormAuthenticationEntryPointTest.php

@@ -64,6 +64,6 @@ public function testStartWithUseForward()
         $entryPointResponse = $entryPoint->start($request);
 
         $this->assertEquals($response, $entryPointResponse);
-        $this->assertEquals(401, $entryPointResponse->headers->get('X-Status-Code'));
+        $this->assertEquals(401, $entryPointResponse->getStatusCode());
     }
 }

Tests/Firewall/ExceptionListenerTest.php

@@ -44,14 +44,19 @@ public function testAuthenticationExceptionWithoutEntryPoint(\Exception $excepti
     /**
      * @dataProvider getAuthenticationExceptionProvider
      */
-    public function testAuthenticationExceptionWithEntryPoint(\Exception $exception, \Exception $eventException = null)
+    public function testAuthenticationExceptionWithEntryPoint(\Exception $exception)
     {
-        $event = $this->createEvent($exception = new AuthenticationException());
+        $event = $this->createEvent($exception);
+
+        $response = new Response('Forbidden', 403);
 
-        $listener = $this->createExceptionListener(null, null, null, $this->createEntryPoint());
+        $listener = $this->createExceptionListener(null, null, null, $this->createEntryPoint($response));
         $listener->onKernelException($event);
 
-        $this->assertEquals('OK', $event->getResponse()->getContent());
+        $this->assertTrue($event->isAllowingCustomResponseCode());
+
+        $this->assertEquals('Forbidden', $event->getResponse()->getContent());
+        $this->assertEquals(403, $event->getResponse()->getStatusCode());
         $this->assertSame($exception, $event->getException());
     }
 
@@ -100,7 +105,7 @@ public function testAccessDeniedExceptionFullFledgedAndWithoutAccessDeniedHandle
     public function testAccessDeniedExceptionFullFledgedAndWithoutAccessDeniedHandlerAndWithErrorPage(\Exception $exception, \Exception $eventException = null)
     {
         $kernel = $this->getMockBuilder('Symfony\Component\HttpKernel\HttpKernelInterface')->getMock();
-        $kernel->expects($this->once())->method('handle')->will($this->returnValue(new Response('error')));
+        $kernel->expects($this->once())->method('handle')->will($this->returnValue(new Response('Unauthorized', 401)));
 
         $event = $this->createEvent($exception, $kernel);
 
@@ -110,7 +115,10 @@ public function testAccessDeniedExceptionFullFledgedAndWithoutAccessDeniedHandle
         $listener = $this->createExceptionListener(null, $this->createTrustResolver(true), $httpUtils, null, '/error');
         $listener->onKernelException($event);
 
-        $this->assertEquals('error', $event->getResponse()->getContent());
+        $this->assertTrue($event->isAllowingCustomResponseCode());
+
+        $this->assertEquals('Unauthorized', $event->getResponse()->getContent());
+        $this->assertEquals(401, $event->getResponse()->getStatusCode());
         $this->assertSame(null === $eventException ? $exception : $eventException, $event->getException()->getPrevious());
     }
 
@@ -159,10 +167,10 @@ public function getAccessDeniedExceptionProvider()
         );
     }
 
-    private function createEntryPoint()
+    private function createEntryPoint(Response $response = null)
     {
         $entryPoint = $this->getMockBuilder('Symfony\Component\Security\Http\EntryPoint\AuthenticationEntryPointInterface')->getMock();
-        $entryPoint->expects($this->once())->method('start')->will($this->returnValue(new Response('OK')));
+        $entryPoint->expects($this->once())->method('start')->will($this->returnValue($response ?: new Response('OK')));
 
         return $entryPoint;
     }

composer.json

@@ -20,7 +20,7 @@
         "symfony/security-core": "~3.2",
         "symfony/event-dispatcher": "~2.8|~3.0",
         "symfony/http-foundation": "~2.8|~3.0",
-        "symfony/http-kernel": "~2.8|~3.0",
+        "symfony/http-kernel": "~3.3",
         "symfony/polyfill-php56": "~1.0",
         "symfony/polyfill-php70": "~1.0",
         "symfony/property-access": "~2.8|~3.0"