5 files changed, 139 insertions, 62 deletions
diff --git a/Core/User/AdvancedUserInterface.php b/Core/User/AdvancedUserInterface.php
index ba528a1..e951c65 100644
--- a/Core/User/AdvancedUserInterface.php
+++ b/Core/User/AdvancedUserInterface.php
@@ -11,8 +11,27 @@
 
 namespace Symfony\Component\Security\Core\User;
 
+use Symfony\Component\Security\Core\Exception\AccountStatusException;
+use Symfony\Component\Security\Core\Exception\AccountExpiredException;
+use Symfony\Component\Security\Core\Exception\LockedException;
+use Symfony\Component\Security\Core\Exception\CredentialsExpiredException;
+use Symfony\Component\Security\Core\Exception\DisabledException;
+
 /**
- * AdvancedUserInterface adds status flags to a regular account.
+ * Adds extra features to a user class related to account status flags.
+ *
+ * This interface can be implemented in place of UserInterface if you'd like
+ * the authentication system to consider different account status flags
+ * during authentication. If any of the methods in this interface return
+ * false, authentication will fail.
+ *
+ * If you need to perform custom logic for any of these situations, then
+ * you will need to register an exception listener and watch for the specific
+ * exception instances thrown in each case. All exceptions are a subclass
+ * of AccountStatusException
+ *
+ * @see UserInterface
+ * @see AccountStatusException
  *
  * @author Fabien Potencier <fabien@symfony.com>
  */
@@ -21,28 +40,48 @@ interface AdvancedUserInterface extends UserInterface
     /**
      * Checks whether the user's account has expired.
      *
+     * Internally, if this method returns false, the authentication system
+     * will throw an AccountExpiredException and prevent login.
+     *
      * @return Boolean true if the user's account is non expired, false otherwise
+     *
+     * @see AccountExpiredException
      */
     function isAccountNonExpired();
 
     /**
      * Checks whether the user is locked.
      *
+     * Internally, if this method returns false, the authentication system
+     * will throw a LockedException and prevent login.
+     *
      * @return Boolean true if the user is not locked, false otherwise
+     *
+     * @see LockedException
      */
     function isAccountNonLocked();
 
     /**
      * Checks whether the user's credentials (password) has expired.
      *
+     * Internally, if this method returns false, the authentication system
+     * will throw a CredentialsExpiredException and prevent login.
+     *
      * @return Boolean true if the user's credentials are non expired, false otherwise
+     *
+     * @see CredentialsExpiredException
      */
     function isCredentialsNonExpired();
 
     /**
      * Checks whether the user is enabled.
      *
+     * Internally, if this method returns false, the authentication system
+     * will throw a DisabledException and prevent login.
+     *
      * @return Boolean true if the user is enabled, false otherwise
+     *
+     * @see DisabledException
      */
     function isEnabled();
 }
diff --git a/Core/User/EquatableInterface.php b/Core/User/EquatableInterface.php
new file mode 100644
index 0000000..e2bde9e
--- /dev/null
+++ b/Core/User/EquatableInterface.php
@@ -0,0 +1,37 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Security\Core\User;
+
+/**
+ * EquatableInterface used to test if two objects are equal in security
+ * and re-authentication context.
+ *
+ * @author Dariusz Górecki <darek.krk@gmail.com>
+ */
+interface EquatableInterface
+{
+    /**
+     * The equality comparison should neither be done by referential equality
+     * nor by comparing identities (i.e. getId() === getId()).
+     *
+     * However, you do not need to compare every attribute, but only those that
+     * are relevant for assessing whether re-authentication is required.
+     *
+     * Also implementation should consider that $user instance may implement
+     * the extended user interface `AdvancedUserInterface`.
+     *
+     * @param UserInterface $user
+     *
+     * @return Boolean
+     */
+    function isEqualTo(UserInterface $user);
+}
diff --git a/Core/User/User.php b/Core/User/User.php
index d586511..6076603 100644
--- a/Core/User/User.php
+++ b/Core/User/User.php
@@ -112,44 +112,4 @@ final class User implements AdvancedUserInterface
     public function eraseCredentials()
     {
     }
-
-    /**
-     * {@inheritDoc}
-     */
-    public function equals(UserInterface $user)
-    {
-        if (!$user instanceof User) {
-            return false;
-        }
-
-        if ($this->password !== $user->getPassword()) {
-            return false;
-        }
-
-        if ($this->getSalt() !== $user->getSalt()) {
-            return false;
-        }
-
-        if ($this->username !== $user->getUsername()) {
-            return false;
-        }
-
-        if ($this->accountNonExpired !== $user->isAccountNonExpired()) {
-            return false;
-        }
-
-        if ($this->accountNonLocked !== $user->isAccountNonLocked()) {
-            return false;
-        }
-
-        if ($this->credentialsNonExpired !== $user->isCredentialsNonExpired()) {
-            return false;
-        }
-
-        if ($this->enabled !== $user->isEnabled()) {
-            return false;
-        }
-
-        return true;
-    }
 }
