Merge branch '2.6' into 2.7

* 2.6:
  Changed PhpStormOpener to PhpStormProtocol
  [#5402] Being explicit what this applies to (it should not apply to things like >=)
  [Contributing] [Conventions] Added entry for Yoda conditions
  Added the "payload" option back
  Show annotations first
  Reordered the code blocks to show Annotations, YAML, XML and PHP
  Fixed the issues reported by @xabbuh
  Finished the documentation of the new data comparison validators
  Added information about the new date handling in the comparison constraints and Range
  Document security.switch_user event
  Added some more docs about the remember me feature
  Fixed a minor grammar issue
  Fixed a minor grammar issue
  Added support for standard Forwarded header
  Added support for standard Forwarded header
  Fixed issues reported by @xabbuh
  Remove the Propel book chapter and explain why we do that

Author: weaverryan

book/propel.rst

@@ -102,6 +102,10 @@ Structure
 
 * Always use `identical comparison`_ unless you need type juggling;
 
+* Use `Yoda conditions`_ when checking a variable against an expression to avoid
+  an accidental assignment inside the condition statement (this applies to ``==``,
+  ``!=``, ``===``, and ``!==``);
+
 * Add a comma after each array item in a multi-line array, even after the
   last one;
 
@@ -189,3 +193,4 @@ License
 .. _`PSR-2`: http://www.php-fig.org/psr/psr-2/
 .. _`PSR-4`: http://www.php-fig.org/psr/psr-4/
 .. _`identical comparison`: https://php.net/manual/en/language.operators.comparison.php
+.. _`Yoda conditions`: https://en.wikipedia.org/wiki/Yoda_conditions

contributing/code/standards.rst

@@ -7,9 +7,14 @@ an AWS Elastic Load Balancer) or a reverse proxy (e.g. Varnish for
 
 For the most part, this doesn't cause any problems with Symfony. But, when
 a request passes through a proxy, certain request information is sent using
-special ``X-Forwarded-*`` headers. For example, instead of reading the ``REMOTE_ADDR``
-header (which will now be the IP address of your reverse proxy), the user's
-true IP will be stored in an ``X-Forwarded-For`` header.
+either the standard ``Forwarded`` header or non-standard special ``X-Forwarded-*``
+headers. For example, instead of reading the ``REMOTE_ADDR`` header (which
+will now be the IP address of your reverse proxy), the user's true IP will be
+stored in a standard ``Forwarded: for="..."`` header or a non standard
+``X-Forwarded-For`` header.
+
+.. versionadded:: 2.7
+    ``Forwarded`` header support was introduced in Symfony 2.7.
 
 If you don't configure Symfony to look for these headers, you'll get incorrect
 information about the client's IP address, whether or not the client is connecting
@@ -57,9 +62,9 @@ the IP address ``192.0.0.1`` or matches the range of IP addresses that use
 the CIDR notation ``10.0.0.0/8``. For more details, see the
 :ref:`framework.trusted_proxies <reference-framework-trusted-proxies>` option.
 
-That's it! Symfony will now look for the correct ``X-Forwarded-*`` headers
-to get information like the client's IP address, host, port and whether or
-not the request is using HTTPS.
+That's it! Symfony will now look for the correct headers to get information
+like the client's IP address, host, port and whether the request is
+using HTTPS.
 
 But what if the IP of my Reverse Proxy Changes Constantly!
 ----------------------------------------------------------
@@ -93,9 +98,14 @@ other information.
 My Reverse Proxy Uses Non-Standard (not X-Forwarded) Headers
 ------------------------------------------------------------
 
-Most reverse proxies store information on specific ``X-Forwarded-*`` headers.
-But if your reverse proxy uses non-standard header names, you can configure
+Although `RFC 7239`_ recently defined a standard ``Forwarded`` header to disclose
+all proxy information, most reverse proxies store information in non-standard
+``X-Forwarded-*`` headers.
+
+But if your reverse proxy uses other non-standard header names, you can configure
 these (see ":doc:`/components/http_foundation/trusting_proxies`").
+
 The code for doing this will need to live in your front controller (e.g. ``web/app.php``).
 
 .. _`security groups`: http://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/using-elb-security-groups.html
+.. _`RFC 7239`: http://tools.ietf.org/html/rfc7239

cookbook/request/load_balancer_reverse_proxy.rst

@@ -152,3 +152,63 @@ setting:
                 ),
             ),
         ));
