Merge branch '2.3' into 2.7

Conflicts:
	book/security.rst

Author: wouterj

Diff for: best_practices/tests.rst

@@ -113,12 +113,13 @@ pure JavaScript-based testing tools.
 Learn More about Functional Tests
 ---------------------------------
 
-Consider using `Faker`_ and `Alice`_ libraries to generate real-looking data
-for your test fixtures.
+Consider using the `HautelookAliceBundle`_ to generate real-looking data for
+your test fixtures using `Faker`_ and `Alice`_.
 
 .. _`Faker`: https://github.com/fzaninotto/Faker
 .. _`Alice`: https://github.com/nelmio/alice
 .. _`PhpUnit`: https://phpunit.de/
 .. _`PhpSpec`: http://www.phpspec.net/
 .. _`Mink`: http://mink.behat.org
 .. _`smoke testing`: https://en.wikipedia.org/wiki/Smoke_testing_(software)
+.. _`HautelookAliceBundle`: https://github.com/hautelook/AliceBundle

Diff for: book/security.rst

@@ -513,7 +513,7 @@ else, you'll want to encode their passwords. The best algorithm to use is
 .. include:: /cookbook/security/_ircmaxwell_password-compat.rst.inc
 
 Of course, your users' passwords now need to be encoded with this exact algorithm.
-For hardcoded users, since 2.7 you can use the built-in command :
+For hardcoded users, since 2.7 you can use the built-in command:
 
 .. code-block:: bash
 

Diff for: components/security/secure_tools.rst

@@ -1,5 +1,5 @@
-Securely Comparing Strings and Generating Random Numbers
-========================================================
+Securely Comparing Strings and Generating Random Values
+=======================================================
 
 The Symfony Security component comes with a collection of nice utilities
 related to security. These utilities are used by Symfony, but you should
@@ -21,45 +21,40 @@ algorithm; you can use the same strategy in your own code thanks to the
     // is some known string (e.g. password) equal to some user input?
     $bool = StringUtils::equals($knownString, $userInput);
 
-Generating a Secure random Number
+Generating a Secure Random String
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Whenever you need to generate a secure random number, you are highly
-encouraged to use the Symfony
-:class:`Symfony\\Component\\Security\\Core\\Util\\SecureRandom` class::
+Whenever you need to generate a secure random string, you are highly
+encouraged to use the :phpfunction:`random_bytes` function::
 
-    use Symfony\Component\Security\Core\Util\SecureRandom;
+    $random = random_bytes(10);
 
-    $generator = new SecureRandom();
-    $random = $generator->nextBytes(10);
+The function returns a random string, suitable for cryptographic use, of
+the number bytes passed as an argument (10 in the above example).
 
-The
-:method:`Symfony\\Component\\Security\\Core\\Util\\SecureRandom::nextBytes`
-method returns a random string composed of the number of characters passed as
-an argument (10 in the above example).
+.. tip::
 
-The SecureRandom class works better when OpenSSL is installed. But when it's
-not available, it falls back to an internal algorithm, which needs a seed file
-to work correctly. Just pass a file name to enable it::
+    The ``random_bytes()`` function returns a binary string which may contain
+    the ``\0`` character. This can cause trouble in several common scenarios,
+    such as storing this value in a database or including it as part of the
+    URL. The solution is to encode or hash the value returned by
+    ``random_bytes()`` (to do that, you can use a simple ``base64_encode()``
+    PHP function).
 
-    use Symfony\Component\Security\Core\Util\SecureRandom;
+Generating a Secure Random Number
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    $generator = new SecureRandom('/some/path/to/store/the/seed.txt');
+If you need to generate a cryptographically secure random integer, you should
+use the :phpfunction:`random_int` function::
 
-    $random = $generator->nextBytes(10);
-    $hashedRandom = md5($random); // see tip below
+    $random = random_int(1, 10);
 
 .. note::
 
-    If you're using the Symfony Framework, you can get a secure random number
-    generator via the ``security.secure_random`` service.
-
-.. tip::
-
-    The ``nextBytes()`` method returns a binary string which may contain the
-    ``\0`` character. This can cause trouble in several common scenarios, such
-    as storing this value in a database or including it as part of the URL. The
-    solution is to hash the value returned by ``nextBytes()`` (to do that, you
-    can use a simple ``md5()`` PHP function).
+    PHP 7 and up provide the ``random_bytes()`` and ``random_int()`` functions
+    natively, for older versions of PHP a polyfill is provided by the
+    `Symfony Polyfill Component`_ and the `paragonie/random_compat package`_.
 
 .. _`Timing attack`: https://en.wikipedia.org/wiki/Timing_attack
+.. _`Symfony Polyfill Component`: https://github.com/symfony/polyfill
+.. _`paragonie/random_compat package`: https://github.com/paragonie/random_compat

Diff for: cookbook/email/gmail.rst

@@ -8,11 +8,6 @@ During development, instead of using a regular SMTP server to send emails, you
 might find using Gmail easier and more practical. The SwiftmailerBundle makes
 it really easy.
 
-.. tip::
-
-    Instead of using your regular Gmail account, it's of course recommended
-    that you create a special account.
-
 In the development configuration file, change the ``transport`` setting to
 ``gmail`` and set the ``username`` and ``password`` to the Google credentials:
 
@@ -55,33 +50,87 @@ In the development configuration file, change the ``transport`` setting to
             'password'  => 'your_gmail_password',
         ));
 
-You're done!
-
 .. tip::
 
-    If you are using the Symfony Standard Edition, configure the parameters in ``parameters.yml``:
+    It's more convenient to configure these options in the ``parameters.yml``
+    file:
 
     .. code-block:: yaml
 
         # app/config/parameters.yml
         parameters:
             # ...
-            mailer_transport: gmail
-            mailer_host:      ~
-            mailer_user:      your_gmail_username
-            mailer_password:  your_gmail_password
-
-.. note::
-
-    The ``gmail`` transport is simply a shortcut that uses the ``smtp`` transport
-    and sets ``encryption``, ``auth_mode`` and ``host`` to work with Gmail.
-
-.. note::
-
-    Depending on your Gmail account settings, you may get authentication errors
-    within your app. If your Gmail account uses 2-Step-Verification, you should
-    `generate an App password`_ to use for your ``mailer_password`` parameter.
-    You should also ensure that you `allow less secure apps to access your Gmail account`_.
+            mailer_user:     your_gmail_username
+            mailer_password: your_gmail_password
+
+    .. configuration-block::
+
+        .. code-block:: yaml
+
+            # app/config/config_dev.yml
+            swiftmailer:
+                transport: gmail
+                username:  '%mailer_user%'
+                password:  '%mailer_password%'
+
+        .. code-block:: xml
+
+            <!-- app/config/config_dev.xml -->
+            <?xml version="1.0" encoding="UTF-8" ?>
+            <container xmlns="http://symfony.com/schema/dic/services"
+                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    http://symfony.com/schema/dic/services/services-1.0.xsd
+                    http://symfony.com/schema/dic/swiftmailer
+                    http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
+
+                <!-- ... -->
+                <swiftmailer:config
+                    transport="gmail"
+                    username="%mailer_user%"
+                    password="%mailer_password%"
+                />
+            </container>
+
+        .. code-block:: php
+
+            // app/config/config_dev.php
+            $container->loadFromExtension('swiftmailer', array(
+                'transport' => 'gmail',
+                'username'  => '%mailer_user%',
+                'password'  => '%mailer_password%',
+            ));
+
+Redefining the Default Configuration Parameters
+-----------------------------------------------
+
+The ``gmail`` transport is simply a shortcut that uses the ``smtp`` transport
+and sets these options:
+
+==============  ==================
+Option          Value
+==============  ==================
+``encryption``  ``ssl``
+``auth_mode``   ``login``
+``host``        ``smtp.gmail.com``
+==============  ==================
+
+If your application uses ``tls`` encryption or ``oauth`` authentication, you
+must override the default options by defining the ``encryption`` and ``auth_mode``
+parameters.
+
+If you are using 2-Step-Verification, you must `generate an App password`_ and
+use this as your ``mailer_password`` value.
+
+If your Gmail account uses 2-Step-Verification, you must `generate an App password`_
+and use it as the value of the ``mailer_password`` parameter. You must also ensure
+that you `allow less secure apps to access your Gmail account`_.
+
+.. seealso::
+
+    see the :doc:`Swiftmailer configuration reference </reference/configuration/swiftmailer>`
+    for more details.
 
 .. _`generate an App password`: https://support.google.com/accounts/answer/185833
 .. _`allow less secure apps to access your Gmail account`: https://support.google.com/accounts/answer/6010255

