Merge branch '2.2' into 2.3

Conflicts:
	reference/forms/types/options/property_path.rst.inc

Author: weaverryan

book/controller.rst

@@ -687,23 +687,19 @@ the ``notice`` message:
 
     .. code-block:: html+jinja
 
-        {% if app.session.started %}
-            {% for flashMessage in app.session.flashbag.get('notice') %}
-                <div class="flash-notice">
-                    {{ flashMessage }}
-                </div>
-            {% endfor %}
-        {% endif %}
+        {% for flashMessage in app.session.flashbag.get('notice') %}
+            <div class="flash-notice">
+                {{ flashMessage }}
+            </div>
+        {% endfor %}
 
     .. code-block:: html+php
 
-        <?php if ($view['session']->isStarted()): ?>
-            <?php foreach ($view['session']->getFlashBag()->get('notice') as $message): ?>
-                <div class="flash-notice">
-                    <?php echo "<div class='flash-error'>$message</div>" ?>
-                </div>
-            <?php endforeach; ?>
-        <?php endif; ?>
+        <?php foreach ($view['session']->getFlashBag()->get('notice') as $message): ?>
+            <div class="flash-notice">
+                <?php echo "<div class='flash-error'>$message</div>" ?>
+            </div>
+        <?php endforeach; ?>
 
 By design, flash messages are meant to live for exactly one request (they're
 "gone in a flash"). They're designed to be used across redirects exactly as

book/doctrine.rst

@@ -1462,7 +1462,7 @@ and ``nullable``. Take a few examples:
         <!--
             A string field length 255 that cannot be null
             (reflecting the default values for the "length" and *nullable* options)
-            type attribute is necessary in yaml definitions
+            type attribute is necessary in xml definitions
         -->
         <field name="name" type="string" />
         <field name="email"

book/http_cache.rst

@@ -975,7 +975,7 @@ possible.
 
 .. tip::
 
-    The listener listener only responds to local IP addresses or trusted
+    The listener only responds to local IP addresses or trusted
     proxies.
 
 .. note::

book/templating.rst

@@ -1381,43 +1381,9 @@ in a JavaScript string, use the ``js`` context:
 Debugging
 ---------
 
-.. versionadded:: 2.0.9
-    This feature is available as of Twig ``1.5.x``, which was first shipped
-    with Symfony 2.0.9.
-
 When using PHP, you can use ``var_dump()`` if you need to quickly find the
 value of a variable passed. This is useful, for example, inside your controller.
-The same can be achieved when using Twig by using the debug extension. This
-needs to be enabled in the config:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # app/config/config.yml
-        services:
-            acme_hello.twig.extension.debug:
-                class:        Twig_Extension_Debug
-                tags:
-                     - { name: 'twig.extension' }
-
-    .. code-block:: xml
-
-        <!-- app/config/config.xml -->
-        <services>
-            <service id="acme_hello.twig.extension.debug" class="Twig_Extension_Debug">
-                <tag name="twig.extension" />
-            </service>
-        </services>
-
-    .. code-block:: php
-
-        // app/config/config.php
-        use Symfony\Component\DependencyInjection\Definition;
-
-        $definition = new Definition('Twig_Extension_Debug');
-        $definition->addTag('twig.extension');
-        $container->setDefinition('acme_hello.twig.extension.debug', $definition);
+The same can be achieved when using Twig thanks to the the debug extension.
 
 Template parameters can then be dumped using the ``dump`` function:
 

book/validation.rst

@@ -779,6 +779,9 @@ With this configuration, there are two validation groups:
 
 * ``Default`` - contains the constraints not assigned to any other group;
 
+* ``User`` - contains the constraints that belongs to group ``Default``
+  (this group is useful for :ref:`book-validation-group-sequence`);
+
 * ``registration`` - contains the constraints on the ``email`` and ``password``
   fields only.
 
@@ -787,13 +790,138 @@ as the second argument to the ``validate()`` method::
 
     $errors = $validator->validate($author, array('registration'));
 
+If no groups are specified, all constraints that belong in group ``Default``
+will be applied.
+
 Of course, you'll usually work with validation indirectly through the form
 library. For information on how to use validation groups inside forms, see
 :ref:`book-forms-validation-groups`.
 
 .. index::
    single: Validation; Validating raw values
 
