minor #2252 clean up the documentation a bit (xabbuh)

This PR was merged into the 2.x branch.

Discussion
----------

clean up the documentation a bit

Commits
-------

7de9ac0 clean up the documentation a bit

Author: xabbuh

Resources/doc/2-the-view-layer.rst

@@ -6,7 +6,7 @@ Introduction
 
 The view layer makes it possible to write ``format`` (html, json, xml, etc)
 agnostic controllers, by placing a layer between the Controller and the
-generation of the final output via the templating or a serializer.
+generation of the final output via a serializer.
 
 The bundle works both with the `Symfony Serializer Component`_ and the more
 sophisticated `serializer`_ created by Johannes Schmitt and integrated via the
@@ -134,17 +134,11 @@ combination with SensioFrameworkExtraBundle you can even omit the calls to
 
 As the purpose is to create a format-agnostic controller, data assigned to the
 ``View`` instance should ideally be an object graph, though any data type is
-acceptable. Note that when rendering templating formats, the ``ViewHandler``
-will wrap data types other than associative arrays in an associative array with
-a single key (default  ``'data'``), which will become the variable name of the
-object in the respective template. You can change this variable by calling
-the ``setTemplateVar()`` method on the view object.
+acceptable.
 
 There are also two specialized methods for redirect in the ``View`` classes.
 ``View::createRedirect`` redirects to an URL called ``RedirectView`` and
-``View::createRouteRedirect`` redirects to a route. Note that whether these
-classes actually cause a redirect or not is determined by the ``force_redirects``
-configuration option, which is only enabled for ``html`` by default (see below).
+``View::createRouteRedirect`` redirects to a route.
 
 There are several more methods on the ``View`` class, here is a list of all
 the important ones for configuring the view:
@@ -288,12 +282,9 @@ the task without any client modifications.
 Configuration
 -------------
 
-The ``formats`` and ``templating_formats`` settings determine which formats are
-respectively supported by the serializer and by the template layer. In other
-words any format listed in ``templating_formats`` will require a template for
-rendering using the ``templating`` service, while any format listed in
-``formats`` will use the serializer for rendering.  For both settings a
-value of ``false`` means that the given format is disabled.
+The ``formats`` setting determines which formats are supported by the serializer.
+Any format listed in ``formats`` will use the serializer for rendering. A value
+of ``false`` means that the given format is disabled.
 
 When using ``RouteRedirectView::create()`` the default behavior of forcing a
 redirect to the route when HTML is enabled, but this needs to be enabled for other
@@ -303,99 +294,6 @@ Finally the HTTP response status code for failed validation defaults to
 ``400``. Note when changing the default you can use name constants of
 ``Symfony\Component\HttpFoundation\Response`` class or an integer status code.
 
-You can also set the default templating engine to something different than the
-default of ``twig``:
-
-.. code-block:: yaml
-
-    fos_rest:
-        view:
-            formats:
-                rss: true
-                xml: false
-            templating_formats:
-                html: true
-            force_redirects:
-                html: true
-            failed_validation: HTTP_BAD_REQUEST
-            default_engine: twig
-
-Custom handler
---------------
-
-While many things should be possible via the serializer, in some cases
-it might not be enough. For example you might need some custom logic to be
-executed in the ``ViewHandler``. For these cases one might want to register a
-custom handler for a specific format. The custom handler can either be
-registered by defining a custom service, via a compiler pass, or it can be
-registered from inside the controller action.
-
-The callable will receive 3 parameters:
-
-* the instance of the ``ViewHandler``
-* the instance of the ``View``
-* the instance of the ``Request``
-
-Note there are several public methods on the ``ViewHandler`` which can be helpful:
-
-* ``isFormatTemplating()``
-* ``createResponse()``
-* ``createRedirectResponse()``
-* ``renderTemplate()``
-
-There is an example for how to register a custom handler (for an RSS feed) in ``Resources\doc\examples``:
-https://github.com/FriendsOfSymfony/FOSRestBundle/blob/master/Resources/doc/examples/RssHandler.php
-
-Here is an example using a closure registered inside a Controller action:
-
-.. code-block:: php
-
-    <?php
-
-    namespace AppBundle\Controller;
-
-    use Symfony\Bundle\FrameworkBundle\Controller\Controller;
-    use FOS\RestBundle\View\View;
-
-    class UsersController extends Controller
-    {
-        public function getUsersAction()
-        {
-            $view = View::create();
-
-            // ...
-
-            $handler = $this->get('fos_rest.view_handler');
-            if (!$handler->isFormatTemplating($view->getFormat())) {
-                $templatingHandler = function ($handler, $view, $request) {
-                    // if a template is set, render it using the 'params'
-                    // and place the content into the data
-                    if ($view->getTemplate()) {
-                        $data = $view->getData();
-
-                        if (empty($data['params'])) {
-                            $params = array();
-                        } else {
-                            $params = $data['params'];
-                            unset($data['params']);
-                        }
-
-                        $view->setData($params);
-                        $data['html'] = $handler->renderTemplate($view, 'html');
-
-                        $view->setData($data);
-                    }
-
-                    return $handler->createResponse($view, $request, $format);
-                };
-
-                $handler->registerHandler($view->getFormat(), $templatingHandler);
-            }
-
-            return $handler->handle($view);
-        }
-    }
-
 JSONP custom handler
 ~~~~~~~~~~~~~~~~~~~~
 

