Added feature doc for named encoders

tamirvs · tamirvs · commit 8cd63d069534 · 2014-01-19T10:18:25.000+02:00
diff --git a/book/security.rst b/book/security.rst
@@ -1466,6 +1466,79 @@ 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).
 
+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;
+
+    class User implements UserInterface, EncoderAwareInterface
+    {
+        public function getEncoderName()
+        {
+            if ($this->isAdmin()) {
+                return 'harsh';
+            }
+            
+            return null; // use the default encoder
+        }
+    }
+
 Determining the Hashed Password
 ...............................
 
