minor #6857 Update events.rst (tabbi89)

weaverryan · weaverryan · commit bc8373575875 · 2016-12-14T19:15:27.000-05:00
This PR was merged into the 2.7 branch. Discussion ---------- Update events.rst What I have done here is just a complete explanation what is going on during setting response status code. Sentence `setting the status on the response won't work` is not true because if we pass "proper status code" it will be passed to final response without further checks - condition: https://github.com/symfony/symfony/blob/master/src/Symfony/Component/HttpKernel/HttpKernel.php#L248. So for example If I do something like this ``` php // ... $exception = $event->getException(); $response = new Response(); // setup the Response object based on the caught exception $event->setResponse($response); $event->setStatusCode(400); ``` Finally 400 status code will be passed to response! In my opinion current documentation is incorrect and as a developer I would like to have valid information. Maybe what I wrote is too precise maybe a reference to code would be a better option ? Thanks a lot. Commits ------- 4db1863 Update events.rst
diff --git a/reference/events.rst b/reference/events.rst
@@ -241,10 +241,8 @@ and set a new ``Exception`` object, or do nothing::
 
 .. note::
 
-    As Symfony ensures that the Response status code is set to the most
-    appropriate one depending on the exception, setting the status on the
-    response won't work. If you want to overwrite the status code (which you
-    should not without a good reason), set the ``X-Status-Code`` header::
+    If you want to overwrite the status code (which you should not without a good reason),
+     set the ``X-Status-Code`` header::
 
         $response = new Response(
             'Error',
@@ -254,6 +252,20 @@ and set a new ``Exception`` object, or do nothing::
             )
         );
 
+    This indeed will skip all checks that Symfony processes on setting response status code.
+    First check that Symfony does is fitting response status code.
+    Symfony leaves set status code as it is if it belongs to one of group:
+
+    :method:`Symfony\\Component\\HttpFoundation\\Response::isClientError`
+
+    :method:`Symfony\\Component\\HttpFoundation\\Response::isServerError`
+
+    :method:`Symfony\\Component\\HttpFoundation\\Response::isRedirect`
+
+    If status code is different then Symfony checks instance of raised Exception if it is
+    :class:`Symfony\\Component\\HttpKernel\\Exception\\HttpExceptionInterface` then its headers including status code are passed to response.
+    Otherwise status code 500 is set to response.
+
 .. seealso::
 
     Read more on the :ref:`kernel.exception event <component-http-kernel-kernel-exception>`.
