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
symfony · Jun 28, 2015 · d7c9085 · d7c9085
2 parents 9f62c19 + 6d3d892
commit d7c9085
Show file tree

Hide file tree

Showing 11 changed files with 1,116 additions and 569 deletions.
diff --git a/book/propel.rst b/book/propel.rst
diff --git a/contributing/code/standards.rst b/contributing/code/standards.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
diff --git a/cookbook/request/load_balancer_reverse_proxy.rst b/cookbook/request/load_balancer_reverse_proxy.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
diff --git a/cookbook/security/impersonating_user.rst b/cookbook/security/impersonating_user.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()
+                );
+            }
+        }
diff --git a/cookbook/security/remember_me.rst b/cookbook/security/remember_me.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

diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.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