Update docs for setting custom response code in exception handler

Author: James Halsall

reference/events.rst

@@ -217,22 +217,35 @@ sent as response::
     that forwards the ``Request`` to a given controller defined by the
     ``exception_listener.controller`` parameter.
 
-.. note::
+Symfony uses the following logic to determine the HTTP status code of the
+response:
+
+* If :method:`Symfony\\Component\\HttpFoundation\\Response::isClientError`,
+  :method:`Symfony\\Component\\HttpFoundation\\Response::isServerError` or
+  :method:`Symfony\\Component\\HttpFoundation\\Response::isRedirect` is true,
+  then the status code on your ``Response`` object is used;
+
+* If the original exception implements
+  :class:`Symfony\\Component\\HttpKernel\\Exception\\HttpExceptionInterface`,
+  then ``getStatusCode()`` is called on the exception and used (the headers
+  from ``getHeaders()`` are also added);
 
-    Symfony uses the following logic to determine the HTTP status code of the
-    response:
+* If both of the above aren't true, then a 500 status code is used.
 
-    * If :method:`Symfony\\Component\\HttpFoundation\\Response::isClientError`,
-      :method:`Symfony\\Component\\HttpFoundation\\Response::isServerError` or
-      :method:`Symfony\\Component\\HttpFoundation\\Response::isRedirect` is true,
-      then the status code on your ``Response`` object is used;
+.. note::
+
+    If you want to overwrite the status code of the exception response, which
+    you should not without a good reason, call
+    ``GetResponseForExceptionEvent::allowSuccessfulResponse()`` first and then
+    set the status code on the response::
 
-    * If the original exception implements
-      :class:`Symfony\\Component\\HttpKernel\\Exception\\HttpExceptionInterface`,
-      then ``getStatusCode()`` is called on the exception and used (the headers
-      from ``getHeaders()`` are also added);
+        $event->allowSuccessfulResponse();
+        $response = new Response('No Content', 204);
+        $event->setResponse($response);
 
-    * If both of the above aren't true, then a 500 status code is used.
+    The status code sent to the client in the above example will be ``204`. If
+    ``$event->allowSuccessfulResponse()`` is omitted, then the kernel will set
+    an appropriate status code based on the type of exception thrown.
 
 .. seealso::