Merge branch '2.7' into 2.8

Conflicts:
	components/security/secure_tools.rst
	cookbook/security/csrf_in_login_form.rst
	cookbook/security/form_login.rst
	cookbook/security/form_login_setup.rst
	cookbook/security/remember_me.rst

Author: wouterj

best_practices/security.rst

@@ -57,8 +57,8 @@ which uses a login form to load users from the database:
                 pattern: ^/
                 anonymous: true
                 form_login:
-                    check_path: security_login_check
-                    login_path: security_login_form
+                    check_path: login
+                    login_path: login
 
                 logout:
                     path: security_logout

book/configuration.rst

@@ -87,8 +87,8 @@ format you prefer:
 
 .. note::
 
-   You'll learn exactly how to load each file/format in the next section
-   `Environments`_.
+    You'll learn exactly how to load each file/format in the next section
+    `Environments`_.
 
 Each top-level entry like ``framework`` or ``twig`` defines the configuration
 for a particular bundle. For example, the ``framework`` key defines the configuration
@@ -122,13 +122,13 @@ FrameworkBundle configuration:
 
 .. code-block:: bash
 
-    $ app/console config:dump-reference FrameworkBundle
+    $ php app/console config:dump-reference FrameworkBundle
 
 The extension alias (configuration key) can also be used:
 
 .. code-block:: bash
 
-    $ app/console config:dump-reference framework
+    $ php app/console config:dump-reference framework
 
 .. note::
 
@@ -195,6 +195,12 @@ cached files and allow them to rebuild:
     be accessed directly through the browser. See the :doc:`testing chapter </book/testing>`
     for more details.
 
+.. tip::
+
+    When using the ``server:run`` command to start a server,
+    ``http://localhost:8000/`` will use the dev front controller of your
+    application.
+
 .. index::
    single: Environments; Configuration
 

book/page_creation.rst

@@ -59,11 +59,12 @@ a method inside of it that will be executed when someone goes to ``/lucky/number
 
 Before diving into this, test it out!
 
-    http://localhost:8000/app_dev.php/lucky/number
+    http://localhost:8000/lucky/number
 
 .. tip::
 
-    If you setup a proper virtual host in :doc:`Apache or Nginx </cookbook/configuration/web_server_configuration>`,
+    If you set up a proper virtual host in
+    :doc:`Apache or Nginx </cookbook/configuration/web_server_configuration>`,
     replace ``http://localhost:8000`` with your host name - like
     ``http://symfony.dev/app_dev.php/lucky/number``.
 
