Merge branch '2.3' into 2.5

* 2.3: (45 commits)
  More xml fixes
  Xml changes and line-break changes
  Swiched mydomain and specialdomain
  Changes recommended by @cordoval
  Changes recommended by @javierguiluz
  Changed line-breaks in text
  Added improvments from @wouterj
  fixed typo in "except"
  Document whitelist option to email redirect
  Typo
  Improve assetic:watch text
  Update asset_management.rst
  Link to standard edition so users can get the app/AppKernel.php if needed.
  Update tests.rst
  ensure consistency with the note
  Update security.rst
  minor #4977 Unnecessary comma (edsonmedina)
  Wrong comma
  file extension fix
  Fixed some syntax issues in Twig Reference
  ...

Conflicts:
	cookbook/session/index.rst
	reference/twig_reference.rst

Author: weaverryan

Diff for: best_practices/business-logic.rst

@@ -56,7 +56,7 @@ The blog application needs a utility that can transform a post title (e.g.
 "Hello World") into a slug (e.g. "hello-world"). The slug will be used as
 part of the post URL.
 
-Let's, create a new ``Slugger`` class inside ``src/AppBundle/Utils/`` and
+Let's create a new ``Slugger`` class inside ``src/AppBundle/Utils/`` and
 add the following ``slugify()`` method:
 
 .. code-block:: php

Diff for: best_practices/tests.rst

@@ -30,25 +30,35 @@ A functional test can be as easy as this:
 
 .. code-block:: php
 
-    /** @dataProvider provideUrls */
-    public function testPageIsSuccessful($url)
-    {
-        $client = self::createClient();
-        $client->request('GET', $url);
+    // src/AppBundle/Tests/ApplicationAvailabilityFunctionalTest.php
+    namespace AppBundle\Tests;
 
-        $this->assertTrue($client->getResponse()->isSuccessful());
-    }
+    use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
 
-    public function provideUrls()
+    class ApplicationAvailabilityFunctionalTest extends WebTestCase
     {
-        return array(
-            array('/'),
-            array('/posts'),
-            array('/post/fixture-post-1'),
-            array('/blog/category/fixture-category'),
-            array('/archives'),
-            // ...
-        );
+        /**
+         * @dataProvider urlProvider
+         */
+        public function testPageIsSuccessful($url)
+        {
+            $client = self::createClient();
+            $client->request('GET', $url);
+
+            $this->assertTrue($client->getResponse()->isSuccessful());
+        }
+
+        public function urlProvider()
+        {
+            return array(
+                array('/'),
+                array('/posts'),
+                array('/post/fixture-post-1'),
+                array('/blog/category/fixture-category'),
+                array('/archives'),
+                // ...
+            );
+        }
     }
 
 This code checks that all the given URLs load successfully, which means that

Diff for: book/controller.rst

@@ -116,7 +116,7 @@ Controllers are also called *actions*.
 
 This controller is pretty straightforward:
 
-* *line 4*: Symfony takes advantage of PHP 5.3 namespace functionality to
+* *line 4*: Symfony takes advantage of PHP's namespace functionality to
   namespace the entire controller class. The ``use`` keyword imports the
   ``Response`` class, which the controller must return.
 

Diff for: book/from_flat_php_to_symfony2.rst

@@ -649,7 +649,7 @@ A routing configuration map provides this information in a readable format:
 
 Now that Symfony is handling all the mundane tasks, the front controller
 is dead simple. And since it does so little, you'll never have to touch
-it once it's created (and if you use a Symfony distribution, you won't
+it once it's created (and if you use a `Symfony distribution`_, you won't
 even need to create it!)::
 
     // web/app.php
@@ -764,3 +764,4 @@ Learn more from the Cookbook
 .. _`Twig`: http://twig.sensiolabs.org
 .. _`Varnish`: https://www.varnish-cache.org/
 .. _`PHPUnit`: http://www.phpunit.de
+.. _`Symfony distribution`: https://github.com/symfony/symfony-standard

Diff for: book/security.rst

@@ -14,11 +14,11 @@ is both flexible and (hopefully) fun to work with.
 Since there's a lot to talk about, this chapter is organized into a few big
 sections:
 
-1) Initial ``security.yml`` setup (*authentication*);
+#. Initial ``security.yml`` setup (*authentication*);
 
-2) Denying access to your app (*authorization*);
+#. Denying access to your app (*authorization*);
 