+        
+Events
+------
+
+The firewall dispatches the ``security.switch_user`` event right after the impersonation
+is completed. The :class:`Symfony\\Component\\Security\\Http\\Event\\SwitchUserEvent` is
+passed to the listener, and you can use this to get the user that you are now impersonating.
+
+The cookbook article about
+:doc:`Making the Locale "Sticky" during a User's Session </cookbook/session/locale_sticky_session>`
+does not update the locale when you impersonate a user. The following code sample will show
+how to change the sticky locale:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/services.yml
+        services:
+            app.switch_user_listener:
+                class: AppBundle\EventListener\SwitchUserListener
+                tags:
+                    - { name: kernel.event_listener, event: security.switch_user, method: onSwitchUser }
+
+    .. code-block:: xml
+
+        <!-- app/config/services.xml -->
+        <service id="app.switch_user_listener" class="AppBundle\EventListener\SwitchUserListener">
+            <tag name="kernel.event_listener" event="security.switch_user" method="onSwitchUser" />
+        </service>
+
+    .. code-block:: php
+
+        // app/config/services.php
+        $container
+            ->register('app.switch_user_listener', 'AppBundle\EventListener\SwitchUserListener')
+            ->addTag('kernel.event_listener', array('event' => 'security.switch_user', 'method' => 'onSwitchUser'))
+        ;
+
+.. caution::
+
+    The listener implementation assumes your ``User`` entity has a ``getLocale()`` method.
+
+.. code-block:: php
+
+        // src/AppBundle/EventListener/SwitchUserListener.pnp
+        namespace AppBundle\EventListener;
+
+        use Symfony\Component\Security\Http\Event\SwitchUserEvent;
+        
+        class SwitchUserListener
+        {
+            public function onSwitchUser(SwitchUserEvent $event)
+            {
+                $event->getRequest()->getSession()->set(
+                    '_locale', 
+                    $event->getTargetUser()->getLocale()
+                );
+            }
+        }

cookbook/security/impersonating_user.rst

@@ -16,11 +16,16 @@ the session lasts using a cookie with the ``remember_me`` firewall option:
 
         # app/config/security.yml
         firewalls:
-            main:
+            default:
+                # ...
                 remember_me:
                     key:      "%secret%"
                     lifetime: 604800 # 1 week in seconds
                     path:     /
+                    # by default, the feature is enabled by checking a
+                    # checkbox in the login form (see below), uncomment the
+                    # below lines to always enable it.
+                    #always_remember_me: true
 
     .. code-block:: xml
 
@@ -33,12 +38,16 @@ the session lasts using a cookie with the ``remember_me`` firewall option:
                 http://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
-                <firewall>
-                    <!-- lifetime: 604800 seconds = 1 week -->
+                <firewall name="default">
+                    <!-- ... -->
+
+                    <!-- by default, the feature is enabled by checking a checkbox
+                         in the login form (see below), add always-remember-me="true"
+                         to always enable it. -->
                     <remember-me
-                        key="%secret%"
-                        lifetime="604800"
-                        path="/"
+                        key      = "%secret%"
+                        lifetime = "604800" <!-- 1 week in seconds -->
+                        path     = "/"
                     />
                 </firewall>
             </config>
