Merge branch '2.3' into 2.4

Author: weaverryan

book/security.rst

@@ -661,7 +661,7 @@ see :doc:`/cookbook/security/form_login`.
                 ),
             ),
 
-    **3. Be sure ``/login_check`` is behind a firewall**
+    **3. Be sure /login_check is behind a firewall**
 
     Next, make sure that your ``check_path`` URL (e.g. ``/login_check``)
     is behind the firewall you're using for your form login (in this example,
@@ -1338,7 +1338,7 @@ in plain text (whether those users are stored in a configuration file or in
 a database somewhere). Of course, in a real application, you'll want to encode
 your users' passwords for security reasons. This is easily accomplished by
 mapping your User class to one of several built-in "encoders". For example,
-to store your users in memory, but obscure their passwords via ``sha1``,
+to store your users in memory, but obscure their passwords via ``bcrypt``,
 do the following:
 
 .. configuration-block::
@@ -1352,14 +1352,17 @@ do the following:
                 in_memory:
                     memory:
                         users:
-                            ryan:  { password: bb87a29949f3a1ee0559f8a57357487151281386, roles: 'ROLE_USER' }
-                            admin: { password: 74913f5cd5f61ec0bcfdb775414c2fb3d161b620, roles: 'ROLE_ADMIN' }
+                            ryan:
+                                password: $2a$12$w/aHvnC/XNeDVrrl65b3dept8QcKqpADxUlbraVXXsC03Jam5hvoO
+                                roles: 'ROLE_USER'
+                            admin:
+                                password: $2a$12$HmOsqRDJK0HuMDQ5Fb2.AOLMQHyNHGD0seyjU3lEVusjT72QQEIpW
+                                roles: 'ROLE_ADMIN'
 
             encoders:
                 Symfony\Component\Security\Core\User\User:
-                    algorithm: sha1
-                    iterations: 1
-                    encode_as_base64: false
+                    algorithm: bcrypt
+                    cost: 12
 
     .. code-block:: xml
 
@@ -1369,18 +1372,18 @@ do the following:
             <provider name="in_memory">
                 <memory>
                     <user name="ryan"
-                        password="bb87a29949f3a1ee0559f8a57357487151281386"
+                        password="$2a$12$w/aHvnC/XNeDVrrl65b3dept8QcKqpADxUlbraVXXsC03Jam5hvoO"
                         roles="ROLE_USER" />
                     <user name="admin"
-                        password="74913f5cd5f61ec0bcfdb775414c2fb3d161b620"
+                        password="$2a$12$HmOsqRDJK0HuMDQ5Fb2.AOLMQHyNHGD0seyjU3lEVusjT72QQEIpW"
                         roles="ROLE_ADMIN" />
                 </memory>
             </provider>
 
             <encoder class="Symfony\Component\Security\Core\User\User"
-                algorithm="sha1"
-                iterations="1"
-                encode_as_base64="false" />
+                algorithm="bcrypt"
+                cost="12"
+            />
         </config>
 
     .. code-block:: php
@@ -1393,11 +1396,11 @@ do the following:
                     'memory' => array(
                         'users' => array(
                             'ryan' => array(
-                                'password' => 'bb87a29949f3a1ee0559f8a57357487151281386',
+                                'password' => '$2a$12$w/aHvnC/XNeDVrrl65b3dept8QcKqpADxUlbraVXXsC03Jam5hvoO',
                                 'roles' => 'ROLE_USER',
                             ),
                             'admin' => array(
-                                'password' => '74913f5cd5f61ec0bcfdb775414c2fb3d161b620',
+                                'password' => '$2a$12$HmOsqRDJK0HuMDQ5Fb2.AOLMQHyNHGD0seyjU3lEVusjT72QQEIpW',
                                 'roles' => 'ROLE_ADMIN',
                             ),
                         ),
@@ -1406,77 +1409,36 @@ do the following:
             ),
             'encoders' => array(
                 'Symfony\Component\Security\Core\User\User' => array(
-                    'algorithm'         => 'sha1',
-                    'iterations'        => 1,
-                    'encode_as_base64'  => false,
+                    'algorithm'         => 'bcrypt',
+                    'iterations'        => 12,
                 ),
             ),
         ));
 
