Merge branch '2.8'

Author: wouterj

best_practices/security.rst

@@ -221,10 +221,6 @@ more advanced use-case, you can always do the same security check in PHP:
 
 .. code-block:: php
 
-    use Symfony\Component\Security\Core\Exception\AccessDeniedException;
-
-    // ...
-
     /**
      * @Route("/{id}/edit", name="admin_post_edit")
      */
@@ -238,7 +234,16 @@ more advanced use-case, you can always do the same security check in PHP:
         }
 
         if (!$post->isAuthor($this->getUser())) {
-            throw new AccessDeniedException();
+            $this->denyAccessUnlessGranted('edit', $post);
+
+	    // or without the shortcut:
+	    //
+	    // use Symfony\Component\Security\Core\Exception\AccessDeniedException;
+	    // ...
+	    //
+	    // if (!$this->get('security.authorization_checker')->isGranted('edit', $post)) {
+	    //    throw $this->createAccessDeniedException();
+	    // }
         }
 
         // ...
@@ -327,10 +332,6 @@ via the even easier shortcut in a controller:
 
 .. code-block:: php
 
-    use Symfony\Component\Security\Core\Exception\AccessDeniedException;
-
-    // ...
-
     /**
      * @Route("/{id}/edit", name="admin_post_edit")
      */
@@ -342,6 +343,9 @@ via the even easier shortcut in a controller:
 
         // or without the shortcut:
         //
+        // use Symfony\Component\Security\Core\Exception\AccessDeniedException;
+        // ...
+        //
         // if (!$this->get('security.authorization_checker')->isGranted('edit', $post)) {
         //    throw $this->createAccessDeniedException();
         // }

book/forms.rst

@@ -1595,13 +1595,17 @@ override the default error rendering for *all* fields, copy and customize the
 .. index::
    single: Forms; Global Theming
 
+.. _book-forms-theming-global:
+
 Global Form Theming
 ~~~~~~~~~~~~~~~~~~~
 
 In the above example, you used the ``form_theme`` helper (in Twig) to "import"
 the custom form fragments into *just* that form. You can also tell Symfony
 to import form customizations across your entire project.
 
+.. _book-forms-theming-twig:
+
 Twig
 ....
 

book/http_cache.rst

@@ -1157,6 +1157,8 @@ of the master page.
 With ESI, the full page cache will be valid for 600 seconds, but the news
 component cache will only last for 60 seconds.
 
+.. _book-http_cache-fragments:
+
 When using a controller reference, the ESI tag should reference the embedded
 action as an accessible URL so the gateway cache can fetch it independently of
 the rest of the page. Symfony takes care of generating a unique URL for any

book/routing.rst

@@ -543,6 +543,8 @@ URL          Route     Parameters
 .. index::
    single: Routing; Requirements
 
+.. _book-routing-requirements:
+
 Adding Requirements
 ~~~~~~~~~~~~~~~~~~~
 

book/templating.rst

@@ -679,6 +679,8 @@ Controllers are fast to execute and promote good code organization and reuse.
 Of course, like all controllers, they should ideally be "skinny", meaning
 that as much code as possible lives in reusable :doc:`services </book/service_container>`.
 
+.. _book-templating-hinclude:
+
 Asynchronous Content with hinclude.js
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

book/translation.rst

@@ -532,7 +532,9 @@ in your application.
 .. index::
    single: Translations; Fallback and default locale
 
-Setting a default Locale
+.. _book-translation-default-locale:
+
+Setting a Default Locale
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 What if the user's locale hasn't been determined? You can guarantee that a

cookbook/controller/error_pages.rst

@@ -27,7 +27,7 @@ Error pages for the production environment can be customized in different ways
 depending on your needs:
 
 #. If you just want to change the contents and styles of the error pages to match
-   the rest of your application, :ref:`override default error templates <use-default-exception-controller>`;
+   the rest of your application, :ref:`override the default error templates <use-default-exception-controller>`;
 
 #. If you also want to tweak the logic used by Symfony to generate error pages,
    :ref:`override the default exception controller <custom-exception-controller>`;
@@ -41,25 +41,16 @@ depending on your needs:
 Overriding the Default Error Templates
 --------------------------------------
 
-By default, the ``showAction()`` method of the
-:class:`Symfony\\Bundle\\TwigBundle\\Controller\\ExceptionController` is called
-whenever an exception occurs, thanks to an event listener configured by the TwigBundle.
-
-Then, the controller selects one of the templates defined in the
-``Resources/views/Exception`` directory of the TwigBundle to render the error
-page. If you browse that directory (usually located in
-``vendor/symfony/symfony/src/Symfony/Bundle/TwigBundle``) you'll find a lot of
-templates defined for different types of errors and content formats
-(``error.*.twig`` templates are used in the production environment whereas
-``exception.*.twig`` templates are used in the development environment).
+When the error page loads, an internal :class:`Symfony\\Bundle\\TwigBundle\\Controller\\ExceptionController`
+is used to render a Twig template to show the user.
 
 .. _cookbook-error-pages-by-status-code:
 
