diff --git a/book/security.rst b/book/security.rst
index 7e40fe7c3be..391856bb3ae 100644
--- a/book/security.rst
+++ b/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
-
-
-
-
-
-
-
-
-
-
-
- .. 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
...............................
diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc
index 6986e4b1ca0..380498f59e0 100644
--- a/cookbook/map.rst.inc
+++ b/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**
diff --git a/cookbook/security/index.rst b/cookbook/security/index.rst
index 63bd29520b3..59f9af787be 100644
--- a/cookbook/security/index.rst
+++ b/cookbook/security/index.rst
@@ -20,3 +20,4 @@ Security
custom_authentication_provider
target_path
csrf_in_login_form
+ named_encoders
diff --git a/cookbook/security/named_encoders.rst b/cookbook/security/named_encoders.rst
new file mode 100644
index 00000000000..fe54738f670
--- /dev/null
+++ b/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
+
+
+
+
+
+
+
+
+
+
+ .. 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
+
+
+
+
+
+
+
+
+
+
+
+ .. 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
+ }
+ }