Moving the new named algorithms into their own cookbook entry

book/security.rst

@@ -1434,78 +1434,10 @@ or via some online tool.
 Supported algorithms for this method depend on your PHP version. A full list
 is available by calling the PHP function :phpfunction:`hash_algos`.
 
-Named encoders
-..............
-
-.. versionadded:: 2.5
-    Named encoders were introduced in Symfony 2.5
-
-Another option is to set the encoder dynamically on an instance basis.
-In the previous example, you've set the ``sha512`` algorithm for ``Acme\UserBundle\Entity\User``.
-This may be secure enough for a regular user, but what if you want your admins to have
-a stronger algorithm? Let's say ``bcrypt``. This can be done with named encoders:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # app/config/security.yml
-        security:
-            # ...
-            encoders:
-                harsh:
-                    algorithm: bcrypt
-                    cost: 15
-
-    .. code-block:: xml
-
-        <!-- app/config/security.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <srv:container xmlns="http://symfony.com/schema/dic/security"
-            xmlns:srv="http://symfony.com/schema/dic/services">
-
-            <config>
-                <!-- ... -->
-                <encoder class="harsh"
-                    algorithm="bcrypt"
-                    cost="15" />
-            </config>
-        </srv:container>
-
-    .. code-block:: php
-
-        // app/config/security.php
-        $container->loadFromExtension('security', array(
-            // ...
-            'encoders' => array(
-                'harsh' => array(
-                    'algorithm' => 'bcrypt',
-                    'cost'      => '15'
-                ),
-            ),
-        ));
-
-Now you've created an encoder named ``harsh``. In order for a ``User`` instance to use it,
-It must implement ``EncoderAwareInterface`` and have a method ``getEncoderName`` which returns the
-name of the encoder to use::
-
-    // src/Acme/UserBundle/Entity/User.php
-    namespace Acme\UserBundle\Entity;
-
-    use Symfony\Component\Security\Core\User\UserInterface;
-    use Symfony\Component\Security\Core\Encoder\EncoderAwareInterface;
+.. tip::
 
-    class User implements UserInterface, EncoderAwareInterface
-    {
-        public function getEncoderName()
-        {
-            if ($this->isAdmin()) {
-                return 'harsh';
-            }
-
-            return null; // use the default encoder
-        }
-    }
+    It's also possible to use different hashing algorithms on a user-by-user
+    basis. See :doc:`/cookbook/security/named-encoders` for more details.
 
 Determining the Hashed Password
 ...............................

cookbook/map.rst.inc

@@ -144,6 +144,7 @@
   * :doc:`/cookbook/security/custom_authentication_provider`
   * :doc:`/cookbook/security/target_path`
   * :doc:`/cookbook/security/csrf_in_login_form`
+  * :doc:`/cookbook/security/named_encoders`
 
 * **Serializer**
 

cookbook/security/index.rst

@@ -20,3 +20,4 @@ Security
     custom_authentication_provider
     target_path
     csrf_in_login_form
+    named_encoders

cookbook/security/named_encoders.rst

@@ -0,0 +1,123 @@
+.. index::
+    single: Security; Named Encoders
+
+How to Choose the Password Encoder Algorithm Dynamically
+========================================================
+
+.. versionadded:: 2.5
+    Named encoders were introduced in Symfony 2.5.
+
+Usually, the same password encoder is used for all users by configuring it
+to apply to all instances of a specific class:
+
+        # app/config/security.yml
+        security:
+            # ...
+            encoders:
+                Symfony\Component\Security\Core\User\User: sha512
+
+    .. code-block:: xml
+
+        <!-- app/config/security.xml -->
+        <?xml version="1.0" encoding="UTF-8"?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd"
+        >
+            <config>
+                <!-- ... -->
+                <encoder class="Symfony\Component\Security\Core\User\User"
+                    algorithm="sha512"
+                />
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // app/config/security.php
+        $container->loadFromExtension('security', array(
+            // ...
+            'encoders' => array(
+                'Symfony\Component\Security\Core\User\User' => array(
+                    'algorithm' => 'sha512',
+                ),
+            ),
+        ));
+
+Another option is to use a "named" encoder and then select which encoder
+you want to use dynamically.
+
+In the previous example, you've set the ``sha512`` algorithm for ``Acme\UserBundle\Entity\User``.
+This may be secure enough for a regular user, but what if you want your admins
+to have a stronger algorithm, for example ``bcrypt``. This can be done with
+named encoders:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/security.yml
+        security:
+            # ...
+            encoders:
+                harsh:
+                    algorithm: bcrypt
+                    cost: 15
+
+    .. code-block:: xml
+
+        <!-- app/config/security.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd"
+        >
+
+            <config>
+                <!-- ... -->
+                <encoder class="harsh"
+                    algorithm="bcrypt"
+                    cost="15" />
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // app/config/security.php
+        $container->loadFromExtension('security', array(
+            // ...
+            'encoders' => array(
+                'harsh' => array(
+                    'algorithm' => 'bcrypt',
+                    'cost'      => '15'
+                ),
+            ),
+        ));
+
+This creates an encoder named ``harsh``. In order for a ``User`` instance
+to use it, the class must implement
+:class:`Symfony\\Component\\Security\\Core\\Encoder\\EncoderAwareInterface`.
+The interface requires one method - ``getEncoderName`` - which should reutrn
+the name of the encoder to use::
+
+    // src/Acme/UserBundle/Entity/User.php
+    namespace Acme\UserBundle\Entity;
+
+    use Symfony\Component\Security\Core\User\UserInterface;
+    use Symfony\Component\Security\Core\Encoder\EncoderAwareInterface;
+
+    class User implements UserInterface, EncoderAwareInterface
+    {
+        public function getEncoderName()
+        {
+            if ($this->isAdmin()) {
+                return 'harsh';
+            }
+
+            return null; // use the default encoder
+        }
+    }