-3) Fetching the current User object
+#. Fetching the current User object.
 
 These are followed by a number of small (but still captivating) sections,
 like :ref:`logging out <book-security-logging-out>` and :ref:`encoding user passwords <security-encoding-password>`.
@@ -492,7 +492,7 @@ else, you'll want to encode their passwords. The best algorithm to use is
 
             'encoders' => array(
                 'Symfony\Component\Security\Core\User\User' => array(
-                    'algorithm' => 'plaintext',
+                    'algorithm' => 'bcrypt',
                     'cost' => 12,
                 )
             ),

Diff for: book/testing.rst

@@ -619,7 +619,8 @@ and pass it a ``Link`` object::
 Forms
 ~~~~~
 
-Just like links, you select forms with the ``selectButton()`` method::
+Forms can be selected using their buttons, which can be selected with the
+``selectButton()`` method, just like links::
 
     $buttonCrawlerNode = $crawler->selectButton('submit');
 

Diff for: book/validation.rst

@@ -1252,7 +1252,7 @@ By calling ``validate`` on the validator, you can pass in a raw value and
 the constraint object that you want to validate that value against. A full
 list of the available constraints - as well as the full class name for each
 constraint - is available in the :doc:`constraints reference </reference/constraints>`
-section .
+section.
 
 The ``validate`` method returns a :class:`Symfony\\Component\\Validator\\ConstraintViolationList`
 object, which acts just like an array of errors. Each error in the collection

Diff for: components/class_loader/map_class_loader.rst

@@ -25,7 +25,7 @@ Usage
 Using it is as easy as passing your mapping to its constructor when creating
 an instance of the ``MapClassLoader`` class::
 
-    require_once '/path/to/src/Symfony/Component/ClassLoader/MapClassLoader';
+    require_once '/path/to/src/Symfony/Component/ClassLoader/MapClassLoader.php';
 
     $mapping = array(
         'Foo' => '/path/to/Foo',

Diff for: components/console/events.rst

@@ -20,6 +20,11 @@ the wheel, it uses the Symfony EventDispatcher component to do the work::
     $application->setDispatcher($dispatcher);
     $application->run();
 
+.. caution::
+
+    Console events are only triggered by the main command being executed.
+    Commands called by the main command will not trigger any event.
+
 The ``ConsoleEvents::COMMAND`` Event
 ------------------------------------
 

Diff for: components/http_foundation/introduction.rst

@@ -480,7 +480,7 @@ Serving Files
 When sending a file, you must add a ``Content-Disposition`` header to your
 response. While creating this header for basic file downloads is easy, using
 non-ASCII filenames is more involving. The
-:method:`Symfony\\Component\\HttpFoundation\\Response::makeDisposition`
+:method:`Symfony\\Component\\HttpFoundation\\ResponseHeaderBag::makeDisposition`
 abstracts the hard work behind a simple API::
 
     use Symfony\Component\HttpFoundation\ResponseHeaderBag;

Diff for: components/translation/usage.rst

@@ -217,7 +217,7 @@ recommended format. These files are parsed by one of the loader classes.
                 'symfony.is.great'    => 'Symfony is great',
                 'symfony.is.amazing'  => 'Symfony is amazing',
                 'symfony.has.bundles' => 'Symfony has bundles',
-                'user.login'           => 'Login',
+                'user.login'          => 'Login',
             );
 
 .. _component-translation-pluralization:

Diff for: components/yaml/yaml_format.rst

@@ -228,14 +228,14 @@ The following YAML is equivalent to the following PHP code:
 .. code-block:: php
 
     array(
-      'symfony 1.0' => array(
-        'PHP'    => 5.0,
-        'Propel' => 1.2,
-      ),
-      'symfony 1.2' => array(
-        'PHP'    => 5.2,
-        'Propel' => 1.3,
-      ),
+        'symfony 1.0' => array(
+            'PHP'    => 5.0,
+            'Propel' => 1.2,
+        ),
+        'symfony 1.2' => array(
+            'PHP'    => 5.2,
+            'Propel' => 1.3,
+        ),
     );
 
 There is one important thing you need to remember when using indentation in a

Diff for: cookbook/assetic/asset_management.rst

@@ -540,12 +540,16 @@ need to dump them manually. To do so, run the following:
 
 This physically writes all of the asset files you need for your ``dev``
 environment. The big disadvantage is that you need to run this each time
