minor symfony#6948 Update docs for setting custom response code in exception handler (jameshalsall)

This PR was submitted for the master branch but it was merged into the 3.3 branch instead (closes symfony#6948).

Discussion
----------

Update docs for setting custom response code in exception handler

Docs update for the changes applied in symfony/symfony#19822

Commits
-------

5f0becf Update docs for setting custom response code in exception handler

Author: javiereguiluz

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::