Merge branch '2.8' into 3.0

xabbuh · xabbuh · commit 66b2469dee10 · 2016-01-11T08:55:13.000+01:00
diff --git a/book/controller.rst b/book/controller.rst
@@ -806,6 +806,8 @@ Just like when creating a controller for a route, the order of the arguments of
 order of the arguments, Symfony will still pass the correct value to each
 variable.
 
+.. _checking-the-validity-of-a-csrf-token::
+
 Validating a CSRF Token
 -----------------------
 
diff --git a/book/routing.rst b/book/routing.rst
@@ -812,10 +812,10 @@ Adding HTTP Method Requirements
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In addition to the URL, you can also match on the *method* of the incoming
-request (i.e. GET, HEAD, POST, PUT, DELETE). Suppose you have a contact form
-with two controllers - one for displaying the form (on a GET request) and one
-for processing the form when it's submitted (on a POST request). This can
-be accomplished with the following route configuration:
+request (i.e. GET, HEAD, POST, PUT, DELETE). Suppose you create an API for
+your blog and you have 2 routes: One for displaying a post (on a GET or HEAD
+request) and one for updating a post (on a PUT request). This can be
+accomplished with the following route configuration:
 
 .. configuration-block::
 
@@ -827,39 +827,39 @@ be accomplished with the following route configuration:
         use Sensio\Bundle\FrameworkExtraBundle\Configuration\Method;
         // ...
 
-        class MainController extends Controller
+        class BlogApiController extends Controller
         {
             /**
-             * @Route("/news")
-             * @Method("GET")
+             * @Route("/api/posts/{id}")
+             * @Method({"GET","HEAD"})
              */
-            public function newsAction()
+            public function showAction($id)
             {
-                // ... display your news
+                // ... return a JSON response with the post
             }
 
             /**
-             * @Route("/contact")
-             * @Method({"GET", "POST"})
+             * @Route("/api/posts/{id}")
+             * @Method("PUT")
              */
-            public function contactFormAction()
+            public function editAction($id)
             {
-                // ... display and process a contact form
+                // ... edit a post
             }
         }
 
     .. code-block:: yaml
 
         # app/config/routing.yml
-        news:
-            path:     /news
-            defaults: { _controller: AppBundle:Main:news }
-            methods:  [GET]
+        api_post_show:
+            path:     /api/posts/{id}
+            defaults: { _controller: AppBundle:BlogApi:show }
+            methods:  [GET, HEAD]
 
-        contact_form:
-            path:     /contact
-            defaults: { _controller: AppBundle:Main:contactForm }
-            methods:  [GET, POST]
+        api_post_edit:
+            path:     /api/posts/{id}
+            defaults: { _controller: AppBundle:BlogApi:edit }
+            methods:  [PUT]
 
     .. code-block:: xml
 
@@ -870,12 +870,12 @@ be accomplished with the following route configuration:
             xsi:schemaLocation="http://symfony.com/schema/routing
                 http://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <route id="news" path="/news" methods="GET">
-                <default key="_controller">AppBundle:Main:news</default>
+            <route id="api_post_show" path="/api/posts/{id}" methods="GET|HEAD">
+                <default key="_controller">AppBundle:BlogApi:show</default>
             </route>
 
-            <route id="contact_form" path="/contact" methods="GET|POST">
-                <default key="_controller">AppBundle:Main:contactForm</default>
+            <route id="api_post_edit" path="/api/posts/{id}" methods="PUT">
+                <default key="_controller">AppBundle:BlogApi:edit</default>
             </route>
         </routes>
 
@@ -886,20 +886,21 @@ be accomplished with the following route configuration:
         use Symfony\Component\Routing\Route;
 
         $collection = new RouteCollection();
-        $collection->add('news', new Route('/news', array(
-            '_controller' => 'AppBundle:Main:contact',
-        ), array(), array(), '', array(), array('GET')));
+        $collection->add('api_post_show', new Route('/api/posts/{id}', array(
+            '_controller' => 'AppBundle:BlogApi:show',
+        ), array(), array(), '', array(), array('GET', 'HEAD')));
 
-        $collection->add('contact_form', new Route('/contact', array(
-            '_controller' => 'AppBundle:Main:contactForm',
-        ), array(), array(), '', array(), array('GET', 'POST')));
+        $collection->add('api_post_edit', new Route('/api/posts/{id}', array(
+            '_controller' => 'AppBundle:BlogApi:edit',
+        ), array(), array(), '', array(), array('PUT')));
 
         return $collection;
 