@@ -80,16 +81,6 @@ and is where you build the page. The only rule is that a controller *must*
 return a Symfony :ref:`Response <component-http-foundation-response>` object
 (and you'll even learn to bend this rule eventually).
 
-.. sidebar:: What's the ``app_dev.php`` in the URL?
-
-    Great question! By including ``app_dev.php`` in the URL, you're executing
-    Symfony through a file - ``web/app_dev.php`` - that boots it in the ``dev``
-    environment. This enables great debugging tools and rebuilds cached
-    files automatically. For production, you'll use clean URLs - like
-    ``http://localhost:8000/lucky/number`` - that execute a different file -
-    ``app.php`` - that's optimized for speed. To learn more about this and
-    environments, see :ref:`book-page-creation-prod-cache-clear`.
-
 Creating a JSON Response
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -126,7 +117,7 @@ Just add a second method to ``LuckyController``::
 
 Try this out in your browser:
 
-    http://localhost:8000/app_dev.php/api/lucky/number
+    http://localhost:8000/api/lucky/number
 
 You can even shorten this with the handy :class:`Symfony\\Component\\HttpFoundation\\JsonResponse`::
 
@@ -247,7 +238,7 @@ The best part is that you can access this value and use it in your controller::
 
 Try it by going to ``/lucky/number/XX`` - replacing XX with *any* number:
 
-    http://localhost:8000/app_dev.php/lucky/number/7
+    http://localhost:8000/lucky/number/7
 
 You should see *7* lucky numbers printed out! You can get the value of any
 ``{placeholder}`` in your route by adding a ``$placeholder`` argument to
@@ -404,7 +395,7 @@ to put the content into the middle of the ``base.html.twig`` layout.
 
 Refresh to see your template in action!
 
-    http://localhost:8000/app_dev.php/lucky/number/9
+    http://localhost:8000/lucky/number/9
 
 If you view the source code, you now have a basic HTML structure thanks to
 ``base.html.twig``.

book/security.rst

@@ -1192,6 +1192,14 @@ is defined by the ``target`` parameter above (e.g. the ``homepage``).
     :class:`Symfony\\Component\\Security\\Http\\Logout\\LogoutSuccessHandlerInterface`.
     See :doc:`Security Configuration Reference </reference/configuration/security>`.
 
+.. caution::
+
+    Notice that when using http-basic authenticated firewalls, there is no
+    real  way to log out : the only way to *log out* is to have the browser
+    stop sending your name and password  on every request. Clearing your
+    browser cache or restarting your browser usually helps. Some web developer
+    tools might be helpful here too.
+
 .. _`security-encoding-password`:
 
 Dynamically Encoding a Password

changelog.rst

@@ -13,6 +13,79 @@ documentation.
     Do you also want to participate in the Symfony Documentation? Take a look
     at the ":doc:`/contributing/documentation/overview`" article.
 
+December, 2015
+--------------
+
+New Documentation
+~~~~~~~~~~~~~~~~~
+
+* `#5906 <https://github.com/symfony/symfony-docs/pull/5906>`_ Added documentation for choice_translation_domain option (peterrehm)
+* `#6017 <https://github.com/symfony/symfony-docs/pull/6017>`_ Documented the Symfony Console Styles (javiereguiluz)
+* `#5811 <https://github.com/symfony/symfony-docs/pull/5811>`_ Conversion from mysql to PDO (iqbalmalik89)
+* `#5962 <https://github.com/symfony/symfony-docs/pull/5962>`_ Simplify code example in "Adding custom extensions" section (snoek09)
+* `#6022 <https://github.com/symfony/symfony-docs/pull/6022>`_ clarify custom route loader documentation (dbu)
+* `#5994 <https://github.com/symfony/symfony-docs/pull/5994>`_ Updated the release process for Symfony 3.x and future releases (javiereguiluz)
+
+Fixed Documentation
+~~~~~~~~~~~~~~~~~~~
+
+* `#6063 <https://github.com/symfony/symfony-docs/pull/6063>`_ minor #5829 Fix broken composer command (JHGitty)
+* `#5904 <https://github.com/symfony/symfony-docs/pull/5904>`_ Update php_soap_extension.rst (xDaizu)
+* `#5819 <https://github.com/symfony/symfony-docs/pull/5819>`_ Remove AppBundle (roukmoute)
+* `#6001 <https://github.com/symfony/symfony-docs/pull/6001>`_ Fix class name (BlueM)
+
+Minor Documentation Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* `#6043 <https://github.com/symfony/symfony-docs/pull/6043>`_ Mention commiting only bower.json (krike, WouterJ)
+* `#5848 <https://github.com/symfony/symfony-docs/pull/5848>`_ Added hints to spool config section (martinczerwi)
+* `#6042 <https://github.com/symfony/symfony-docs/pull/6042>`_ some tweaks to unit testing form types (xabbuh)
+* `#6059 <https://github.com/symfony/symfony-docs/pull/6059>`_ Add best practice about the Form type namespace (WouterJ)
+* `#6068 <https://github.com/symfony/symfony-docs/pull/6068>`_ Remove references to API tagging (dunglas)
+* `#6088 <https://github.com/symfony/symfony-docs/pull/6088>`_ Update validation.rst (syedi)
+* `#6085 <https://github.com/symfony/symfony-docs/pull/6085>`_ Update validation.rst (syedi)
+* `#6094 <https://github.com/symfony/symfony-docs/pull/6094>`_ [Form] Added a missing php opening tag (dev-symfony-void)
+* `#5840 <https://github.com/symfony/symfony-docs/pull/5840>`_ [Contributing] [Standards] Add note about `trigger_error()` and deprecation messages (phansys)
+* `#6050 <https://github.com/symfony/symfony-docs/pull/6050>`_ Lots of minor fixes & applying best practices to form cookbook doc (ThomasLandauer, WouterJ)
+* `#5570 <https://github.com/symfony/symfony-docs/pull/5570>`_ Quick review of 'create framework' tutorial (WouterJ)
+* `#5445 <https://github.com/symfony/symfony-docs/pull/5445>`_ Reworded the explanation about the kernel.event_listener tag (javiereguiluz)
+* `#6054 <https://github.com/symfony/symfony-docs/pull/6054>`_ Remove 2.8 branch from patch documentation (Triiistan)
+* `#6057 <https://github.com/symfony/symfony-docs/pull/6057>`_ Fix PHP code for registering service (WouterJ)
+* `#6067 <https://github.com/symfony/symfony-docs/pull/6067>`_ improve phrasing (greg0ire)
+* `#6063 <https://github.com/symfony/symfony-docs/pull/6063>`_ minor #5829 Fix broken composer command (JHGitty)
+* `#6041 <https://github.com/symfony/symfony-docs/pull/6041>`_ Fixed misspelling of human in glossary.rst YAML (Wasserschlange)
+* `#6049 <https://github.com/symfony/symfony-docs/pull/6049>`_ Finish #5798 Add app_ prefix to form type names (OskarStark, WouterJ)
+* `#5829 <https://github.com/symfony/symfony-docs/pull/5829>`_ use composer command instead of editing json file (OskarStark)
+* `#6046 <https://github.com/symfony/symfony-docs/pull/6046>`_ Update framework.rst (typo in sesssion) (patrick-mota)
+* `#5662 <https://github.com/symfony/symfony-docs/pull/5662>`_ Fixed wrong version of symfony with composer install (Nek-)
+* `#5890 <https://github.com/symfony/symfony-docs/pull/5890>`_ Updated article for modern Symfony practices and the use of bcrypt (javiereguiluz)
+* `#6015 <https://github.com/symfony/symfony-docs/pull/6015>`_ [Assetic] complete XML configuration examples (xabbuh)
+* `#5963 <https://github.com/symfony/symfony-docs/pull/5963>`_ Add note about 'phar extension' dependency (snoek09)
+* `#6006 <https://github.com/symfony/symfony-docs/pull/6006>`_ [Book] use AppBundle examples and follow best practices (xabbuh)
+* `#6016 <https://github.com/symfony/symfony-docs/pull/6016>`_ Corrected the line references for the basic controller example (theTeddyBear)
+* `#5446 <https://github.com/symfony/symfony-docs/pull/5446>`_ [Contributing] [Standards] Added note about phpdoc_separation (phansys)
+* `#5820 <https://github.com/symfony/symfony-docs/pull/5820>`_ Fixed an issue with command option shortcuts (javiereguiluz)
+* `#6033 <https://github.com/symfony/symfony-docs/pull/6033>`_ Fix Typo (Shine-neko)
+* `#6011 <https://github.com/symfony/symfony-docs/pull/6011>`_ Fixed formatting issues (javiereguiluz)
+* `#6012 <https://github.com/symfony/symfony-docs/pull/6012>`_ Use HTTPS for downloading the Symfony Installer (javiereguiluz)
+* `#6009 <https://github.com/symfony/symfony-docs/pull/6009>`_ Fix missing constant usage for generating urls (Tobion)
+* `#5965 <https://github.com/symfony/symfony-docs/pull/5965>`_ Removing php opening tags (Deamon)
+* `#6003 <https://github.com/symfony/symfony-docs/pull/6003>`_ #5999 fix files names (vincentaubert)
+* `#5996 <https://github.com/symfony/symfony-docs/pull/5996>`_ Clarify example for SUBMIT form event (bkosborne)
+* `#6000 <https://github.com/symfony/symfony-docs/pull/6000>`_ Update registration_form.rst (afurculita)
+* `#5989 <https://github.com/symfony/symfony-docs/pull/5989>`_ Fix words according context (richardpq)
+* `#5992 <https://github.com/symfony/symfony-docs/pull/5992>`_ More use single quotes for YAML strings (snoek09)
+* `#5957 <https://github.com/symfony/symfony-docs/pull/5957>`_ mark deep option as deprecated (snoek09)
+* `#5943 <https://github.com/symfony/symfony-docs/pull/5943>`_ Add tip for when returning `null` from `createToken()` (jeroenseegers)
+* `#5956 <https://github.com/symfony/symfony-docs/pull/5956>`_ Update security.rst (mpaquet)
+* `#5959 <https://github.com/symfony/symfony-docs/pull/5959>`_ Fix #5912 Ambiguity on Access Decision Manager's Strategy (Pierre Maraitre)
+* `#5955 <https://github.com/symfony/symfony-docs/pull/5955>`_ use single quotes for YAML strings (snoek09)
+* `#5979 <https://github.com/symfony/symfony-docs/pull/5979>`_ [Book] Do not extend the base controller before introducing it (ogizanagi)
+* `#5970 <https://github.com/symfony/symfony-docs/pull/5970>`_ Remove isSubmitted call (DanielSiepmann)
+* `#5972 <https://github.com/symfony/symfony-docs/pull/5972>`_ Add isSubmitted call (DanielSiepmann)
+* `#5961 <https://github.com/symfony/symfony-docs/pull/5961>`_ update from_flat_php_to_symfony2.rst (thao-witkam)
+
+
 November, 2015
 --------------
 

components/expression_language/syntax.rst

@@ -20,6 +20,18 @@ The component supports:
 * **booleans** - ``true`` and ``false``
 * **null** - ``null``
 
+.. caution::
+
+    A backslash (``\``) must be escaped by 4 backslashes (``\\\\``) in a string
+    and 8 backslashes (``\\\\\\\\``) in a regex::
+
+        echo $language->evaluate('"\\\\"'); // prints \
+        $language->evaluate('"a\\\\b" matches "/^a\\\\\\\\b$/"'); // returns true
+
+    Control characters (e.g. ``\n``) in expressions are replaced with
+    whitespace. To avoid this, escape the sequence with a single backslash
+    (e.g.  ``\\n``).
+
 .. _component-expression-objects:
 
 Working with Objects

components/security/secure_tools.rst

@@ -5,7 +5,27 @@ 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 String
+.. note::
+
+    The functions described in this article were introduced in PHP 5.6 or 7.
+    For older PHP versions, a polyfill is provided by the
+    `Symfony Polyfill Component`_.
+
+Comparing Strings
+~~~~~~~~~~~~~~~~~
+
+The time it takes to compare two strings depends on their differences. This
+can be used by an attacker when the two strings represent a password for
+instance; it is known as a `Timing attack`_.
+
+When comparing two passwords, you should use the :phpfunction:`hash_equals`
+function::
+
+    if (hash_equals($knownString, $userInput)) {
+        // ...
+    }
+
+Generating a Secure Random String
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Whenever you need to generate a secure random string, you are highly
@@ -33,11 +53,5 @@ use the :phpfunction:`random_int` function::
 
     $random = random_int(1, 10);
 
-.. note::
-
-    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

cookbook/controller/error_pages.rst

@@ -267,7 +267,7 @@ In that case, you might want to override one or both of the ``showAction()`` and
             # app/config/services.yml
             services:
                 app.exception_controller:
-                class: AppBundle\CustomExceptionController
+                class: AppBundle\Controller\CustomExceptionController
                 arguments: ['@twig', '%kernel.debug%']
 
         .. code-block:: xml
@@ -298,6 +298,7 @@ In that case, you might want to override one or both of the ``showAction()`` and
                 new Reference('twig'),
                 '%kernel.debug%'
             ));
