merged branch weaverryan/security-phpdoc (PR #3055)

Commits
-------

8ee9161 [Security] Adding more extensive PHPDoc to UserInterface, AdvancedUserInterface and UserProviderInterface

Discussion
----------

More extensive PHPDoc for Security interfaces

Hey guys!

We've started to get into the habit of documenting interfaces and methods in the official docs. I think these things should be omitted from the documentation entirely, and replaced with a link to API docs that rock (I've started doing this already).

This PR just takes some of the details we have in the docs and pushes them back as PHPDoc. I use `@see`, `<code>` and changed a particular `@throws` to have a FQ class name since there's no `use` statement.

Thanks!

---------------------------------------------------------------------------

by weaverryan at 2012/01/07 20:24:15 -0800

Ok, updated and I think it's clearer now.

---------------------------------------------------------------------------

by fabpot at 2012/01/07 23:29:45 -0800

@weaverryan Great! I think that's a really good idea to document interfaces in the API, that makes a lot of sense.

---------------------------------------------------------------------------

by maastermedia at 2012/01/08 02:10:04 -0800

+1 Symfony API needs that atention also, yes. Thank you.

---------------------------------------------------------------------------

by lsmith77 at 2012/01/08 11:45:04 -0800

@fabpot: but then we should also add a list of interfaces to the API http://screencast.com/t/vu4Tljkri0

src/Symfony/Component/Security/Core/User/AdvancedUserInterface.php

@@ -12,8 +12,20 @@
 namespace Symfony\Component\Security\Core\User;
 
 /**
- * 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 Symfony\Component\Security\Core\Exception\AccountStatusException
  * @author Fabien Potencier <fabien@symfony.com>
  */
 interface AdvancedUserInterface extends UserInterface
@@ -21,6 +33,11 @@ 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.
+     *
+     * @see Symfony\Component\Security\Core\Exception\AccountExpiredException
+     *
      * @return Boolean true if the user's account is non expired, false otherwise
      */
     function isAccountNonExpired();
@@ -28,6 +45,11 @@ interface AdvancedUserInterface extends UserInterface
     /**
      * Checks whether the user is locked.
      *
+     * Internally, if this method returns false, the authentication system
+     * will throw a LockedException and prevent login.
+     *
+     * @see Symfony\Component\Security\Core\Exception\LockedException
+     *
      * @return Boolean true if the user is not locked, false otherwise
      */
     function isAccountNonLocked();
@@ -35,6 +57,11 @@ interface AdvancedUserInterface extends UserInterface
     /**
      * 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.
+     *
+     * @see Symfony\Component\Security\Core\Exception\CredentialsExpiredException
+     *
      * @return Boolean true if the user's credentials are non expired, false otherwise
      */
     function isCredentialsNonExpired();
@@ -42,6 +69,11 @@ interface AdvancedUserInterface extends UserInterface
     /**
      * Checks whether the user is enabled.
      *
+     * Internally, if this method returns false, the authentication system
+     * will throw a DisabledException and prevent login.
+     *
+     * @see Symfony\Component\Security\Core\Exception\DisabledException
+     *
      * @return Boolean true if the user is enabled, false otherwise
      */
     function isEnabled();

src/Symfony/Component/Security/Core/User/UserInterface.php

@@ -12,8 +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>
  */
 interface UserInterface
@@ -21,6 +33,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 +51,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
      */
@@ -49,11 +77,16 @@ 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()).
      *

src/Symfony/Component/Security/Core/User/UserProviderInterface.php

@@ -12,9 +12,19 @@
 namespace Symfony\Component\Security\Core\User;
 
 /**
- * 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 Symfony\Component\Security\Core\User\UserInterface
  * @author Fabien Potencier <fabien@symfony.com>
  */
 interface UserProviderInterface
@@ -25,7 +35,8 @@ interface UserProviderInterface
      * This method must throw UsernameNotFoundException if the user is not
      * found.
      *
-     * @throws UsernameNotFoundException if the user is not found
+     * @see UsernameNotFoundException
+     * @throws Symfony\Component\Security\Core\Exception\UsernameNotFoundException if the user is not found
      * @param string $username The username
      *
      * @return UserInterface
@@ -35,11 +46,12 @@ interface UserProviderInterface
     /**
      * 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.
+     * 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.
      *
-     * @throws UnsupportedUserException if the account is not supported
+     * @throws Symfony\Component\Security\Core\Exception\UnsupportedUserException if the account is not supported
      * @param UserInterface $user
      *
      * @return UserInterface