@@ -49,11 +58,16 @@ the session lasts using a cookie with the ``remember_me`` firewall option:
         // app/config/security.php
         $container->loadFromExtension('security', array(
             'firewalls' => array(
-                'main' => array(
+                'default' => array(
+                    // ...
                     'remember_me' => array(
                         'key'      => '%secret%',
                         'lifetime' => 604800, // 1 week in seconds
                         'path'     => '/',
+                        // by default, the feature is enabled by checking a
+                        // checkbox in the login form (see below), uncomment
+                        // the below lines to always enable it.
+                        //'always_remember_me' => true,
                     ),
                 ),
             ),
@@ -103,21 +117,30 @@ The ``remember_me`` firewall defines the following configuration options:
     "Remember Me" feature is always enabled, regardless of the desire of the
     end user.
 
+``token_provider`` (default value: ``null``)
+    Defines the service id of a token provider to use. By default, tokens are
+    stored in a cookie. For example, you might want to store the token in a
+    database, to not have a (hashed) version of the password in a cookie. The
+    DoctrineBridge comes with a
+    ``Symfony\Bridge\Doctrine\Security\RememberMe\DoctrineTokenProvider`` that
+    you can use.
+
 Forcing the User to Opt-Out of the Remember Me Feature
 ------------------------------------------------------
 
 It's a good idea to provide the user with the option to use or not use the
 remember me functionality, as it will not always be appropriate. The usual
 way of doing this is to add a checkbox to the login form. By giving the checkbox
-the name ``_remember_me``, the cookie will automatically be set when the checkbox
-is checked and the user successfully logs in. So, your specific login form
-might ultimately look like this:
+the name ``_remember_me`` (or the name you configured using ``remember_me_parameter``),
+the cookie will automatically be set when the checkbox is checked and the user
+successfully logs in. So, your specific login form might ultimately look like
+this:
 
 .. configuration-block::
 
     .. code-block:: html+jinja
 
-        {# src/Acme/SecurityBundle/Resources/views/Security/login.html.twig #}
+        {# app/Resources/views/security/login.html.twig #}
         {% if error %}
             <div>{{ error.message }}</div>
         {% endif %}
@@ -137,7 +160,7 @@ might ultimately look like this:
 
     .. code-block:: html+php
 
-        <!-- src/Acme/SecurityBundle/Resources/views/Security/login.html.php -->
+        <!-- app/Resources/views/security/login.html.php -->
         <?php if ($error): ?>
             <div><?php echo $error->getMessage() ?></div>
         <?php endif ?>
@@ -159,7 +182,7 @@ might ultimately look like this:
 The user will then automatically be logged in on subsequent visits while
 the cookie remains valid.
 
-Forcing the User to Re-authenticate before Accessing certain Resources
+Forcing the User to Re-Authenticate before Accessing certain Resources
 ----------------------------------------------------------------------
 
 When the user returns to your site, they are authenticated automatically based

cookbook/security/remember_me.rst

@@ -262,7 +262,7 @@ you use PHPstorm on the Mac OS platform, you will do something like:
 
 .. tip::
 
-    If you're on a Windows PC, you can install the `PhpStormOpener`_ to
+    If you're on a Windows PC, you can install the `PhpStormProtocol`_ to
     be able to use this.
 
 Of course, since every developer uses a different IDE, it's better to set
@@ -1620,5 +1620,5 @@ Full Default Configuration
 .. _`HTTP Host header attacks`: http://www.skeletonscribe.net/2013/05/practical-http-host-header-attacks.html
 .. _`Security Advisory Blog post`: http://symfony.com/blog/security-releases-symfony-2-0-24-2-1-12-2-2-5-and-2-3-3-released#cve-2013-4752-request-gethost-poisoning
 .. _`Doctrine Cache`: http://docs.doctrine-project.org/projects/doctrine-common/en/latest/reference/caching.html
-.. _`PhpStormOpener`: https://github.com/pinepain/PhpStormOpener
 .. _`egulias/email-validator`: https://github.com/egulias/EmailValidator
+.. _`PhpStormProtocol`: https://github.com/aik099/PhpStormProtocol