+            $container->setDefinition('app.exception_controller', $definition);
 
     And then configure ``twig.exception_controller`` using the controller as
     services syntax (e.g. ``app.exception_controller:showAction``).

cookbook/email/dev_environment.rst

@@ -141,12 +141,9 @@ by adding the ``delivery_whitelist`` option:
         swiftmailer:
             delivery_address: [email protected]
             delivery_whitelist:
-               # all email addresses matching this regex will *not* be
-               # redirected to [email protected]
+               # all email addresses matching these regexes will be delivered
+               # like normal, as well as being sent to [email protected]
                - '/@specialdomain\.com$/'
-
-               # all emails sent to [email protected] won't
-               # be redirected to [email protected] too
                - '/^admin@mydomain\.com$/'
 
     .. code-block:: xml
@@ -162,10 +159,9 @@ by adding the ``delivery_whitelist`` option:
                 http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
 
             <swiftmailer:config delivery-address="[email protected]">
-                <!-- all email addresses matching this regex will *not* be redirected to [email protected] -->
+                <!-- all email addresses matching these regexes will be delivered
+                     like normal, as well as being sent 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>/^admin@mydomain\.com$/</swiftmailer:delivery-whitelist-pattern>
             </swiftmailer:config>
         </container>
@@ -176,19 +172,16 @@ by adding the ``delivery_whitelist`` option:
         $container->loadFromExtension('swiftmailer', array(
             'delivery_address'  => "[email protected]",
             'delivery_whitelist' => array(
-                // all email addresses matching this regex will *not* be
-                // redirected to [email protected]
+                // all email addresses matching these regexes will be delivered
+                // like normal, as well as being sent to [email protected]
                 '/@specialdomain\.com$/',
-
-                // all emails sent to [email protected] won't be
-                // redirected to [email protected] too
                 '/^admin@mydomain\.com$/',
             ),
         ));
 