-By setting the ``iterations`` to ``1`` and the ``encode_as_base64`` to false,
-the password is simply run through the ``sha1`` algorithm one time and without
-any extra encoding. You can now calculate the hashed password either programmatically
-(e.g. ``hash('sha1', 'ryanpass')``) or via some online tool like `functions-online.com`_
-
-.. tip::
-
-    Supported algorithms for this method depend on your PHP version.
-    A full list is available calling the PHP function :phpfunction:`hash_algos`.
-
-If you're creating your users dynamically (and storing them in a database),
-you can use even tougher hashing algorithms and then rely on an actual password
-encoder object to help you encode passwords. For example, suppose your User
-object is ``Acme\UserBundle\Entity\User`` (like in the above example). First,
-configure the encoder for that user:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # app/config/security.yml
-        security:
-            # ...
-
-            encoders:
-                Acme\UserBundle\Entity\User: sha512
-
-    .. code-block:: xml
+.. versionadded:: 2.2
+    The BCrypt encoder was introduced in Symfony 2.2.
 
-        <!-- app/config/security.xml -->
-        <config>
-            <!-- ... -->
+You can now calculate the hashed password either programmatically
+(e.g. ``password_hash('ryanpass', PASSWORD_BCRYPT, array('cost' => 12));``)
+or via some online tool.
 
-            <encoder class="Acme\UserBundle\Entity\User" algorithm="sha512" />
-        </config>
+.. include:: /cookbook/security/_ircmaxwell_password-compat.rst.inc
 
-    .. code-block:: php
-
-        // app/config/security.php
-        $container->loadFromExtension('security', array(
-            // ...
-            'encoders' => array(
-                'Acme\UserBundle\Entity\User' => 'sha512',
-            ),
-        ));
-
-In this case, you're using the stronger ``sha512`` algorithm. Also, since
-you've simply specified the algorithm (``sha512``) as a string, the system
-will default to hashing your password 5000 times in a row and then encoding
-it as base64. In other words, the password has been greatly obfuscated so
-that the hashed password can't be decoded (i.e. you can't determine the password
-from the hashed password).
+Supported algorithms for this method depend on your PHP version. A full list
+is available by calling the PHP function :phpfunction:`hash_algos`.
 
 .. versionadded:: 2.2
     As of Symfony 2.2 you can also use the :ref:`PBKDF2 <reference-security-pbkdf2>`
-    and :ref:`BCrypt <reference-security-bcrypt>` password encoders.
+    password encoder.
 
 Determining the Hashed Password
 ...............................
 
-If you have some sort of registration form for users, you'll need to be able
-to determine the hashed password so that you can set it on your user. No
-matter what algorithm you configure for your user object, the hashed password
-can always be determined in the following way from a controller::
+If you're storing users in the database and you have some sort of registration
+form for users, you'll need to be able to determine the hashed password so
+that you can set it on your user before inserting it. No matter what algorithm
+you configure for your user object, the hashed password can always be determined
+in the following way from a controller::
 
     $factory = $this->get('security.encoder_factory');
     $user = new Acme\UserBundle\Entity\User();
@@ -1485,6 +1447,10 @@ can always be determined in the following way from a controller::
     $password = $encoder->encodePassword('ryanpass', $user->getSalt());
     $user->setPassword($password);
 
