Merge branch '2.3' into 2.4

Conflicts:
	cookbook/security/voters.rst
	cookbook/service_container/scopes.rst

Author: weaverryan

book/forms.rst

@@ -281,7 +281,7 @@ Submitting Forms with Multiple Buttons
 
 When your form contains more than one submit button, you will want to check
 which of the buttons was clicked to adapt the program flow in your controller.
-Let's add a second button with the caption "Save and add" to our form::
+To do this, add a second button with the caption "Save and add" to your form::
 
     $form = $this->createFormBuilder($task)
         ->add('task', 'text')
@@ -552,8 +552,8 @@ Groups based on the Clicked Button
 When your form contains multiple submit buttons, you can change the validation
 group depending on which button is used to submit the form. For example,
 consider a form in a wizard that lets you advance to the next step or go back
-to the previous step. Let's assume also that when returning to the previous
-step, the data of the form should be saved, but not validated.
+to the previous step. Also assume that when returning to the previous step,
+the data of the form should be saved, but not validated.
 
 First, we need to add the two buttons to the form::
 

book/from_flat_php_to_symfony2.rst

@@ -75,8 +75,6 @@ to maintain. There are several problems that need to be addressed:
     tied to MySQL. Though not covered here, Symfony2 fully integrates `Doctrine`_,
     a library dedicated to database abstraction and mapping.
 