+.. _book-validation-group-sequence:
+
+Group Sequence
+--------------
+
+In some cases, you want to validate your groups by steps. To do this, you can
+use the ``GroupSequence`` feature. In the case, an object defines a group sequence,
+and then the groups in the group sequence are validated in order.
+
+.. tip::
+
+    Group sequences cannot contain the group ``Default``, as this would create
+    a loop. Instead, use the group ``{ClassName}`` (e.g. ``User``) instead.
+
+For example, suppose you have a ``User`` class and want to validate that the
+username and the password are different only if all other validation passes
+(in order to avoid multiple error messages).
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # src/Acme/BlogBundle/Resources/config/validation.yml
+        Acme\BlogBundle\Entity\User:
+            group_sequence:
+                - User
+                - Strict
+            getters:
+                passwordLegal:
+                    - "True":
+                        message: "The password cannot match your username"
+                        groups: [Strict]
+            properties:
+                username:
+                    - NotBlank: ~
+                password:
+                    - NotBlank: ~
+
+    .. code-block:: php-annotations
+
+        // src/Acme/BlogBundle/Entity/User.php
+        namespace Acme\BlogBundle\Entity;
+
+        use Symfony\Component\Security\Core\User\UserInterface;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        /**
+         * @Assert\GroupSequence({"Strict", "User"})
+         */
+        class User implements UserInterface
+        {
+            /**
+            * @Assert\NotBlank
+            */
+            private $username;
+
+            /**
+            * @Assert\NotBlank
+            */
+            private $password;
+
+            /**
+             * @Assert\True(message="The password cannot match your username", groups={"Strict"})
+             */
+            public function isPasswordLegal()
+            {
+                return ($this->username !== $this->password);
+            }
+        }
+
+    .. code-block:: xml
+
+        <!-- src/Acme/BlogBundle/Resources/config/validation.xml -->
+        <class name="Acme\BlogBundle\Entity\User">
+            <property name="username">
+                <constraint name="NotBlank" />
+            </property>
+            <property name="password">
+                <constraint name="NotBlank" />
+            </property>
+            <getter property="passwordLegal">
+                <constraint name="True">
+                    <option name="message">The password cannot match your username</option>
+                    <option name="groups">
+                        <value>Strict</value>
+                    </option>
+                </constraint>
+            </getter>
+            <group-sequence>
+                <value>User</value>
+                <value>Strict</value>
+            </group-sequence>
+        </class>
+
+    .. code-block:: php
+
+        // src/Acme/BlogBundle/Entity/User.php
+        namespace Acme\BlogBundle\Entity;
+
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class User
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('username', new Assert\NotBlank());
+                $metadata->addPropertyConstraint('password', new Assert\NotBlank());
+
+                $metadata->addGetterConstraint('passwordLegal', new Assert\True(array(
+                    'message' => 'The password cannot match your first name',
+                    'groups'  => array('Strict'),
+                )));
+
+                $metadata->setGroupSequence(array('User', 'Strict'));
+            }
+        }
+
+In this example, it will first validate all constraints in the group ``User``
+(which is the same as the ``Default`` group). Only if all constraints in
+that group are valid, the second group, ``Strict``, will be validated.
+
 .. _book-validation-raw-values:
 
 Validating Values and Arrays

components/config/definition.rst

@@ -443,7 +443,7 @@ and sometimes only:
 
 By default ``connection`` would be an array in the first case and a string
 in the second making it difficult to validate. You can ensure it is always
-an array with with ``fixXmlConfig``.
+an array with ``fixXmlConfig``.
 
 You can further control the normalization process if you need to. For example,
 you may want to allow a string to be set and used as a particular key or several

components/event_dispatcher/container_aware_dispatcher.rst

@@ -56,7 +56,7 @@ Adding Subscriber Services
 ``EventSubscribers`` can be added using the
 :method:`Symfony\\Component\\EventDispatcher\\ContainerAwareEventDispatcher::addSubscriberService`
 method where the first argument is the service ID of the subscriber service,
-and the second argument is the the service's class name (which must implement
+and the second argument is the service's class name (which must implement
 :class:`Symfony\\Component\\EventDispatcher\\EventSubscriberInterface`) as follows::
 
     $dispatcher->addSubscriberService(

components/http_foundation/session_configuration.rst

@@ -79,7 +79,7 @@ examples if you wish to write your own.
 Example usage::
 
     use Symfony\Component\HttpFoundation\Session\Session;
-    use Symfony\Component\HttpFoundation\Session\Storage\SessionStorage;
+    use Symfony\Component\HttpFoundation\Session\Storage\NativeSessionStorage;
     use Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler;
 
     $storage = new NativeSessionStorage(array(), new PdoSessionHandler());

components/http_foundation/sessions.rst

@@ -329,16 +329,3 @@ Compact method to process display all flashes at once::
             echo "<div class='flash-$type'>$message</div>\n";
         }
     }
-
-.. caution::
-
-    As flash messages use a session to store the messages from one request to
-    the next one, a session will be automatically started when you read the
-    flash messages even if none already exists. To avoid that default
-    behavior, test if there is an existing session first::
-
-        if ($session->isStarted()) {
-            foreach ($session->getFlashBag()->get('warning', array()) as $message) {
-                echo "<div class='flash-warning'>$message</div>";
-            }
-        }

contributing/code/patches.rst

@@ -34,15 +34,15 @@ Set up your user information with your real name and a working email address:
 
 .. tip::
 
-    If your IDE creates configuration files inside project's directory,
+    If your IDE creates configuration files inside the project's directory,
     you can use global ``.gitignore`` file (for all projects) or
     ``.git/info/exclude`` file (per project) to ignore them. See
     `Github's documentation`_.
 
 .. tip::
 
     Windows users: when installing Git, the installer will ask what to do with
-    line endings and suggests to replace all Lf by CRLF. This is the wrong
+    line endings, and suggests replacing all LF with CRLF. This is the wrong
     setting if you wish to contribute to Symfony! Selecting the as-is method is
     your best choice, as git will convert your line feeds to the ones in the
     repository. If you have already installed Git, you can check the value of
@@ -52,8 +52,8 @@ Set up your user information with your real name and a working email address:
 
         $ git config core.autocrlf
 
-    This will return either "false", "input" or "true", "true" and "false" being
-    the wrong values. Set it to another value by typing:
+    This will return either "false", "input" or "true"; "true" and "false" being
+    the wrong values. Change it to "input" by typing:
 
     .. code-block:: bash
 
@@ -344,7 +344,7 @@ because you want early feedback on your work, add an item to todo-list:
 .. code-block:: text
 
     - [ ] finish the code
-    - [ ] gather feedback my changes
+    - [ ] gather feedback for my changes
 
 As long as you have items in the todo-list, please prefix the pull request
 title with "[WIP]".