+In order for this to work, just make sure that you have the encoder for your
+user class (e.g. ``Acme\UserBundle\Entity\User``) configured under the ``encoders``
+key in ``app/config/security.yml``.
+
 .. caution::
 
     When you allow a user to submit a plaintext password (e.g. registration
@@ -2168,5 +2134,4 @@ Learn more from the Cookbook
 
 .. _`FOSUserBundle`: https://github.com./FriendsOfSymfony/FOSUserBundle
 .. _`implement the \Serializable interface`: http://php.net/manual/en/class.serializable.php
-.. _`functions-online.com`: http://www.functions-online.com/sha1.html
 .. _`Timing attack`: http://en.wikipedia.org/wiki/Timing_attack

components/config/introduction.rst

@@ -12,6 +12,13 @@ The Config component provides several classes to help you find, load, combine,
 autofill and validate configuration values of any kind, whatever their source
 may be (YAML, XML, INI files, or for instance a database).
 
+.. caution::
+
+    The ``IniFileLoader`` parses the file contents using the
+    :phpfunction:`parse_ini_file` function, therefore, you can only set
+    parameters to string values. To set parameters to other data types
+    (e.g. boolean, integer, etc), the other loaders are recommended.
+
 Installation
 ------------
 

components/http_foundation/trusting_proxies.rst

@@ -15,7 +15,7 @@ headers by default. If you are behind a proxy, you should manually whitelist
 your proxy.
 
 .. versionadded:: 2.3
-    CIDR notation support was introduced, so you can whitelist whole
+    CIDR notation support was introduced in Symfony 2.3, so you can whitelist whole
     subnets (e.g. ``10.0.0.0/8``, ``fc00::/7``).
 
 .. code-block:: php

contributing/code/patches.rst

@@ -200,7 +200,7 @@ When your patch is not about a bug fix (when you add a new feature or change
 an existing one for instance), it must also include the following:
 
 * An explanation of the changes in the relevant ``CHANGELOG`` file(s) (the
- ``[BC BREAK]`` or the ``[DEPRECATION]`` prefix must be used when relevant);
+  ``[BC BREAK]`` or the ``[DEPRECATION]`` prefix must be used when relevant);
 
 * An explanation on how to upgrade an existing application in the relevant
   ``UPGRADE`` file(s) if the changes break backward compatibility or if you
@@ -244,7 +244,7 @@ Check that all tests still pass and push your branch remotely:
 
 .. code-block:: bash
 
-    $ git push -f origin BRANCH_NAME
+    $ git push --force origin BRANCH_NAME
 
 Make a Pull Request
 ~~~~~~~~~~~~~~~~~~~
@@ -369,11 +369,11 @@ patch. Before re-submitting the patch, rebase with ``upstream/master`` or
 .. code-block:: bash
 
     $ git rebase -f upstream/master
-    $ git push -f origin BRANCH_NAME
+    $ git push --force origin BRANCH_NAME
 
 .. note::
 
-    when doing a ``push --force``, always specify the branch name explicitly
+    When doing a ``push --force``, always specify the branch name explicitly
     to avoid messing other branches in the repo (``--force`` tells Git that
     you really want to mess with things so do it carefully).
 
@@ -383,10 +383,9 @@ convert many commits to one commit. To do this, use the rebase command:
 .. code-block:: bash
 
     $ git rebase -i upstream/master
-    $ git push -f origin BRANCH_NAME
+    $ git push --force origin BRANCH_NAME
 
-The number 3 here must equal the amount of commits in your branch. After you
-type this command, an editor will popup showing a list of commits:
+After you type this command, an editor will popup showing a list of commits:
 
 .. code-block:: text
 
@@ -396,9 +395,9 @@ type this command, an editor will popup showing a list of commits:
 
 To squash all commits into the first one, remove the word ``pick`` before the
 second and the last commits, and replace it by the word ``squash`` or just
- ``s``. When you save, Git will start rebasing, and if successful, will ask
- you to edit the commit message, which by default is a listing of the commit
- messages of all the commits. When you are finished, execute the push command.
+``s``. When you save, Git will start rebasing, and if successful, will ask
+you to edit the commit message, which by default is a listing of the commit
+messages of all the commits. When you are finished, execute the push command.
 
 .. _ProGit:                                http://git-scm.com/book
 .. _GitHub:                                https://github.com./signup/free

