feature symfony#12096 Add an action to show *error* pages in kernel.debug mode (mpdude)

This PR was squashed before being merged into the 2.6-dev branch (closes symfony#12096).

Discussion
----------

Add an action to show *error* pages in kernel.debug mode

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | symfony#7446, symfony#1486, symfony#11327
| License       | MIT
| Doc PR        | symfony/symfony-docs#4293

See symfony#7446 for the initial reasoning. In short, add to your `routing_development.yml` file the following

```yaml
_errors:
    resource: "@TwigBundle/Resources/config/routing/errors.xml"
    prefix:   /_error
```

Then you can use `http://localhost/app_dev.php/_error/xxx` to preview the HTML *error* page that the default `ExceptionController` (from `TwigBundle`) would pick for the XXX status code.

You can also use `http://localhost/app_dev.php/_error/xxx.{some_format}` to show error pages for other formats than HTML, most notably `txt`.

Note that the status code will be 500 for all exceptions [that do not implement `HttpExceptionInterface`](https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Debug/Exception/FlattenException.php#L47).

##### Want to test with a custom exception?

~~Folks might want to display (part of) the exception even on error pages and thus need to work with generic (own) exceptions.~~

~~They could write an arbitrary controller and throw their exception there. By default, the `ExceptionController` would be used to handle this, only that it would not show *error* pages in `kernel.debug` mode.~~

~~Thus, a simple public setter to change the `debug` flag after construction could help. Do we want to add that as well?~~

If you want to test error pages with your own exceptions,
* create a subclass of `ExceptionController`
* set the protected `debug` flag to false
* register it as twig.exception_controller in the config
* throw your custom exception from any controller.

That should give you the error page also in `kernel.debug` mode.

##### To-Do
- [x] Update docs
- [x] Add route in symfony/symfony-default

Commits
-------

66ed177 Add an action to show *error* pages in kernel.debug mode

Author: fabpot

src/Symfony/Bundle/TwigBundle/Controller/ExceptionController.php

@@ -21,6 +21,7 @@
  * ExceptionController.
  *
  * @author Fabien Potencier <fabien@symfony.com>
+ * @author Matthias Pigulla <mp@webfactory.de>
  */
 class ExceptionController
 {
@@ -48,18 +49,24 @@ public function showAction(Request $request, FlattenException $exception, DebugL
     {
         $currentContent = $this->getAndCleanOutputBuffering($request->headers->get('X-Php-Ob-Level', -1));
 
-        $code = $exception->getStatusCode();
+        return $this->createResponse($request, $exception, $this->debug, $logger, $currentContent);
+    }
 
-        return new Response($this->twig->render(
-            $this->findTemplate($request, $request->getRequestFormat(), $code, $this->debug),
-            array(
-                'status_code'    => $code,
-                'status_text'    => isset(Response::$statusTexts[$code]) ? Response::$statusTexts[$code] : '',
-                'exception'      => $exception,
-                'logger'         => $logger,
-                'currentContent' => $currentContent,
-            )
-        ));
+    /**
+     * Displays the error page for arbitrary status codes and formats.
+     *
+     * @param Request   $request The request
+     * @param int       $code    The HTTP status code to show the error page for.
+     *
+     * @return Response
+     *
+     * @throws \InvalidArgumentException When the error template does not exist
+     */
+    public function testErrorPageAction(Request $request, $code)
+    {
+        $exception = FlattenException::create(new \Exception("Something has intentionally gone wrong."), $code);
+
+        return $this->createResponse($request, $exception, false);
     }
 
     /**
@@ -130,4 +137,29 @@ protected function templateExists($template)
 
         return false;
     }
+
+    /**
+     * @param Request              $request
+     * @param FlattenException     $exception
+     * @param bool                 $debug
+     * @param DebugLoggerInterface $logger
+     * @param string               $currentContent
+     *
+     * @return Response
+     */
+    protected function createResponse(Request $request, FlattenException $exception, $debug, DebugLoggerInterface $logger = null, $currentContent = '')
+    {
+        $code = $exception->getStatusCode();
+
+        return new Response($this->twig->render(
+            $this->findTemplate($request, $request->getRequestFormat(), $code, $debug),
+            array(
+                'status_code' => $code,
+                'status_text' => isset(Response::$statusTexts[$code]) ? Response::$statusTexts[$code] : '',
+                'exception' => $exception,
+                'logger' => $logger,
+                'currentContent' => $currentContent,
+            )
+        ));
+    }
 }

src/Symfony/Bundle/TwigBundle/Resources/config/routing/errors.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<routes xmlns="http://symfony.com/schema/routing"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd">
+
+    <route id="_twig_error_test" path="/{code}.{_format}">
+        <default key="_controller">twig.controller.exception:testErrorPageAction</default>
+        <default key="_format">html</default>
+        <requirement key="code">\d+</requirement>
+    </route>
+</routes>

src/Symfony/Bundle/TwigBundle/Tests/Controller/ExceptionControllerTest.php

@@ -41,4 +41,44 @@ public function testOnlyClearOwnOutputBuffers()
         $controller = new ExceptionController($twig, false);
         $controller->showAction($request, $flatten);
     }
+
+    public function testErrorPagesInDebugMode()
+    {
+        $twig = new \Twig_Environment(
+            new \Twig_Loader_Array(array(
+                'TwigBundle:Exception:error404.html.twig' => '
+                    {%- if exception is defined and status_text is defined and status_code is defined -%}
+                        OK
+                    {%- else -%}
+                        "exception" variable is missing
+                    {%- endif -%}
+                ',
+            ))
+        );
+
+        $request = Request::create('whatever');
+
+        $controller = new ExceptionController($twig, /* "debug" set to --> */ true);
+        $response = $controller->testErrorPageAction($request, 404);
+
+        $this->assertEquals(200, $response->getStatusCode()); // successful request
+        $this->assertEquals('OK', $response->getContent());  // content of the error404.html template
+    }
+
+    public function testFallbackToHtmlIfNoTemplateForRequestedFormat()
+    {
+        $twig = new \Twig_Environment(
+            new \Twig_Loader_Array(array(
+                'TwigBundle:Exception:error.html.twig' => 'html',
+            ))
+        );
+
+        $request = Request::create('whatever');
+        $request->setRequestFormat('txt');
+
+        $controller = new ExceptionController($twig, false);
+        $response = $controller->testErrorPageAction($request, 42);
+
+        $this->assertEquals('html', $request->getRequestFormat());
+    }
 }