Merge branch '2.5' into 2.6

weaverryan · weaverryan · commit 4b0ebea7e4a9 · 2015-01-16T16:12:59.000-05:00
* 2.5: [#4857] Adding missing word thanks to xabbuh Fixing bad english thanks to xabbuh Adding missing words thanks to javiereguiluz [#4643] Minor english changes to make things even smoother (though they were correct before) replace API link for SwiftmailerBundle Update security.rst Update routing.rst don't output message from AuthenticationException Add custom link labels where Cookbook articles titles looked wrong Fix code example Removed a leftover comma in security config sample [#4141] Tweaks to the new form csrf caching entry How to override vendor directory location - fix How to override vendor directory location - fix How to override vendor directory location
diff --git a/best_practices/configuration.rst b/best_practices/configuration.rst
@@ -74,8 +74,8 @@ add an extra layer of configuration that's not needed because you don't need
 or want these configuration values to change on each server.
 
 The configuration options defined in the ``config.yml`` file usually vary from
-one :doc:`/cookbook/configuration/environments` to another. That's why Symfony
-already includes ``app/config/config_dev.yml`` and ``app/config/config_prod.yml``
+one :doc:`environment </cookbook/configuration/environments>` to another. That's
+why Symfony already includes ``app/config/config_dev.yml`` and ``app/config/config_prod.yml``
 files so that you can override specific values for each environment.
 
 Constants vs Configuration Options
diff --git a/best_practices/controllers.rst b/best_practices/controllers.rst
@@ -139,7 +139,7 @@ For example:
 
     use AppBundle\Entity\Post;
     use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
-    
+
     /**
      * @Route("/{id}", name="admin_post_show")
      */
@@ -212,6 +212,7 @@ Pre and Post Hooks
 ------------------
 
 If you need to execute some code before or after the execution of your controllers,
-you can use the EventDispatcher component to :doc:`/cookbook/event_dispatcher/before_after_filters`.
+you can use the EventDispatcher component to
+:doc:`set up before and after filters </cookbook/event_dispatcher/before_after_filters>`.
 
 .. _`ParamConverter`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
diff --git a/best_practices/forms.rst b/best_practices/forms.rst
@@ -165,8 +165,9 @@ fields:
 
 If you need more control over how your fields are rendered, then you should
 remove the ``form_widget(form)`` function and render your fields individually.
-See :doc:`/cookbook/form/form_customization` for more information on this and how
-you can control *how* the form renders at a global level using form theming.
+See the :doc:`/cookbook/form/form_customization` article for more information
+on this and how you can control *how* the form renders at a global level
+using form theming.
 
 Handling Form Submits
 ---------------------
diff --git a/book/routing.rst b/book/routing.rst
@@ -644,7 +644,7 @@ be added for each parameter. For example:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: php-annotations
 
         // src/AppBundle/Controller/BlogController.php
 
diff --git a/book/security.rst b/book/security.rst
@@ -5,7 +5,7 @@ Security
 ========
 
 Symfony's security system is incredibly powerful, but it can also be confusing
-to setup. In this chapter, you'll learn how to setup your application's security
+to set up. In this chapter, you'll learn how to set up your application's security
 step-by-step, from configuring your firewall and how you load users to denying
 access and fetching the User object. Depending on what you need, sometimes
 the initial setup can be tough. But once it's done, Symfony's security system
@@ -300,7 +300,7 @@ provider, but it's better to think of it as an "in configuration" provider:
                     memory:
                         users:
                             ryan:
-                                password: ryanpass,
+                                password: ryanpass
                                 roles: 'ROLE_USER'
                             admin:
                                 password: kitten
diff --git a/components/http_kernel/introduction.rst b/components/http_kernel/introduction.rst
@@ -495,10 +495,9 @@ as possible to the client (e.g. sending emails).
 
 .. sidebar:: ``kernel.terminate`` in the Symfony Framework
 
-    If you use the SwiftmailerBundle with Symfony and use ``memory``
-    spooling, then the :class:`Symfony\\Bundle\\SwiftmailerBundle\\EventListener\\EmailSenderListener`
-    is activated, which actually delivers any emails that you scheduled to
-    send during the request.
+    If you use the SwiftmailerBundle with Symfony and use ``memory`` spooling,
+    then the `EmailSenderListener`_ is activated, which actually delivers
+    any emails that you scheduled to send during the request.
 
 .. _component-http-kernel-kernel-exception:
 
@@ -714,3 +713,4 @@ look like this::
 .. _`SensioFrameworkExtraBundle`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/index.html
 .. _`@ParamConverter`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
 .. _`@Template`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/view.html
+.. _`EmailSenderListener`: https://github.com/symfony/SwiftmailerBundle/blob/master/EventListener/EmailSenderListener.php
diff --git a/cookbook/bundles/best_practices.rst b/cookbook/bundles/best_practices.rst
@@ -369,8 +369,8 @@ API is being used. The following code, would work for *all* users::
                 // the 2.5 API
                 $this->context->buildViolation($constraint->message)
                     ->setParameter('%string%', $value)
-                    ->addViolation();
-                );
+                    ->addViolation()
+                ;
             } else {
                 // the 2.4 API
                 $this->context->addViolation(
diff --git a/cookbook/cache/form_csrf_caching.rst b/cookbook/cache/form_csrf_caching.rst
@@ -10,39 +10,33 @@ need to be cautious if you try to cache pages with forms including them.
 For more information about how CSRF protection works in Symfony, please
 check :ref:`CSRF Protection <forms-csrf>`.
 
-Why Reverse Proxy Caches do not Cache these Pages by Default
-------------------------------------------------------------
-
-There are many ways to generate unique tokens for each user but in order get
-them validated when the form is submitted, you need to store them inside the
-PHP Session.
-
-If you are using Varnish or some similar reverse proxy cache and you try to cache
-pages containing forms with CSRF token protection, you will see that, by default,
-the reverse proxy cache refuses to cache.
-
-This happens because a cookie is sent in order to preserve the PHP session open and
-Varnish default behaviour is to not cache HTTP requests with cookies.
-
-If you think about it, if you managed to cache the form you would end up
-with many users getting the same token in the form generation. When these
-users try to send the form to the server, the CSRF validation will fail for
-them because the expected token is stored in their session and different
-for each user.
-
-How to Cache Most of the Page and still Be Able to Use CSRF Protection
+Why Caching Pages with a CSRF token is Problematic
+--------------------------------------------------
+
+Typically, each user is assigned a unique CSRF token, which is stored in
+the session for validation. This means that if you *do* cache a page with
+a form containing a CSRF token, you'll cache the CSRF token of the *first*
+user only. When a user submits the form, the token won't match the token
+stored in the session and all users (except for the first) will fail CSRF
+validation when submitting the form.
+
+In fact, many reverse proxies (like Varnish) will refuse to cache a page
+with a CSRF token. This is because a cookie is sent in order to preserve
+the PHP session open and Varnish's default behaviour is to not cache HTTP
+requests with cookies.
+
+How to Cache Most of the Page and still be able to Use CSRF Protection
 ----------------------------------------------------------------------
 
-To cache a page that contains a CSRF token you can use more advanced caching
-techniques like `ESI`_ fragments, having a TTL for the full page and embedding
-the form inside an ESI tag with no cache at all.
+To cache a page that contains a CSRF token, you can use more advanced caching
+techniques like :ref:`ESI fragments <edge-side-includes>`, where you cache
+the full page and embedding the form inside an ESI tag with no cache at all.
 
-Another option to be able to cache that heavy page would be loading the form
-via an uncached AJAX request but cache the rest of the HTML response.
+Another option would be to load the form via an uncached AJAX request, but
+cache the rest of the HTML response.
 
 Or you can even load just the CSRF token with an AJAX request and replace the
 form field value with it.
 
 .. _`Cross-site request forgery`: http://en.wikipedia.org/wiki/Cross-site_request_forgery
-.. _`ESI`: http://www.w3.org/TR/esi-lang
 .. _`Security CSRF Component`: https://github.com/symfony/security-csrf
diff --git a/cookbook/configuration/override_dir_structure.rst b/cookbook/configuration/override_dir_structure.rst
@@ -154,3 +154,38 @@ file:
     
         $ php app/console cache:clear --env=prod
         $ php app/console assetic:dump --env=prod --no-debug
+
+Override the ``vendor`` Directory
+---------------------------------
+
+To override the ``vendor`` directory, you need to introduce changes in the
+following files:
+
+* ``app/autoload.php``
+* ``composer.json``
+
+The change in the ``composer.json`` will look like this:
+
+.. code-block:: json
+
+    {
+        ...
+        "config": {
+            "bin-dir": "bin",
+            "vendor-dir": "/some/dir/vendor"
+        },
+        ...
+    }
+
+In ``app/autoload.php``, you need to modify the path leading to the ``vendor/autoload.php``
+file::
+
+    // app/autoload.php
+    // ...
+    $loader = require '/some/dir/vendor/autoload.php';
+
+.. tip::
+
+    This modification can be of interest if you are working in a virtual environment
+    and cannot use NFS - for example, if you're running a Symfony app using
+    Vagrant/VirtualBox in a guest operating system.
diff --git a/cookbook/security/form_login_setup.rst b/cookbook/security/form_login_setup.rst
@@ -25,7 +25,7 @@ First, enable form login under your firewall:
         # app/config/security.yml
         security:
             # ...
-        
+
             firewalls:
                 default:
                     anonymous: ~
@@ -98,7 +98,7 @@ under your ``form_login`` configuration (``/login`` and ``/login_check``):
 .. configuration-block::
 
     .. code-block:: php-annotations
-    
+
         // src/AppBundle/Controller/SecurityController.php
         // ...
         use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
@@ -165,7 +165,7 @@ form::
 
     // src/AppBundle/Controller/SecurityController.php
     // ...
-    
+
     // ADD THIS use STATEMENT above your class
     use Symfony\Component\Security\Core\Security;
 
@@ -182,7 +182,7 @@ form::
             $error = $session->get(Security::AUTHENTICATION_ERROR);
             $session->remove(Security::AUTHENTICATION_ERROR);
         } else {
-            $error = '';
+            $error = null;
         }
 
         // last username entered by the user
@@ -218,7 +218,7 @@ Finally, create the template:
         {# ... you will probably extends your base template, like base.html.twig #}
 
         {% if error %}
-            <div>{{ error.message }}</div>
+            <div>{{ error.messageKey|trans(error.messageData) }}</div>
         {% endif %}
 
         <form action="{{ path('login_check') }}" method="post">