contributing/documentation/overview.rst

@@ -135,7 +135,7 @@ tag and a short description:
 .. code-block:: text
 
     .. versionadded:: 2.3
-        The ``askHiddenResponse`` method was added in Symfony 2.3.
+        The ``askHiddenResponse`` method was introduced in Symfony 2.3.
 
     You can also ask a question and hide the response. This is particularly...
 

cookbook/doctrine/file_uploads.rst

@@ -300,6 +300,15 @@ object, which is what's returned after a ``file`` field is submitted::
 Using Lifecycle Callbacks
 -------------------------
 
+.. caution::
+
+    Using lifecycle callbacks is a limited technique that has some drawbacks.
+    If you want to remove the hardcoded ``__DIR__`` reference inside
+    the ``Document::getUploadRootDir()`` method, the best way is to start
+    using explicit :doc:`doctrine listeners </cookbook/doctrine/event_listeners_subscribers>`.
+    There you will be able to inject kernel parameters such as ``kernel.root_dir``
+    to be able to build absolute paths.
+
 Even if this implementation works, it suffers from a major flaw: What if there
 is a problem when the entity is persisted? The file would have already moved
 to its final location even though the entity's ``path`` property didn't

cookbook/routing/service_container_parameters.rst

@@ -18,16 +18,17 @@ inside your routing configuration:
 
     .. code-block:: yaml
 
+        # app/config/routing.yml
         contact:
             path:     /{_locale}/contact
             defaults: { _controller: AcmeDemoBundle:Main:contact }
             requirements:
-                _locale: %acme_demo.locales%
+                _locale: "%acme_demo.locales%"
 
     .. code-block:: xml
 
+        <!-- app/config/routing.xml -->
         <?xml version="1.0" encoding="UTF-8" ?>
-
         <routes xmlns="http://symfony.com/schema/routing"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd">
@@ -40,6 +41,7 @@ inside your routing configuration:
 
     .. code-block:: php
 
+        // app/config/routing.php
         use Symfony\Component\Routing\RouteCollection;
         use Symfony\Component\Routing\Route;
 
@@ -82,14 +84,15 @@ path):
 
     .. code-block:: yaml
 
+        # app/config/routing.yml
         some_route:
             path:     /%acme_demo.route_prefix%/contact
             defaults: { _controller: AcmeDemoBundle:Main:contact }
 
     .. code-block:: xml
 
+        <!-- app/config/routing.xml -->
         <?xml version="1.0" encoding="UTF-8" ?>
-
         <routes xmlns="http://symfony.com/schema/routing"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd">
@@ -101,6 +104,7 @@ path):
 
     .. code-block:: php
 
+        // app/config/routing.php
         use Symfony\Component\Routing\RouteCollection;
         use Symfony\Component\Routing\Route;
 
@@ -116,7 +120,7 @@ path):
     Just like in normal service container configuration files, if you actually
     need a ``%`` in your route, you can escape the percent sign by doubling
     it, e.g. ``/score-50%%``, which would resolve to ``/score-50%``.
-    
+
     However, as the ``%`` characters included in any URL are automatically encoded,
     the resulting URL of this example would be ``/score-50%25`` (``%25`` is the
     result of encoding the ``%`` character).

cookbook/security/_ircmaxwell_password-compat.rst.inc

@@ -0,0 +1,13 @@
+.. caution::
+
+    If you're using PHP 5.4 or lower, you'll need to install the ``ircmaxell/password-compat``
+    library via Composer in order to be able to use the ``bcrypt`` encoder:
+
+    .. code-block:: json
+
+        {
+            "require": {
+                ...
+                "ircmaxell/password-compat": "~1.0.3"
+            }
+        }