-you update an asset. Fortunately, by passing the ``--watch`` option, the
-command will automatically regenerate assets *as they change*:
+you update an asset. Fortunately, by using the ``assetic:watch`` command,
+assets will be regenerated automatically *as they change*:
 
 .. code-block:: bash
 
-    $ php app/console assetic:dump --watch
+    $ php app/console assetic:watch
+
+The ``assetic:watch`` command was introduced in AsseticBundle 2.4. In prior 
+versions, you had to use the ``--watch`` option of the ``assetic:dump`` 
+command for the same behavior.
 
 Since running this command in the ``dev`` environment may generate a bunch
 of files, it's usually a good idea to point your generated asset files to

Diff for: cookbook/bundles/best_practices.rst

@@ -29,10 +29,9 @@ Bundle Name
 -----------
 
 A bundle is also a PHP namespace. The namespace must follow the technical
-interoperability `standards`_ for PHP 5.3 namespaces and class names: it
-starts with a vendor segment, followed by zero or more category segments, and
-it ends with the namespace short name, which must end with a ``Bundle``
-suffix.
+interoperability `standards`_ for PHP namespaces and class names: it starts
+with a vendor segment, followed by zero or more category segments, and it ends
+with the namespace short name, which must end with a ``Bundle`` suffix.
 
 A namespace becomes a bundle as soon as you add a bundle class to it. The
 bundle class name must follow these simple rules:

Diff for: cookbook/cache/varnish.rst

@@ -72,11 +72,10 @@ If you know for sure that the backend never uses sessions or basic
 authentication, have varnish remove the corresponding header from requests to
 prevent clients from bypassing the cache. In practice, you will need sessions
 at least for some parts of the site, e.g. when using forms with
-:ref:`CSRF Protection <forms-csrf>`. In this situation, make sure to only
-start a session when actually needed, and clear the session when it is no
-longer needed. Alternatively, you can look into :doc:`../cache/form_csrf_caching`.
-
-.. todo link "only start a session when actually needed" to cookbook/session/avoid_session_start once https://github.com/symfony/symfony-docs/pull/4661 is merged
+:ref:`CSRF Protection <forms-csrf>`. In this situation, make sure to
+:doc:`only start a session when actually needed </cookbook/session/avoid_session_start>`
+and clear the session when it is no longer needed. Alternatively, you can look
+into :doc:`/cookbook/cache/form_csrf_caching`.
 
 Cookies created in Javascript and used only in the frontend, e.g. when using
 Google analytics are nonetheless sent to the server. These cookies are not

Diff for: cookbook/doctrine/file_uploads.rst

@@ -181,7 +181,7 @@ rules::
 
     .. code-block:: xml
 
-        <!-- src/AppBundle/Resources/config/validation.yml -->
+        <!-- src/AppBundle/Resources/config/validation.xml -->
         <class name="AppBundle\Entity\Document">
             <property name="file">
                 <constraint name="File">

Diff for: cookbook/email/dev_environment.rst

@@ -11,7 +11,7 @@ can easily achieve this through configuration settings without having to
 make any changes to your application's code at all. There are two main
 choices when it comes to handling email during development: (a) disabling the
 sending of email altogether or (b) sending all email to a specific
-address.
+address (with optional exceptions).
 
 Disabling Sending
 -----------------
@@ -119,6 +119,67 @@ the replaced address, so you can still see who it would have been sent to.
     These are ``X-Swift-Cc`` and ``X-Swift-Bcc`` for the ``CC`` and ``BCC``
     addresses respectively.
 
