1 files changed, 158 insertions, 30 deletions
diff --git a/framework/Security/TUserManager.php b/framework/Security/TUserManager.php
index efa17616..c4bcbacd 100644
--- a/framework/Security/TUserManager.php
+++ b/framework/Security/TUserManager.php
@@ -1,66 +1,96 @@
 <?php
+/**
+ * TUser, TUserManager class
+ *
+ * @author Qiang Xue <qiang.xue@gmail.com>
+ * @link http://www.pradosoft.com/
+ * @copyright Copyright &copy; 2005 PradoSoft
+ * @license http://www.pradosoft.com/license/
+ * @version $Revision: $  $Date: $
+ * @package System.Security
+ */
 
 /**
- * IUser interface.
+ * TUser class
  *
- * This interface must be implemented by user objects.
+ * TUser implements basic user functionality for a prado application.
+ * To get the name of the user, use {@link getName Name} property.
+ * The property {@link getIsGuest IsGuest} tells if the user a guest/anonymous user.
+ * To obtain or test the roles that the user is in, use property
+ * {@link getRoles Roles} and call {@link isInRole()}, respectively.
+ *
+ * TUser is meant to be used together with {@link TUserManager} and
+ * {@link TAuthManager}.
  *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @version $Revision: $  $Date: $
  * @package System.Security
  * @since 3.0
  */
-interface IUser
-{
-	public function getManager();
-	public function getName();
-	public function setName($value);
-	public function getIsGuest();
-	public function setIsGuest($value);
-	public function getRoles();
-	public function setRoles($value);
-	/**
-	 * @param string role to be tested
-	 * @return boolean whether the user is of this role
-	 */
-	public function isInRole($role);
-	public function saveToString();
-	public function loadFromString($string);
-}
-
 class TUser extends TComponent implements IUser
 {
+	/**
+	 * @var TUserManager user manager
+	 */
 	private $_manager;
-	private $_isGuest=false;
+	/**
+	 * @var boolean if the user is a guest
+	 */
+	private $_isGuest=true;
+	/**
+	 * @var string username
+	 */
 	private $_name='';
+	/**
+	 * @var array user roles
+	 */
 	private $_roles=array();
 
+	/**
+	 * Constructor.
+	 * @param TUserManager user manager
+	 */
 	public function __construct($manager=null)
 	{
 		parent::__construct();
 		$this->_manager=$manager;
 	}
 
+	/**
+	 * @return TUserManager user manager
+	 */
 	public function getManager()
 	{
 		return $this->_manager;
 	}
 
+	/**
+	 * @return string username
+	 */
 	public function getName()
 	{
 		return $this->_name;
 	}
 
+	/**
+	 * @param string username
+	 */
 	public function setName($value)
 	{
 		$this->_name=$value;
 	}
 
+	/**
+	 * @return boolean if the user is a guest
+	 */
 	public function getIsGuest()
 	{
 		return $this->_isGuest;
 	}
 
+	/**
+	 * @param boolean if the user is a guest
+	 */
 	public function setIsGuest($value)
 	{
 		$this->_isGuest=TPropertyValue::ensureBoolean($value);
@@ -71,11 +101,17 @@ class TUser extends TComponent implements IUser
 		}
 	}
 
+	/**
+	 * @return array list of roles that the user is of
+	 */
 	public function getRoles()
 	{
 		return $this->_roles;
 	}
 
+	/**
+	 * @return array|string list of roles that the user is of. If it is a string, roles are assumed by separated by comma
+	 */
 	public function setRoles($value)
 	{
 		if(is_array($value))
@@ -91,6 +127,10 @@ class TUser extends TComponent implements IUser
 		}
 	}
 
+	/**
+	 * @param string role to be tested. Note, role is case-insensitive.
+	 * @return boolean whether the user is of this role
+	 */
 	public function isInRole($role)
 	{
 		foreach($this->_roles as $r)
@@ -99,11 +139,18 @@ class TUser extends TComponent implements IUser
 		return false;
 	}
 
+	/**
+	 * @return string user data that is serialized and will be stored in session
+	 */
 	public function saveToString()
 	{
 		return serialize(array($this->_name,$this->_roles,$this->_isGuest));
 	}
 
+	/**
+	 * @param string user data that is serialized and restored from session
+	 * @return IUser the user object
+	 */
 	public function loadFromString($data)
 	{
 		if(!empty($data))
@@ -117,15 +164,61 @@ class TUser extends TComponent implements IUser
 	}
 }
 
