merged 2.0

3 files changed, 105 insertions, 11 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/UserInterface.php b/Core/User/UserInterface.php
index ed6ce0a..85356b7 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,10 +77,17 @@ interface UserInterface
 
     /**
      * Removes sensitive data from the user.
+     *
+     * This is important if, at any given point, sensitive information like
+     * the plain-text password is stored on this object.
+     *
+     * @return void
      */
     function eraseCredentials();
 
     /**
+     * Returns whether or not the given user is equivalent to *this* user.
+     *
      * The equality comparison should neither be done by referential equality
      * nor by comparing identities (i.e. getId() === getId()).
      *
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);