-Let's get to work on solving these problems and more.
-
 Isolating the Presentation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -676,8 +674,8 @@ Where Symfony2 Delivers
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 In the upcoming chapters, you'll learn more about how each piece of Symfony
-works and the recommended organization of a project. For now, let's see how
-migrating the blog from flat PHP to Symfony2 has improved life:
+works and the recommended organization of a project. For now, have a look
+at how migrating the blog from flat PHP to Symfony2 has improved life:
 
 * Your application now has **clear and consistently organized code** (though
   Symfony doesn't force you into this). This promotes **reusability** and

book/propel.rst

@@ -55,10 +55,10 @@ configuration file (``config.yml``):
 
     propel:
         dbal:
-            driver:     "%database_driver%"
-            user:       "%database_user%"
-            password:   "%database_password%"
-            dsn:        "%database_driver%:host=%database_host%;dbname=%database_name%;charset=%database_charset%"
+            driver:   "%database_driver%"
+            user:     "%database_user%"
+            password: "%database_password%"
+            dsn:      "%database_driver%:host=%database_host%;dbname=%database_name%;charset=%database_charset%"
 
 Now that Propel knows about your database, Symfony2 can create the database for
 you:

book/routing.rst

@@ -432,6 +432,13 @@ match, giving the ``page`` parameter a value of ``2``. Perfect.
 | /blog/2            | blog  | {page} = 2            |
 +--------------------+-------+-----------------------+
 
+.. caution::
+
+    Of course, you can have more than one optional placeholder (e.g. ``/blog/{slug}/{page}``),
+    but everything after an optional placeholder must be optional. For example,
+    ``/{page}/blog`` is a valid path, but ``page`` will always be required
+    (i.e. simply ``/blog`` will not match this route).
+
 .. tip::
 
     Routes with optional parameters at the end will not match on requests

book/security.rst

@@ -45,7 +45,7 @@ authentication (i.e. the old-school username/password box):
         security:
             firewalls:
                 secured_area:
-                    pattern:    ^/
+                    pattern:   ^/
                     anonymous: ~
                     http_basic:
                         realm: "Secured Demo Area"
@@ -148,8 +148,8 @@ that looks like the following:
 * All URLs *not* matching ``/admin/*`` are accessible by all users (and the
   user is never prompted to log in).
 
-Let's look briefly at how security works and how each part of the configuration
-comes into play.
+Read this short summary about how security works and how each part of the
+configuration comes into play.
 
 How Security Works: Authentication and Authorization
 ----------------------------------------------------
@@ -300,11 +300,11 @@ First, enable form login under your firewall:
         security:
             firewalls:
                 secured_area:
-                    pattern:    ^/
+                    pattern:   ^/
                     anonymous: ~
                     form_login:
-                        login_path:  login
-                        check_path:  login_check
+                        login_path: login
+                        check_path: login_check
 
     .. code-block:: xml
 
@@ -373,10 +373,10 @@ submission (i.e.  ``/login_check``):
 
         # app/config/routing.yml
         login:
-            path:   /login
-            defaults:  { _controller: AcmeSecurityBundle:Security:login }
+            path:     /login
+            defaults: { _controller: AcmeSecurityBundle:Security:login }
         login_check:
-            path:   /login_check
+            path: /login_check
 
     .. code-block:: xml
 
@@ -537,7 +537,7 @@ And that's it! When you submit the form, the security system will automatically
 check the user's credentials and either authenticate the user or send the
 user back to the login form where the error can be displayed.
 
-Let's review the whole process:
+To review the whole process:
 
 #. The user tries to access a resource that is protected;
 #. The firewall initiates the authentication process by redirecting the
@@ -633,8 +633,8 @@ see :doc:`/cookbook/security/form_login`.
 
             firewalls:
                 login_firewall:
-                    pattern:    ^/login$
-                    anonymous:  ~
+                    pattern:   ^/login$
+                    anonymous: ~
                 secured_area:
                     pattern:    ^/
                     form_login: ~
@@ -1211,13 +1211,14 @@ aren't stored anywhere in a database. The actual user object is provided
 by Symfony (:class:`Symfony\\Component\\Security\\Core\\User\\User`).
 
 .. tip::
+
     Any user provider can load users directly from configuration by specifying
     the ``users`` configuration parameter and listing the users beneath it.
 
 .. caution::
 
     If your username is completely numeric (e.g. ``77``) or contains a dash
-    (e.g. ``user-name``), you should use that alternative syntax when specifying
+    (e.g. ``user-name``), you should use an alternative syntax when specifying
     users in YAML:
 
     .. code-block:: yaml

book/translation.rst

@@ -449,8 +449,8 @@ by the routing system using the special ``_locale`` parameter:
     .. code-block:: yaml
 
         contact:
-            path:      /{_locale}/contact
-            defaults:  { _controller: AcmeDemoBundle:Contact:index, _locale: en }
+            path:     /{_locale}/contact
+            defaults: { _controller: AcmeDemoBundle:Contact:index }
             requirements:
                 _locale: en|fr|de
 
@@ -464,7 +464,6 @@ by the routing system using the special ``_locale`` parameter:
 
             <route id="contact" path="/{_locale}/contact">
                 <default key="_controller">AcmeDemoBundle:Contact:index</default>
-                <default key="_locale">en</default>
                 <requirement key="_locale">en|fr|de</requirement>
             </route>
         </routes>
@@ -475,12 +474,15 @@ by the routing system using the special ``_locale`` parameter:
         use Symfony\Component\Routing\Route;
 
         $collection = new RouteCollection();
-        $collection->add('contact', new Route('/{_locale}/contact', array(
-            '_controller' => 'AcmeDemoBundle:Contact:index',
-            '_locale'     => 'en',
-        ), array(
-            '_locale'     => 'en|fr|de',
-        )));
+        $collection->add('contact', new Route(
+            '/{_locale}/contact',
+            array(
+                '_controller' => 'AcmeDemoBundle:Contact:index',
+            ),
+            array(
+                '_locale'     => 'en|fr|de',
+            )
+        ));
 
         return $collection;
 

components/config/definition.rst

@@ -21,14 +21,14 @@ applied to it (like: "the value for ``auto_connect`` must be a boolean value"):
     default_connection: mysql
     connections:
         mysql:
-            host: localhost
-            driver: mysql
+            host:     localhost
+            driver:   mysql
             username: user
             password: pass
         sqlite:
-            host: localhost
-            driver: sqlite
-            memory: true
+            host:     localhost
+            driver:   sqlite
+            memory:   true
             username: user
             password: pass
 
@@ -470,9 +470,9 @@ in this config:
 .. code-block:: yaml
 
     connection:
-        name: my_mysql_connection
-        host: localhost
-        driver: mysql
+        name:     my_mysql_connection
+        host:     localhost
+        driver:   mysql
         username: user
         password: pass
 

components/console/introduction.rst

@@ -27,7 +27,7 @@ You can install the component in 2 different ways:
     configured with an ANSI driver and your console commands invoke other scripts which
     emit ANSI color sequences, they will be shown as raw escape characters.
 
-    To enable ANSI colour support for Windows, please install `ANSICON`_.
+    To enable ANSI color support for Windows, please install `ANSICON`_.
 
 Creating a basic Command
 ------------------------
@@ -529,4 +529,4 @@ Learn More!
 * :doc:`/components/console/events`
 
 .. _Packagist: https://packagist.org/packages/symfony/console
-.. _ANSICON: https://github.com/adoxa/ansicon/downloads
+.. _ANSICON: https://github.com/adoxa/ansicon/releases

components/dependency_injection/parameters.rst

@@ -134,8 +134,8 @@ making the class of a service a parameter:
 
         services:
             mailer:
-                class:     '%mailer.class%'
-                arguments: ['%mailer.transport%']
+                class:     "%mailer.class%"
+                arguments: ["%mailer.transport%"]
 
     .. code-block:: xml
 

components/dependency_injection/parentservices.rst

@@ -62,7 +62,7 @@ The service config for these classes would look something like this:
             my_email_formatter:
                 # ...
             newsletter_manager:
-                class:     "%newsletter_manager.class%"
+                class: "%newsletter_manager.class%"
                 calls:
                     - [setMailer, ["@my_mailer"]]
                     - [setEmailFormatter, ["@my_email_formatter"]]
@@ -196,7 +196,7 @@ a parent for a service.
                     - [setEmailFormatter, ["@my_email_formatter"]]
 
             newsletter_manager:
-                class:     "%newsletter_manager.class%"
+                class:  "%newsletter_manager.class%"
                 parent: mail_manager
 
             greeting_card_manager:
@@ -321,13 +321,13 @@ to the ``NewsletterManager`` class, the config would look like this:
                     - [setEmailFormatter, ["@my_email_formatter"]]
 
             newsletter_manager:
-                class:     "%newsletter_manager.class%"
+                class:  "%newsletter_manager.class%"
                 parent: mail_manager
                 calls:
                     - [setMailer, ["@my_alternative_mailer"]]
 
             greeting_card_manager:
-                class:     "%greeting_card_manager.class%"
+                class:  "%greeting_card_manager.class%"
                 parent: mail_manager
 
     .. code-block:: xml

components/dependency_injection/types.rst

@@ -184,7 +184,7 @@ Another possibility is just setting public fields of the class directly::
             my_mailer:
                 # ...
             newsletter_manager:
-                class:     NewsletterManager
+                class: NewsletterManager
                 properties:
                     mailer: "@my_mailer"
 

components/filesystem.rst

@@ -162,8 +162,8 @@ the mode of a file. The fourth argument is a boolean recursive option::
 Remove
 ~~~~~~
 
-:method:`Symfony\\Component\\Filesystem\\Filesystem::remove` let's you remove
-files, symlink, directories easily::
+:method:`Symfony\\Component\\Filesystem\\Filesystem::remove` is used to remove
+files, symlinks, directories easily::
 
     $fs->remove(array('symlink', '/path/to/directory', 'activity.log'));
 

components/http_foundation/session_configuration.rst

@@ -7,7 +7,7 @@ Configuring Sessions and Save Handlers
 
 This section deals with how to configure session management and fine tune it
 to your specific needs. This documentation covers save handlers, which
-store and retrieve session data, and configuring session behaviour.
+store and retrieve session data, and configuring session behavior.
 
 Save Handlers
 ~~~~~~~~~~~~~
@@ -57,7 +57,7 @@ Example usage::
 
     Native save handlers provide a quick solution to session storage, however, in complex systems
     where you need more control, custom save handlers may provide more freedom and flexibility.
-    Symfony2 provides several implementations which you may further customise as required.
+    Symfony2 provides several implementations which you may further customize as required.
 
 Custom Save Handlers
 --------------------

components/routing/introduction.rst

@@ -25,7 +25,7 @@ In order to set up a basic routing system you need three parts:
 * A :class:`Symfony\\Component\\Routing\\RequestContext`, which has information about the request
 * A :class:`Symfony\\Component\\Routing\\Matcher\\UrlMatcher`, which performs the mapping of the request to a single route
 
-Let's see a quick example. Notice that this assumes that you've already configured
+Here is a quick example. Notice that this assumes that you've already configured
 your autoloader to load the Routing component::
 
     use Symfony\Component\Routing\Matcher\UrlMatcher;

components/serializer.rst

@@ -129,7 +129,7 @@ method on the normalizer definition::
 Deserializing an Object
 -----------------------
 
-Let's see now how to do the exactly the opposite. This time, the information
+You'll now learn how to do the exact opposite. This time, the information
 of the ``Person`` class would be encoded in XML format::
 
     $data = <<<EOF

cookbook/assetic/apply_to_option.rst

@@ -6,7 +6,7 @@ How to Apply an Assetic Filter to a Specific File Extension
 
 Assetic filters can be applied to individual files, groups of files or even,
 as you'll see here, files that have a specific extension. To show you how
-to handle each option, let's suppose that you want to use Assetic's CoffeeScript
+to handle each option, suppose that you want to use Assetic's CoffeeScript
 filter, which compiles CoffeeScript files into JavaScript.
 
 The main configuration is just the paths to coffee, node and node_modules.
@@ -20,9 +20,9 @@ An example configuration might look like this:
         assetic:
             filters:
                 coffee:
-                    bin: /usr/bin/coffee
-                    node: /usr/bin/node
-                    node_paths: [ /usr/lib/node_modules/ ]
+                    bin:        /usr/bin/coffee
+                    node:       /usr/bin/node
+                    node_paths: [/usr/lib/node_modules/]
 
     .. code-block:: xml
 
@@ -130,10 +130,10 @@ applied to all ``.coffee`` files:
         assetic:
             filters:
                 coffee:
-                    bin: /usr/bin/coffee
-                    node: /usr/bin/node
-                    node_paths: [ /usr/lib/node_modules/ ]
-                    apply_to: "\.coffee$"
+                    bin:        /usr/bin/coffee
+                    node:       /usr/bin/node
+                    node_paths: [/usr/lib/node_modules/]
+                    apply_to:   "\.coffee$"
 
     .. code-block:: xml