-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.
+In the above example all email messages will be redirected to ``[email protected]``
+and messages sent to the ``[email protected]`` address or to any email address
+belonging to the domain ``specialdomain.com`` will also be delivered as normal.
 
 Viewing from the Web Debug Toolbar
 ----------------------------------

cookbook/security/csrf_in_login_form.rst

@@ -92,7 +92,7 @@ using the login form:
         {# src/AppBundle/Resources/views/Security/login.html.twig #}
 
         {# ... #}
-        <form action="{{ path('login_check') }}" method="post">
+        <form action="{{ path('login') }}" method="post">
             {# ... the login fields #}
 
             <input type="hidden" name="_csrf_token"
@@ -109,7 +109,7 @@ using the login form:
         <!-- ... -->
         <!-- The path() method was introduced in Symfony 2.8. Prior to 2.8, you
              had to use generate(). -->
-        <form action="<?php echo $view['router']->path('login_check') ?>" method="post">
+        <form action="<?php echo $view['router']->path('login') ?>" method="post">
             <!-- ... the login fields -->
 
             <input type="hidden" name="_csrf_token"

cookbook/security/form_login.rst

@@ -234,7 +234,7 @@ redirect to the URL defined by some ``account`` route, use the following:
             <div>{{ error.message }}</div>
         {% endif %}
 
-        <form action="{{ path('login_check') }}" method="post">
+        <form action="{{ path('login') }}" method="post">
             <label for="username">Username:</label>
             <input type="text" id="username" name="_username" value="{{ last_username }}" />
 
@@ -255,7 +255,7 @@ redirect to the URL defined by some ``account`` route, use the following:
 
         <!-- The path() method was introduced in Symfony 2.8. Prior to 2.8, you
              had to use generate(). -->
-        <form action="<?php echo $view['router']->path('login_check') ?>" method="post">
+        <form action="<?php echo $view['router']->path('login') ?>" method="post">
             <label for="username">Username:</label>
             <input type="text" id="username" name="_username" value="<?php echo $last_username ?>" />