diff --git a/Core/User/UserInterface.php b/Core/User/UserInterface.php
index f6356fe..ce3b3a8 100644
--- a/Core/User/UserInterface.php
+++ b/Core/User/UserInterface.php
@@ -12,7 +12,20 @@
 namespace Symfony\Component\Security\Core\User;
 
 /**
- * UserInterface is the interface that user classes must implement.
+ * Represents the interface that all user classes must implement.
+ *
+ * This interface is useful because the authentication layer can deal with
+ * the object through its lifecycle, using the object to get the encoded
+ * password (for checking against a submitted password), assigning roles
+ * and so on.
+ *
+ * Regardless of how your user are loaded or where they come from (a database,
+ * configuration, web service, etc), you will have a class that implements
+ * this interface. Objects that implement this interface are created and
+ * loaded by different objects that implement UserProviderInterface
+ *
+ * @see UserProviderInterface
+ * @see AdvancedUserInterface
  *
  * @author Fabien Potencier <fabien@symfony.com>
  */
@@ -21,6 +34,17 @@ interface UserInterface
     /**
      * Returns the roles granted to the user.
      *
+     * <code>
+     * public function getRoles()
+     * {
+     *     return array('ROLE_USER');
+     * }
+     * </code>
+     *
+     * Alternatively, the roles might be stored on a ``roles`` property,
+     * and populated in any number of different ways when the user object
+     * is created.
+     *
      * @return Role[] The user roles
      */
     function getRoles();
@@ -28,12 +52,17 @@ interface UserInterface
     /**
      * Returns the password used to authenticate the user.
      *
+     * This should be the encoded password. On authentication, a plain-text
+     * password will be salted, encoded, and then compared to this value.
+     *
      * @return string The password
      */
     function getPassword();
 
     /**
-     * Returns the salt.
+     * Returns the salt that was originally used to encode the password.
+     *
+     * This can return null if the password was not encoded using a salt.
      *
      * @return string The salt
      */
@@ -48,18 +77,11 @@ interface UserInterface
 
     /**
      * Removes sensitive data from the user.
-     */
-    function eraseCredentials();
-
-    /**
-     * The equality comparison should neither be done by referential equality
-     * nor by comparing identities (i.e. getId() === getId()).
      *
-     * However, you do not need to compare every attribute, but only those that
-     * are relevant for assessing whether re-authentication is required.
+     * This is important if, at any given point, sensitive information like
+     * the plain-text password is stored on this object.
      *
-     * @param UserInterface $user
-     * @return Boolean
+     * @return void
      */
-    function equals(UserInterface $user);
+    function eraseCredentials();
 }
diff --git a/Core/User/UserProviderInterface.php b/Core/User/UserProviderInterface.php
index 11fd62c..dbd7924 100644
--- a/Core/User/UserProviderInterface.php
+++ b/Core/User/UserProviderInterface.php
@@ -11,9 +11,23 @@
 
 namespace Symfony\Component\Security\Core\User;
 
+use Symfony\Component\Security\Core\Exception\UsernameNotFoundException;
+use Symfony\Component\Security\Core\Exception\UnsupportedUserException;
+
 /**
- * UserProviderInterface is the implementation that all user provider must
- * implement.
+ * Represents a class that loads UserInterface objects from some source for the authentication system.
+ *
+ * In a typical authentication configuration, a username (i.e. some unique
+ * user identifier) credential enters the system (via form login, or any
+ * method). The user provider that is configured with that authentication
+ * method is asked to load the UserInterface object for the given username
+ * (via loadUserByUsername) so that the rest of the process can continue.
+ *
+ * Internally, a user provider can load users from any source (databases,
+ * configuration, web service). This is totally independent of how the authentication
+ * information is submitted or what the UserInterface object looks like.
+ *
+ * @see UserInterface
  *
  * @author Fabien Potencier <fabien@symfony.com>
  */
@@ -25,24 +39,29 @@ interface UserProviderInterface
      * This method must throw UsernameNotFoundException if the user is not
      * found.
      *
-     * @throws UsernameNotFoundException if the user is not found
      * @param string $username The username
      *
      * @return UserInterface
+     *
+     * @see UsernameNotFoundException
+     *
+     * @throws UsernameNotFoundException if the user is not found
+     *
      */
     function loadUserByUsername($username);
 
     /**
      * Refreshes the user for the account interface.
      *
-     * It is up to the implementation if it decides to reload the user data
-     * from the database, or if it simply merges the passed User into the
-     * identity map of an entity manager.
-     *
-     * @throws UnsupportedUserException if the account is not supported
+     * It is up to the implementation to decide if the user data should be
+     * totally reloaded (e.g. from the database), or if the UserInterface
+     * object can just be merged into some internal array of users / identity
+     * map.
      * @param UserInterface $user
      *
      * @return UserInterface
+     *
+     * @throws UnsupportedUserException if the account is not supported
      */
     function refreshUser(UserInterface $user);