-
+/**
+ * TUserManager class
+ *
+ * TUserManager manages a static list of users {@link TUser}.
+ * The user information is specified via module configuration using the following XML syntax,
+ * <code>
+ * <user name="Joe" password="demo" />
+ * <user name="John" password="demo" />
+ * <role name="Administrator" users="John" />
+ * <role name="Writer" users="Joe,John" />
+ * </code>
+ *
+ * The user passwords may be specified as clear text, SH1 or MD5 hashed by setting
+ * {@link setPasswordMode PasswordMode} as <b>Clear</b>, <b>SH1</b> or <b>MD5</b>.
+ * The default name for a guest user is <b>Guest</b>. It may be changed
+ * by setting {@link setGuestName GuestName} property.
+ *
+ * TUserManager may be used together with {@link TAuthManager} which manages
+ * how users are authenticated and authorized in a Prado application.
+ *
+ * @author Qiang Xue <qiang.xue@gmail.com>
+ * @version $Revision: $  $Date: $
+ * @package System.Security
+ * @since 3.0
+ */
 class TUserManager extends TComponent implements IModule
 {
+	/**
+	 * @var string id of this module
+	 */
 	private $_id;
+	/**
+	 * @var array list of users managed by this module
+	 */
 	private $_users=array();
+	/**
+	 * @var array list of roles managed by this module
+	 */
 	private $_roles=array();
+	/**
+	 * @var string guest name
+	 */
 	private $_guestName='Guest';
+	/**
+	 * @var string password mode, Clear|MD5|SH1
+	 */
 	private $_passwordMode='MD5';
 
+	/**
+	 * Initializes the module.
+	 * This method is required by IModule and is invoked by application.
+	 * It loads user/role information from the module configuration.
+	 * @param TApplication application
+	 * @param TXmlElement module configuration
+	 */
 	public function init($application,$config)
 	{
 		foreach($config->getElementsByTagName('user') as $node)
@@ -140,36 +233,60 @@ class TUserManager extends TComponent implements IModule
 		}
 	}
 
+	/**
+	 * @return string id of this module
+	 */
 	public function getID()
 	{
 		return $this->_id;
 	}
 
+	/**
+	 * @param string id of this module
+	 */
 	public function setID($value)
 	{
 		$this->_id=$value;
 	}
 
+	/**
+	 * @return string guest name, defaults to 'Guest'
+	 */
 	public function getGuestName()
 	{
 		return $this->_guestName;
 	}
 
+	/**
+	 * @param string name to be used for guest users.
+	 */
 	public function setGuestName($value)
 	{
 		$this->_guestName=$value;
 	}
 
+	/**
+	 * @return string (Clear|MD5|SH1) how password is stored, clear text, or MD5 or SH1 hashed. Default to MD5.
+	 */
 	public function getPasswordMode()
 	{
 		return $this->_passwordMode;
 	}
 
+	/**
+	 * @param string (Clear|MD5|SH1) how password is stored, clear text, or MD5 or SH1 hashed.
+	 */
 	public function setPasswordMode($value)
 	{
 		$this->_passwordMode=TPropertyValue::ensureEnum($value,array('Clear','MD5','SHA1'));
 	}
 
+	/**
+	 * Validates if the username and password are correct.
+	 * @param string user name
+	 * @param string password
+	 * @return boolean true if validation is successful, false otherwise.
+	 */
 	public function validateUser($username,$password)
 	{
 		if($this->_passwordMode==='MD5')
@@ -180,19 +297,17 @@ class TUserManager extends TComponent implements IModule
 		return (isset($this->_users[$username]) && $this->_users[$username]===$password);
 	}
 
-	public function logout($user)
-	{
-		$user->setIsGuest(true);
-		$user->setName($this->getGuestName());
-		$user->setRoles(array());
-	}
-
+	/**
+	 * Returns a user instance given the user name.
+	 * @param string user name, null if it is a guest.
+	 * @return TUser the user instance, null if the specified username is not in the user database.
+	 */
 	public function getUser($username=null)
 	{
 		if($username===null)
 		{
 			$user=new TUser($this);
-			$user->setIsGuest($username===null);
+			$user->setIsGuest(true);
 			return $user;
 		}
 		else
@@ -202,6 +317,7 @@ class TUserManager extends TComponent implements IModule
 			{
 				$user=new TUser($this);
 				$user->setName($username);
+				$user->setIsGuest(false);
 				if(isset($this->_roles[$username]))
 					$user->setRoles($this->_roles[$username]);
 				return $user;
@@ -210,6 +326,18 @@ class TUserManager extends TComponent implements IModule
 				return null;
 		}
 	}
+
+	/**
+	 * Sets a user as a guest.
+	 * User name is changed as guest name, and roles are emptied.
+	 * @param TUser the user to be changed to a guest.
+	 */
+	public function switchToGuest($user)
+	{
+		$user->setIsGuest(true);
+		$user->setName($this->getGuestName());
+		$user->setRoles(array());
+	}
 }
 
 ?>
 \ No newline at end of file