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

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

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

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.
 

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

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,
                 )
             ),

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');
 

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

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',

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
 ------------------------------------
 

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;

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:

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

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

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:

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

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">

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 ``[email protected]``). 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: [email protected]
+            delivery_whitelist:
+               # all email addresses matching this regex will *not* be
+               # redirected to [email protected]
+               - "/@specialdomain.com$/"
+
+               # all emails sent to [email protected] won't
+               # be redirected to [email protected] too
+               - "/^[email protected]$/"
+
+    .. 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="[email protected]">
+            <!-- all email addresses matching this regex will *not* be redirected to [email protected] -->
+            <swiftmailer:delivery-whitelist-pattern>/@specialdomain.com$/</swiftmailer:delivery-whitelist-pattern>
+
+            <!-- all emails sent to [email protected] won't be redirected to [email protected] too -->
+            <swiftmailer:delivery-whitelist-pattern>/^[email protected]$/</swiftmailer:delivery-whitelist-pattern>
+        </swiftmailer:config>
+
+    .. code-block:: php
+
+        // app/config/config_dev.php
+        $container->loadFromExtension('swiftmailer', array(
+            'delivery_address'  => "[email protected]",
+            'delivery_whitelist' => array(
+                // all email addresses matching this regex will *not* be
+                // redirected to [email protected]
+                '/@specialdomain.com$/',
+
+                // all emails sent to [email protected] won't be
+                // redirected to [email protected] too
+                '/^[email protected]$/',
+            ),
+        ));
+
+In the above example all email messages will be redirected to ``[email protected]``,
+except messages sent to the ``[email protected]`` address or to any email
+address belonging to the domain ``specialdomain.com``, which will be delivered as normal.
+
 Viewing from the Web Debug Toolbar
 ----------------------------------
 

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:
 

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

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
 

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
 -----

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: