Merge branch '2.7' into 2.8

Conflicts:
	components/security/secure_tools.rst

Author: wouterj

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

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
 

components/form/introduction.rst

@@ -113,45 +113,45 @@ CSRF Protection
 ~~~~~~~~~~~~~~~
 
 Protection against CSRF attacks is built into the Form component, but you need
-to explicitly enable it or replace it with a custom solution. The following
-snippet adds CSRF protection to the form factory::
+to explicitly enable it or replace it with a custom solution. If you want to
+use the built-in support, require the Security CSRF component by executing
+``composer require symfony/security-csrf``.
+
+The following snippet adds CSRF protection to the form factory::
 
     use Symfony\Component\Form\Forms;
-    use Symfony\Component\Form\Extension\Csrf\CsrfExtension;
-    use Symfony\Component\Form\Extension\Csrf\CsrfProvider\SessionCsrfProvider;
     use Symfony\Component\HttpFoundation\Session\Session;
-
-    // generate a CSRF secret from somewhere
-    $csrfSecret = '<generated token>';
+    use Symfony\Component\Security\Extension\Csrf\CsrfExtension;
+    use Symfony\Component\Security\Csrf\TokenStorage\SessionTokenStorage;
+    use Symfony\Component\Security\Csrf\TokenGenerator\UriSafeTokenGenerator;
+    use Symfony\Component\Security\Csrf\CsrfTokenManager;
 
     // create a Session object from the HttpFoundation component
     $session = new Session();
 
-    $csrfProvider = new SessionCsrfProvider($session, $csrfSecret);
+    $csrfGenerator = new UriSafeTokenGenerator();
+    $csrfStorage = new SessionTokenStorage($session);
+    $csrfManager = new CsrfTokenManager($csrfGenerator, $csrfStorage);
 
     $formFactory = Forms::createFormFactoryBuilder()
         // ...
-        ->addExtension(new CsrfExtension($csrfProvider))
+        ->addExtension(new CsrfExtension($csrfStorage))
         ->getFormFactory();
 
-To secure your application against CSRF attacks, you need to define a CSRF
-secret. Generate a random string with at least 32 characters, insert it in the
-above snippet and make sure that nobody except your web server can access
-the secret.
-
 Internally, this extension will automatically add a hidden field to every
-form (called ``_token`` by default) whose value is automatically generated
-and validated when binding the form.
+form (called ``_token`` by default) whose value is automatically generated by
+the CSRF generator and validated when binding the form.
 
 .. tip::
 
     If you're not using the HttpFoundation component, you can use
-    :class:`Symfony\\Component\\Form\\Extension\\Csrf\\CsrfProvider\\DefaultCsrfProvider`
+    :class:`Symfony\\Component\\Security\\Csrf\\TokenStorage\\NativeSessionTokenStorage`
     instead, which relies on PHP's native session handling::
 
-        use Symfony\Component\Form\Extension\Csrf\CsrfProvider\DefaultCsrfProvider;
+        use Symfony\Component\Security\Csrf\TokenStorage\NativeSessionTokenStorage;
 
-        $csrfProvider = new DefaultCsrfProvider($csrfSecret);
+        $csrfStorage = new NativeSessionTokenStorage();
+        // ...
 
 Twig Templating
 ~~~~~~~~~~~~~~~

components/security/secure_tools.rst

@@ -1,47 +1,43 @@
-Securely Generating Random Numbers
-==================================
+Securely 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
 also use them if you want to solve the problem they address.
 
-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::
+    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`_.
 
-    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).
+.. _`Symfony Polyfill Component`: https://github.com/symfony/polyfill
+.. _`paragonie/random_compat package`: https://github.com/paragonie/random_compat

components/translation/usage.rst

@@ -139,6 +139,8 @@ recommended format. These files are parsed by one of the loader classes.
             'symfony.great'    => 'J\'aime Symfony',
         );
 
+.. _translation-real-vs-keyword-messages:
+
 .. sidebar:: Using Real or Keyword Messages
 
     This example illustrates the two different philosophies when creating

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

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);
        // ...

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:

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

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