Diff for: cookbook/request/load_balancer_reverse_proxy.rst

@@ -83,7 +83,7 @@ In this case, you'll need to - *very carefully* - trust *all* proxies.
        // web/app.php
 
        // ...
-       Request::setTrustedProxies(array($request->server->get('REMOTE_ADDR')));
+       Request::setTrustedProxies(array('127.0.0.1', $request->server->get('REMOTE_ADDR')));
 
        $response = $kernel->handle($request);
        // ...

Diff for: cookbook/routing/redirect_trailing_slash.rst

@@ -37,6 +37,26 @@ system, as explained below:
 
 .. configuration-block::
 
+    .. code-block:: php-annotations
+
+        // src/AppBundle/Controller/RedirectingController.php
+        namespace AppBundle\Controller;
+
+        use Symfony\Bundle\FrameworkBundle\Controller\Controller;
+        use Symfony\Component\HttpFoundation\Request;
+
+        class RedirectingController extends Controller
+        {
+            /**
+             * @Route("/{url}", name="remove_trailing_slash",
+             *     requirements={"url" = ".*\/$"}, methods={"GET"})
+             */
+            public function removeTrailingSlashAction(Request $request)
+            {
+                // ...
+            }
+        }
+
     .. code-block:: yaml
 
         remove_trailing_slash:

Diff for: create_framework/unit_testing.rst

@@ -26,6 +26,12 @@ using `PHPUnit`_. Create a PHPUnit configuration file in
                 <directory>./tests</directory>
             </testsuite>
         </testsuites>
+
+        <filter>
+            <whitelist processUncoveredFilesFromWhitelist="true">
+                <directory suffix=".php">./src</directory>
+            </whitelist>
+        </filter>
     </phpunit>
 
 This configuration defines sensible defaults for most PHPUnit settings; more
@@ -180,6 +186,12 @@ Open ``example.com/cov/src/Simplex/Framework.php.html`` in a browser and check
 that all the lines for the Framework class are green (it means that they have
 been visited when the tests were executed).
 
+Alternatively you can output the result directly to the console:
+
+.. code-block:: bash
+
+    $ phpunit --coverage-text
+
 Thanks to the simple object-oriented code that we have written so far, we have
 been able to write unit-tests to cover all possible use cases of our
 framework; test doubles ensured that we were actually testing our code and not

Diff for: glossary.rst

@@ -125,6 +125,11 @@ Glossary
         Symfony's configuration files. See the :doc:`/components/yaml/introduction`
         chapter.
 
+   Annotation
+         Annotations are metadata written alongside your code. They can either be explanatory and will be
+         ignored during execution or add functionality to the line of code directly below as a means of
+         configuration. For example, the annotation ``@var`` describes the type of a variable, whereas in
+         Symfony2 ``@Assert`` can add validation to a member variable of a class (see :doc:`/book/validation` chapter).
 
 .. _`service-oriented architecture`: https://wikipedia.org/wiki/Service-oriented_architecture
 .. _`HTTP Wikipedia`: https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

Diff for: reference/configuration/swiftmailer.rst

@@ -303,3 +303,9 @@ Each mailer is registered as a service::
 
     // returns the second mailer
     $container->get('swiftmailer.mailer.second_mailer');
+
+.. caution::
+
+    When configuring multiple mailers, options must be placed under the
+    appropriate mailer key of the configuration instead of directly under the
+    ``swiftmailer`` key.

Diff for: reference/forms/types/options/error_mapping.rst.inc

@@ -31,7 +31,15 @@ Here are the rules for the left and the right side of the mapping:
   object, the property path is ``[indexName]``;
 * You can construct nested property paths by concatenating them, separating
   properties by dots. For example: ``addresses[work].matchingCityAndZipCode``;
-* The left side of the error mapping also accepts a dot ``.``, which refers
-  to the field itself. That means that any error added to the field is added
-  to the given nested field instead;
 * The right side contains simply the names of fields in the form.
+
+By default, errors for any property that is not mapped will bubble up to the
+parent form. You can use the dot (``.``) on the left side to map errors of all
+unmapped properties to a particular field. For instance, to map all these
+errors to the ``city`` field, use::
+
+    $resolver->setDefaults(array(
+        'error_mapping' => array(
+            '.' => 'city',
+        ),
+    ));