-The logic followed by the ``ExceptionController`` to pick one of the available
-templates is based on the HTTP status code and the request format:
+This controller uses the HTTP status code, request format and the following
+logic to determine the template filename:
 
 #. Look for a template for the given format and status code (like ``error404.json.twig``
-   or ``error500.xml.twig``);
+   or ``error500.html.twig``);
 
 #. If the previous template doesn't exist, discard the status code and look for
    a generic template for the given format (like ``error.json.twig`` or
@@ -71,8 +62,29 @@ templates is based on the HTTP status code and the request format:
 .. _overriding-or-adding-templates:
 
 To override these templates, simply rely on the standard Symfony method for
-:ref:`overriding templates that live inside a bundle <overriding-bundle-templates>`.
-For example, to override the 404 error template for HTML pages, create a new
+:ref:`overriding templates that live inside a bundle <overriding-bundle-templates>`:
+put them in the ``app/Resources/TwigBundle/views/Exception/`` directory.
+
+A typical project that returns HTML and JSON pages, might look like this:
+
+.. code-block:: text
+
+    app/
+    └─ Resources/
+       └─ TwigBundle/
+          └─ views/
+             └─ Exception/
+                ├─ error404.html.twig
+                ├─ error403.html.twig
+                ├─ error.html.twig      # All other HTML errors (including 500)
+                ├─ error404.json.twig
+                ├─ error403.json.twig
+                ├─ error.json.twig      # All other JSON errors (including 500)
+
+Example 404 Error Template
+--------------------------
+
+To override the 404 error template for HTML pages, create a new
 ``error404.html.twig`` template located at ``app/Resources/TwigBundle/views/Exception/``:
 
 .. code-block:: html+jinja
@@ -83,16 +95,17 @@ For example, to override the 404 error template for HTML pages, create a new
     {% block body %}
         <h1>Page not found</h1>
 
+        {# example security usage, see below #}
+        {% if app.user and is_granted('IS_AUTHENTICATED_FULLY') %}
+            {# ... #}
+        {% endif %}
+
         <p>
             The requested page couldn't be located. Checkout for any URL
             misspelling or <a href="{{ path('homepage') }}">return to the homepage</a>.
         </p>
     {% endblock %}
 
-Commonly, Symfony applications redefine the ``error404.html.twig`` template, the
-``error500.html.twig`` template for internal server errors and the generic
-``error.html.twig`` template to catch any other error different from 404 and 500.
-
 In case you need them, the ``ExceptionController`` passes some information to
 the error template via the ``status_code`` and ``status_text`` variables that
 store the HTTP status code and message respectively.
@@ -132,14 +145,9 @@ is undefined. The solution is to add the following check before using this funct
 Testing Error Pages during Development
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-One of the biggest hurdles of testing how do custom error pages look in your
-application is the fact that Symfony ignores them in the development environment
-and displays the default exception pages instead.
-
-You may be tempted to set the ``kernel.debug`` parameter to ``false`` to disable
-the debug mode in the development environment. However, this practice is not
-recommended because it will also stop Symfony from recompiling your Twig templates,
-among many other things.
+While you're in the development environment, Symfony shows the big *exception*
+page instead of your shiny new customized error page. So, how can you see
+what it looks like and debug it?
 
 The recommended solution is to use a third-party bundle called `WebfactoryExceptionsBundle`_.
 This bundle provides a special test controller that allows you to easily display

cookbook/profiler/storage.rst

@@ -58,12 +58,12 @@ uses MySQL as the storage for the profiler with a lifetime of one hour:
         ));
 
 The :doc:`HttpKernel component </components/http_kernel/introduction>` currently
-supports the following profiler storage implementations:
+supports the following profiler storage drivers:
 
-* :class:`Symfony\\Component\\HttpKernel\\Profiler\\FileProfilerStorage`
-* :class:`Symfony\\Component\\HttpKernel\\Profiler\\MemcachedProfilerStorage`
-* :class:`Symfony\\Component\\HttpKernel\\Profiler\\MemcacheProfilerStorage`
-* :class:`Symfony\\Component\\HttpKernel\\Profiler\\MongoDbProfilerStorage`
-* :class:`Symfony\\Component\\HttpKernel\\Profiler\\MysqlProfilerStorage`
-* :class:`Symfony\\Component\\HttpKernel\\Profiler\\RedisProfilerStorage`
-* :class:`Symfony\\Component\\HttpKernel\\Profiler\\SqliteProfilerStorage`
+* file
+* sqlite
+* mysql
+* mongodb
+* memcache
+* memcached
+* redis