-Despite the fact that these two routes have identical paths (``/contact``),
-the first route will match only GET requests and the second route will match
-only POST requests. This means that you can display the form and submit the
-form via the same URL, while using distinct controllers for the two actions.
+Despite the fact that these two routes have identical paths
+(``/api/posts/{id}``), the first route will match only GET or HEAD requests and
+the second route will match only PUT requests. This means that you can display
+and edit the post with the same URL, while using distinct controllers for the
+two actions.
 
 .. note::
 
diff --git a/components/routing/introduction.rst b/components/routing/introduction.rst
@@ -62,11 +62,15 @@ URL path and some array of custom variables in its constructor. This array
 of custom variables can be *anything* that's significant to your application,
 and is returned when that route is matched.
 
-If no matching route can be found a
-:class:`Symfony\\Component\\Routing\\Exception\\ResourceNotFoundException` will be thrown.
+The :method:`UrlMatcher::match() <Symfony\\Component\\Routing\\UrlMatcher::match>`
+returns the variables you set on the route as well as the wildcard placeholders
+(see below). Your application can now use this information to continue
+processing the request. In addition to the configured variables, a ``_route``
+key is added, which holds the name of the matched route.
 
-In addition to your array of custom variables, a ``_route`` key is added,
-which holds the name of the matched route.
+If no matching route can be found, a
+:class:`Symfony\\Component\\Routing\\Exception\\ResourceNotFoundException` will
+be thrown.
 
 Defining Routes
 ~~~~~~~~~~~~~~~
@@ -123,6 +127,10 @@ In this case, the route is matched by ``/archive/2012-01``, because the ``{month
 wildcard matches the regular expression wildcard given. However, ``/archive/foo``
 does *not* match, because "foo" fails the month wildcard.
 
+When using wildcards, these are returned in the array result when calling
+``match``. The part of the path that the wildcard matched (e.g. ``2012-01``) is used
+as value.
+
 .. tip::
 
     If you want to match all URLs which start with a certain path and end in an
diff --git a/components/security/authentication.rst b/components/security/authentication.rst
@@ -269,5 +269,54 @@ in) is correct, you can use::
         $user->getSalt()
     );
 
+Authentication Events
+---------------------
+
+The security component provides 4 related authentication events:
+
+===============================  ================================================  =========================================================================
+Name                             Event Constant                                    Argument Passed to the Listener
+===============================  ================================================  =========================================================================
+security.authentication.success  ``AuthenticationEvents::AUTHENTICATION_SUCCESS``  :class:`Symfony\Component\Security\Core\Event\AuthenticationEvent`
+security.authentication.failure  ``AuthenticationEvents::AUTHENTICATION_FAILURE``  :class:`Symfony\Component\Security\Core\Event\AuthenticationFailureEvent`
+security.interactive_login       ``SecurityEvents::INTERACTIVE_LOGIN``             :class:`Symfony\Component\Security\Http\Event\InteractiveLoginEvent`
+security.switch_user             ``SecurityEvents::SWITCH_USER``                   :class:`Symfony\Component\Security\Http\Event\SwitchUserEvent`
+===============================  ================================================  =========================================================================
+
+Authentication Success and Failure Events
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When a provider authenticates the user, a ``security.authentication.success``
+event is dispatched. But beware - this event will fire, for example, on *every*
+request if you have session-based authentication. See ``security.interactive_login``
+below if you need to do something when a user *actually* logs in.
+
+When a provider attempts authentication but fails (i.e. throws an ``AuthenticationException``),
+a ``security.authentication.failure`` event is dispatched. You could listen on
+the ``security.authentication.failure`` event, for example, in order to log
+failed login attempts.
+
+Security Events
+~~~~~~~~~~~~~~~
+
+The ``security.interactive_login`` event is triggered after a user has actively
+logged into your website.  It is important to distinguish this action from
+non-interactive authentication methods, such as:
+
+* authentication based on a "remember me" cookie.
+* authentication based on your session.
+* authentication using a HTTP basic or HTTP digest header.
+
+You could listen on the ``security.interactive_login`` event, for example, in
+order to give your user a welcome flash message every time they log in.
+
+The ``security.switch_user`` event is triggered every time you activate
+the ``switch_user`` firewall listener.
+
+.. seealso::
+
+    For more information on switching users, see
+    :doc:`/cookbook/security/impersonating_user`.
+
 .. _`CVE-2013-5750`: https://symfony.com/blog/cve-2013-5750-security-issue-in-fosuserbundle-login-form
 .. _`BasePasswordEncoder::checkPasswordLength`: https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Security/Core/Encoder/BasePasswordEncoder.php