Resources/doc/3-listener-support.rst

@@ -160,39 +160,6 @@ You need to enable this listener as follows, as it is disabled by default:
     fos_rest:
         allowed_methods_listener: true
 
-Security Exception Listener
----------------------------
-
-By default it is the responsibility of firewall access points to deal with
-AccessDeniedExceptions. For example the ``form`` entry point will redirect to
-the login page. However, for a RESTful application proper response HTTP status
-codes should be provided. This listener is triggered before the normal exception
-listener and firewall entry points and forces returning either a 403 or 401
-status code for any of the formats configured.
-
-It will return 401 for
-``Symfony\Component\Security\Core\Exception\AuthenticationException`` or 403 for
-``Symfony\Component\Security\Core\Exception\AccessDeniedException``.
-
-As a 401-response requires an authentication-challenge, you can set one using
-the configuration ``unauthorized_challenge`` or leave it blank if you don't want
-to send a challenge in the ``WWW-Authenticate`` header to the client.
-
-If you want to use an advanced value in this header, it's worth looking at this:
-`Test Cases for HTTP Test Cases for the HTTP WWW-Authenticate header field`_.
-
-You need to enable this listener as follows, as it is disabled by default:
-
-.. code-block:: yaml
-
-    fos_rest:
-        unauthorized_challenge: "Basic realm=\"Restricted Area\""
-        access_denied_listener:
-            # all requests using the 'json' format will return a 403 on an access denied violation
-            json: true
-
-Note: The access_denied_listener doesn't return a response itself and must be coupled with an exception listener returning a response (see the :doc:`FOSRestBundle exception controller <4-exception-controller-support>` or the `twig exception controller`_).
-
 Zone Listener
 -------------
 

Resources/doc/4-exception-controller-support.rst

@@ -1,35 +1,6 @@
 Step 4: ExceptionController support
 ===================================
 
-When implementing an API it is also necessary to handle exceptions in a RESTful
-way, while ensuring that no security sensitive information leaks out. This
-bundle provides an extra controller for that job. Using this custom
-ExceptionController it is possible to leverage the View layer when building
-responses for uncaught Exceptions.
-
-The ExceptionController can be enabled via the FOSRestBundle
-configuration:
-
-.. code-block:: yaml
-
-    fos_rest:
-        exception:
-            enabled: true
-            exception_controller: 'Acme\DemoBundle\Controller\ExceptionController::showAction'
-
-.. note::
-
-    The FOSRestBundle ExceptionController is executed before the one of the TwigBundle.
-
-.. note::
-
-    FOSRestBundle defines two services for exception rendering, by default it
-    configures ``fos_rest.exception.controller`` which only supports rendering
-    via a serializer. In case no explicit controller is configured by the user
-    and TwigBundle is detected it will automatically configure
-    ``fos_rest.exception.twig_controller`` which additionally also supports
-    rendering via Twig.
-
 To map Exception classes to HTTP response status codes an *exception map* may
 be configured, where the keys match a fully qualified class name and the values
 are either an integer HTTP response status code or a string matching a class

Resources/doc/configuration-reference.rst

@@ -16,7 +16,6 @@ Getting Started With FOSRestBundle
     param_fetcher_listener
     4-exception-controller-support
     annotations-reference
-    configuration-reference
 
 Installation
 ------------
@@ -42,7 +41,7 @@ FOSRestBundle provides several tools to assist in building REST applications:
 Config reference
 ----------------
 
-- :doc:`Configuration reference <configuration-reference>` for a reference on
+- Run ``bin/console config:dump-reference fos_rest`` for a reference of
   the available configuration options
 - :doc:`Annotations reference <annotations-reference>` for a reference on
   the available configurations through annotations

Resources/doc/index.rst

@@ -89,21 +89,6 @@ you should return a ``$view`` object with the data set by ``setTemplateData``.
         return $view;
     }
 
-If ``@View()`` is used, the template variable name used to render templating
-formats can be configured (default  ``'data'``):
-
-.. code-block:: php
-
-    <?php
-
-    /**
-     * @View(templateVar="users")
-     */
-    public function getUsersAction()
-    {
-        // ...
-    }
-
 The status code of the view can also be configured:
 
 .. code-block:: php