Merge branch '2.8' into 3.0

Conflicts: book/configuration.rst
gregfriedrice · Feb 7, 2016 · cdb8b24 · cdb8b24
2 parents 35a520d + eb1c1ae
commit cdb8b24
Show file tree

Hide file tree

Showing 18 changed files with 415 additions and 105 deletions.
diff --git a/best_practices/forms.rst b/best_practices/forms.rst
@@ -71,13 +71,9 @@ Registering Forms as Services
 
 You can also
 :ref:`register your form type as a service <form-cookbook-form-field-service>`.
-But this is *not* recommended unless you plan to reuse the new form type in many
-places or embed it in other forms directly or via the
-:doc:`CollectionType </reference/forms/types/collection>`.
-
-For most forms that are used only to edit or create something, registering
-the form as a service is over-kill, and makes it more difficult to figure
-out exactly which form class is being used in a controller.
+This is only needed if your form type requires some dependencies to be injected
+by the container, otherwise it is unnecessary overhead and therefore *not*
+recommended to do this for all form type classes.
 
 Form Button Configuration
 -------------------------

diff --git a/best_practices/security.rst b/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

diff --git a/book/configuration.rst b/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
@@ -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
 

diff --git a/book/page_creation.rst b/book/page_creation.rst
@@ -64,11 +64,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``.
 
@@ -85,16 +86,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
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -131,7 +122,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`::
 
@@ -252,7 +243,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
@@ -409,7 +400,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``.

diff --git a/book/security.rst b/book/security.rst
@@ -1190,6 +1190,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

diff --git a/changelog.rst b/changelog.rst
@@ -13,6 +13,93 @@ 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)
+* `#5966 <https://github.com/symfony/symfony-docs/pull/5966>`_ Remove deprecated StringUtils from WSSE custom auth provider (pimpreneil)
+* `#5962 <https://github.com/symfony/symfony-docs/pull/5962>`_ Simplify code example in "Adding custom extensions" section (snoek09)
+* `#5977 <https://github.com/symfony/symfony-docs/pull/5977>`_ RequestStack parameter is required since 3.0 (leunggamciu)
+* `#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)
+* `#5954 <https://github.com/symfony/symfony-docs/pull/5954>`_ Fix #5236 [2.8][Translation] specify additional translation loading paths (Pierre Maraitre, Balamung)
+
+Fixed Documentation
+~~~~~~~~~~~~~~~~~~~
+
+* `#6086 <https://github.com/symfony/symfony-docs/pull/6086>`_ Update form_customization.rst (vudaltsov)
+* `#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)
+* `#5586 <https://github.com/symfony/symfony-docs/pull/5586>`_ [2.8] Remove 2.6 versionaddeds as version reached eom (WouterJ)
+* `#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)
+* `#5993 <https://github.com/symfony/symfony-docs/pull/5993>`_ [Cookbook] [Security] Use UserLoaderInterface instead of UserProviderInterface (ogizanagi)
+* `#6071 <https://github.com/symfony/symfony-docs/pull/6071>`_ Fix syntax (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)
+* `#6027 <https://github.com/symfony/symfony-docs/pull/6027>`_ Update guard-authentication.rst (rvanginneken)
+* `#6025 <https://github.com/symfony/symfony-docs/pull/6025>`_ Update guard-authentication.rst (rvanginneken)
+* `#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)
+* `#6004 <https://github.com/symfony/symfony-docs/pull/6004>`_ Fix for small typo (djoos)
+* `#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)
+* `#5940 <https://github.com/symfony/symfony-docs/pull/5940>`_ [Cookbook][ServiceContainer] move filename comment to the top of the code block (xabbuh)
+* `#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)
+* `#5964 <https://github.com/symfony/symfony-docs/pull/5964>`_ Missing n in Column (joshuataylor)
+* `#5961 <https://github.com/symfony/symfony-docs/pull/5961>`_ update from_flat_php_to_symfony2.rst (thao-witkam)
+* `#5924 <https://github.com/symfony/symfony-docs/pull/5924>`_ Removed note about removed content (WouterJ)
+* `#5938 <https://github.com/symfony/symfony-docs/pull/5938>`_ Add proper use of the password type (themccallister)
+
+
 November, 2015
 --------------
 

diff --git a/components/expression_language/syntax.rst b/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

diff --git a/components/security/secure_tools.rst b/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
diff --git a/cookbook/controller/error_pages.rst b/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``).

diff --git a/cookbook/email/dev_environment.rst b/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
 ----------------------------------

diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc
@@ -178,6 +178,7 @@
   * :doc:`/cookbook/security/multiple_user_providers`
   * :doc:`/cookbook/security/firewall_restriction`
   * :doc:`/cookbook/security/host_restriction`
+  * :doc:`/cookbook/security/user_checkers`
 
 * :doc:`Security Authorization (Denying Access) </cookbook/security/index>`