+Sending to a Specified Address but with Exceptions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Suppose you want to have all email redirected to a specific address,
+(like in the above scenario to ``dev@example.com``). But then you may want
+email sent to some specific email addresses to go through after all, and
+not be redirected (even if it is in the dev environment). This can be done
+by adding the ``delivery_whitelist`` option:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config_dev.yml
+        swiftmailer:
+            delivery_address: dev@example.com
+            delivery_whitelist:
+               # all email addresses matching this regex will *not* be
+               # redirected to dev@example.com
+               - "/@specialdomain.com$/"
+
+               # all emails sent to admin@mydomain.com won't
+               # be redirected to dev@example.com too
+               - "/^admin@mydomain.com$/"
+
+    .. code-block:: xml
+
+        <!-- app/config/config_dev.xml -->
+
+        <?xml version="1.0" charset="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer">
+
+        <swiftmailer:config delivery-address="dev@example.com">
+            <!-- all email addresses matching this regex will *not* be redirected to dev@example.com -->
+            <swiftmailer:delivery-whitelist-pattern>/@specialdomain.com$/</swiftmailer:delivery-whitelist-pattern>
+
+            <!-- all emails sent to admin@mydomain.com won't be redirected to dev@example.com too -->
+            <swiftmailer:delivery-whitelist-pattern>/^admin@mydomain.com$/</swiftmailer:delivery-whitelist-pattern>
+        </swiftmailer:config>
+
+    .. code-block:: php
+
+        // app/config/config_dev.php
+        $container->loadFromExtension('swiftmailer', array(
+            'delivery_address'  => "dev@example.com",
+            'delivery_whitelist' => array(
+                // all email addresses matching this regex will *not* be
+                // redirected to dev@example.com
+                '/@specialdomain.com$/',
+
+                // all emails sent to admin@mydomain.com won't be
+                // redirected to dev@example.com too
+                '/^admin@mydomain.com$/',
+            ),
+        ));
+
+In the above example all email messages will be redirected to ``dev@example.com``,
+except messages sent to the ``admin@mydomain.com`` address or to any email
+address belonging to the domain ``specialdomain.com``, which will be delivered as normal.
+
 Viewing from the Web Debug Toolbar
 ----------------------------------
 

Diff for: cookbook/event_dispatcher/before_after_filters.rst

@@ -156,7 +156,7 @@ your listener to be called just before any controller is executed.
         # app/config/services.yml
         services:
             app.tokens.action_listener:
-                class: AappBundle\EventListener\TokenListener
+                class: AppBundle\EventListener\TokenListener
                 arguments: ["%tokens%"]
                 tags:
                     - { name: kernel.event_listener, event: kernel.controller, method: onKernelController }
@@ -240,7 +240,7 @@ if it's found::
         $response->headers->set('X-CONTENT-HASH', $hash);
     }
 
-Finally, a second "tag" is needed on the service definition to notify Symfony
+Finally, a second "tag" is needed in the service definition to notify Symfony
 that the ``onKernelResponse`` event should be notified for the ``kernel.response``
 event:
 

Diff for: cookbook/form/create_form_type_extension.rst

@@ -92,7 +92,7 @@ For more information on what those methods do, you can refer to the
 cookbook article.
 
 Registering your Form Type Extension as a Service
---------------------------------------------------
+-------------------------------------------------
 
 The next step is to make Symfony aware of your extension. All you
 need to do is to declare it as a service by using the ``form.type_extension``
@@ -290,7 +290,7 @@ Specifically, you need to override the ``file_widget`` block:
     information.
 
 Using the Form Type Extension
-------------------------------
+-----------------------------
 
 From now on, when adding a field of type ``file`` in your form, you can
 specify an ``image_path`` option that will be used to display an image

Diff for: cookbook/form/dynamic_form_modification.rst

@@ -712,10 +712,11 @@ all of this, use a listener::
 
     use Symfony\Component\Form\FormBuilderInterface;
     use Symfony\Component\Form\FormEvents;
+    use Symfony\Component\Form\FormEvent;
 
     public function buildForm(FormBuilderInterface $builder, array $options)
     {
-        $builder->addEventListener(FormEvents::POST_SUBMIT, function ($event) {
+        $builder->addEventListener(FormEvents::POST_SUBMIT, function (FormEvent $event) {
             $event->stopPropagation();
         }, 900); // Always set a higher priority than ValidationListener
 

Diff for: cookbook/logging/monolog.rst

@@ -4,8 +4,8 @@
 How to Use Monolog to Write Logs
 ================================
 
-Monolog_ is a logging library for PHP 5.3 used by Symfony. It is
-inspired by the Python LogBook library.
+Monolog_ is a logging library for PHP used by Symfony. It is inspired by the
+Python LogBook library.
 
 Usage
 -----

Diff for: cookbook/logging/monolog_email.rst

@@ -23,7 +23,7 @@ it is broken down.
                     action_level: critical
                     # to also log 400 level errors (but not 404's):
                     # action_level: error
-                    # excluded_404:
+                    # excluded_404s:
                     #     - ^/
                     handler:      buffered
                 buffered: