Merge pull request #989 from canni/document_security_bc_break

weaverryan · weaverryan · commit 8c1466a599c1 · 2012-01-22T10:19:16.000-08:00
Document BC Break introduced in commit 741859dc
diff --git a/book/security.rst b/book/security.rst
@@ -1004,6 +1004,13 @@ custom user class is that it implements the :class:`Symfony\\Component\\Security
 interface. This means that your concept of a "user" can be anything, as long
 as it implements this interface.
 
+.. versionadded:: 2.1
+
+   In Symfony 2.1 the ``Symfony\\Component\\Security\\Core\\User\\EquatableInterface``
+   was introduced, it contains single method ``isEqualTo(UserInterface $user)``.
+   You can implement this interface if you need to override default implementation
+   of comparsion logic in authentication mechanism.
+
 .. note::
 
     The user object will be serialized and saved in the session during requests,
diff --git a/cookbook/security/entity_provider.rst b/cookbook/security/entity_provider.rst
@@ -40,13 +40,21 @@ To make it shorter, the getter and setter methods for each have been removed to
 focus on the most important methods that come from the
 :class:`Symfony\\Component\\Security\\Core\\User\\UserInterface`.
 
+.. versionadded:: 2.1
+
+   In Symfony 2.1 the ``Symfony\\Component\\Security\\Core\\User\\EquatableInterface``
+   was introduced, it contains single method ``isEqualTo(UserInterface $user)``.
+   You can implement this interface if you need to override default implementation
+   of comparsion logic in authentication mechanism.
+
 .. code-block:: php
 
     // src/Acme/UserBundle/Entity/User.php
 
     namespace Acme\UserBundle\Entity;
 
     use Symfony\Component\Security\Core\User\UserInterface;
+    use Symfony\Component\Security\Core\User\EquatableInterface;
     use Doctrine\ORM\Mapping as ORM;
 
     /**
@@ -100,11 +108,6 @@ focus on the most important methods that come from the
             return array('ROLE_USER');
         }
 
-        public function equals(UserInterface $user)
-        {
-            return $user->getUsername() === $this->username;
-        }
-
         public function eraseCredentials()
         {
         }
@@ -123,18 +126,30 @@ focus on the most important methods that come from the
         {
             return $this->password;
         }
+
+        /**
+         * EquatableInterface
+         */
+        public function isEqualTo(UserInterface $user)
+        {
+            return $user->getUsername() === $this->username;
+        }
     }
 
 In order to use an instance of the ``AcmeUserBundle:User`` class in the Symfony
 security layer, the entity class must implement the
 :class:`Symfony\\Component\\Security\\Core\\User\\UserInterface`. This
-interface forces the class to implement the six following methods: ``getRoles()``,
-``getPassword()``, ``getSalt()``, ``getUsername()``, ``eraseCredentials()``,
-``equals()``. For more details on each of these, see :class:`Symfony\\Component\\Security\\Core\\User\\UserInterface`.
-
-To keep it simple, the ``equals()`` method just compares the ``username`` field
-but it's also possible to do more checks depending on the complexity of your
-data model. On the other hand, the ``eraseCredentials()`` method remains empty
+interface forces the class to implement the five following methods: ``getRoles()``,
+``getPassword()``, ``getSalt()``, ``getUsername()``, ``eraseCredentials()``.
+For more details on each of these, see :class:`Symfony\\Component\\Security\\Core\\User\\UserInterface`.
+
+To keep it simple, the ``isEqualTo()`` method form ``EquatableInterface``
+just compares the ``username`` field but it's also possible to do more checks
+depending on the complexity of your data model, also in most cases, implementing
+``EquatableInterface`` is not nessesery, because security component has good default
+implementation, see the ``hasUserChanged()`` method of
+:class:`Symfony\\Component\\Security\\Core\\Authentication\\Token\\AbstractToken`.
+On the other hand, the ``eraseCredentials()`` method remains empty
 as we don't care about it in this tutorial.
 
 Below is an export of my ``User`` table from MySQL. For details on how to
