added TDbUserManager and TDbUser.

8 files changed, 298 insertions, 6 deletions

diff --git a/.gitattributes b/.gitattributes
index 35538c44..74d07fd3 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -1890,6 +1890,7 @@ framework/PradoBase.php -text
 framework/Security/IUserManager.php -text
 framework/Security/TAuthManager.php -text
 framework/Security/TAuthorizationRule.php -text
+framework/Security/TDbUserManager.php -text
 framework/Security/TSecurityManager.php -text
 framework/Security/TUser.php -text
 framework/Security/TUserManager.php -text
diff --git a/COPYRIGHT b/COPYRIGHT
index f44d0d05..017e13ed 100644
--- a/COPYRIGHT
+++ b/COPYRIGHT
@@ -1,7 +1,7 @@
 The PRADO framework and the included demos are freeware.

 They are released under the terms of the following BSD License.

 

-Copyright 2004-2006, The PRADO Group (http://www.pradosoft.com)

+Copyright 2004-2007, The PRADO Group (http://www.pradosoft.com)

 All rights reserved.

 

 Redistribution and use in source and binary forms, with or without

diff --git a/HISTORY b/HISTORY
index 7c643a09..00ab2908 100644
--- a/HISTORY
+++ b/HISTORY
@@ -22,6 +22,7 @@ ENH: Improved exception display with hyperlinked keywords (Qiang)
 ENH: Improved exception display about template syntax error (Qiang)
 NEW: TShellApplication (Qiang)
 NEW: TDbCache (Qiang)
+NEW: TDbUserManager and TDbUser (Qiang)
 NEW: Active Record driver for IBM DB2 (Cesar Ramos)
 
 Version 3.1.0 alpha January 15, 2007
diff --git a/demos/quickstart/protected/pages/Advanced/Auth.page b/demos/quickstart/protected/pages/Advanced/Auth.page
index 2c335f88..c8380901 100644
--- a/demos/quickstart/protected/pages/Advanced/Auth.page
+++ b/demos/quickstart/protected/pages/Advanced/Auth.page
@@ -89,4 +89,32 @@ We have seen in the above example that two users are specified in the applicatio
 <p id="720562" class="block-content">

 where the <tt>roles</tt> attribute in <tt>user</tt> element is optional. User roles can be specified in either the <tt>user</tt> element or in a separate <tt>role</tt> element.

 </p>

+

+<h2 id="5505">Using <tt>TDbUserManager</tt></h2>

+<p id="720563" class="block-content">

+<tt>TDbUserManager</tt> is introduced in v3.1.0. Its main purpose is to simplify the task of managing user accounts that are stored in a database. It requires developers to write a user class that represents the necessary information for a user account. The user class must extend from <tt>TDbUser</tt>.

+</p>

+<p id="720564" class="block-content">

+To use <tt>TDbUserManager</tt>, configure it in the application configuration like following:

+</p>

+<com:TTextHighlighter Language="xml" CssClass="source block-content" id="code4">

+<module id="db"

+     class="System.Data.TDataSourceConfig" ..../>

+<module id="users"

+     class="System.Security.TDbUserManager"

+     UserClass="Path.To.MyUserClass"

+     ConnectionID="db" />

+<module id="auth"

+     class="System.Security.TAuthManager"

+     UserManager="users" LoginPage="Path.To.LoginPage" />

+</com:TTextHighlighter>

+

+</p>

+<p id="720565" class="block-content">

+In the above, <tt>UserClass</tt> specifies what class will be used to create user instance. The class must extend from <tt>TDbUser</tt>. <tt>ConnectionID</tt> refers to the ID of a <tt>TDataSourceConfig</tt> module which specifies how to establish database connection to retrieve user information.

+</p>

+<p id="720566" class="block-content">

+The user class has to implement the two abstract methods in <tt>TDbUser</tt>: <tt>validateUser()</tt> and <tt>createUser()</tt>. Since user account information is stored in a database, the user class may make use of its <tt>DbConnection</tt> property to reach the database.

+</p>

+

 <div class="last-modified">$Id$</div></com:TContent>
\ No newline at end of file
diff --git a/demos/quickstart/protected/pages/GettingStarted/Introduction.page b/demos/quickstart/protected/pages/GettingStarted/Introduction.page
index 0871921a..e48360d6 100644
--- a/demos/quickstart/protected/pages/GettingStarted/Introduction.page
+++ b/demos/quickstart/protected/pages/GettingStarted/Introduction.page
@@ -4,12 +4,15 @@
 <p id="10001">

 This Quickstart tutorial is provided to help you quickly start building your own Web applications based on PRADO version 3.x.

 </p>

+<p>

+If you are an existing PRADO 3.x user and would like to learn what enhancements are available for each new version, please check out the <a href="?page=GettingStarted.NewFeatures">new features</a> page. Otherwise, the following sections are helpful for newbies.

+</p>

 <div class="start-page">

 	<div class="concepts start-block">

-	<h2>How Prado Works</h2>

+	<h2>How PRADO Works</h2>

 	<p>Concepts and fundamentals</p>

 	<ol>

-		<li><a href="#">Building web applications with Prado</a></li>

+		<li><a href="#">Building web applications with PRADO</a></li>

 		<li><a href="#">Web controls and events</a></li>

 		<li><a href="#">Validating user input</a></li>

 		<li><a href="#">Connecting to your database</a></li>

diff --git a/demos/quickstart/protected/pages/GettingStarted/NewFeatures.page b/demos/quickstart/protected/pages/GettingStarted/NewFeatures.page
index cfbb3e8e..4aff6d47 100644
--- a/demos/quickstart/protected/pages/GettingStarted/NewFeatures.page
+++ b/demos/quickstart/protected/pages/GettingStarted/NewFeatures.page
@@ -19,6 +19,8 @@ This page summarizes the main new features that are introduced in each PRADO rel
 

 <li>Added support to allow <a href="?page=Configurations.AppConfig">including external application configurations</a>. Enhanced template syntax to facilitate <a href="?page=Configurations.Templates1">subproperty configuration</a>.</li>

 

+<li>Added TDbUserManager and TDbUser to simplify <a href="?page=Advanced.Auth">authentication and authorization</a> with user accounts stored in a database.</li>

+

 </ul>

 

 <div class="last-modified">$Id$</div>

diff --git a/framework/Data/TDataSourceConfig.php b/framework/Data/TDataSourceConfig.php
index 93857b16..df444e97 100644
--- a/framework/Data/TDataSourceConfig.php
+++ b/framework/Data/TDataSourceConfig.php
@@ -10,6 +10,8 @@
  * @package System.Data

  */

 

+Prado::using('System.Data.TDbConnection');

+

 /**

  * TDataSourceConfig module class provides <module> configuration for database connections.

  *

@@ -46,7 +48,7 @@
  */

 class TDataSourceConfig extends TModule

 {

-	private $_connID;

+	private $_connID='';

 	private $_conn;

 	private $_connClass='System.Data.TDbConnection';

 

@@ -91,9 +93,9 @@ class TDataSourceConfig extends TModule
 	 */

 	public function getDbConnection()

 	{

-		if(is_null($this->_conn))

+		if($this->_conn===null)

 		{

-			if(!is_null($this->_connID))

+			if($this->_connID!=='')

 				$this->_conn = $this->findConnectionByID($this->getConnectionID());

 			else

 				$this->_conn = Prado::createComponent($this->getConnectionClass());

diff --git a/framework/Security/TDbUserManager.php b/framework/Security/TDbUserManager.php
new file mode 100644
index 00000000..587fe0db
--- /dev/null
+++ b/framework/Security/TDbUserManager.php
@@ -0,0 +1,255 @@
+<?php

+/**

+ * TDbUserManager class

+ *

+ * @author Qiang Xue <qiang.xue@gmail.com>

+ * @link http://www.pradosoft.com/

+ * @copyright Copyright &copy; 2005-2007 PradoSoft

+ * @license http://www.pradosoft.com/license/

+ * @version $Id: $

+ * @package System.Security

+ */

+

+/**

+ * Using IUserManager interface

+ */

+Prado::using('System.Security.IUserManager');

+Prado::using('System.Data.TDataSourceConfig');

+Prado::using('System.Security.TUser');

+

+/**

+ * TDbUserManager class

+ *

+ * TDbUserManager manages user accounts that are stored in a database.

+ * TDbUserManager is mainly designed to be used together with {@link TAuthManager}

+ * which manages how users are authenticated and authorized in a Prado application.

+ *

+ * To use TDbUserManager together with TAuthManager, configure them in

+ * the application configuration like following:

+ * <code>

+ * <module id="db"

+ *     class="System.Data.TDataSourceConfig" ..../>

+ * <module id="users"

+ *     class="System.Security.TDbUserManager"

+ *     UserClass="Path.To.MyUserClass"

+ *     ConnectionID="db" />

+ * <module id="auth"

+ *     class="System.Security.TAuthManager"

+ *     UserManager="users" LoginPage="Path.To.LoginPage" />

+ * </code>

+ *

+ * In the above, {@link setUserClass UserClass} specifies what class will be used

+ * to create user instance. The class must extend from {@link TDbUser}.

+ * {@link setConnectionID ConnectionID} refers to the ID of a {@link TDataSourceConfig} module

+ * which specifies how to establish database connection to retrieve user information.

+ *

+ * @author Qiang Xue <qiang.xue@gmail.com>

+ * @version $Id: $

+ * @package System.Security

+ * @since 3.1.0

+ */

+class TDbUserManager extends TModule implements IUserManager

+{

+	private $_connID='';

+	private $_conn;

+	private $_guestName='Guest';

+	private $_userClass='';

+	private $_userFactory;

+

+	/**

+	 * Initializes the module.

+	 * This method is required by IModule and is invoked by application.

+	 * @param TXmlElement module configuration

+	 */

+	public function init($config)

+	{

+		if($this->_userClass==='')

+			throw new TConfigurationException('dbusermanager_userclass_required');

+		$this->_userFactory=Prado::createComponent($this->_userClass,$this);

+		if(!($this->_userFactory instanceof TDbUser))

+			throw new TInvalidDataTypeException('dbusermanager_userclass_invalid',$this->_userClass);

+	}

+

+	/**

+	 * @return string the user class name in namespace format. Defaults to empty string, meaning not set.

+	 */

+	public function getUserClass()

+	{

+		return $this->_userClass;

+	}

+

+	/**

+	 * @param string the user class name in namespace format. The user class must extend from {@link TDbUser}.

+	 */

+	public function setUserClass($value)

+	{

+		$this->_userClass=$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;

+	}

+

+	/**

+	 * 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)

+	{

+		return $this->_userFactory->validateUser($username,$password);

+	}

+

+	/**

+	 * 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=Prado::createComponent($this->_userClass,$this);

+			$user->setIsGuest(true);

+			return $user;

+		}

+		else

+			return $this->_userFactory->createUser($username);

+	}

+

+	/**

+	 * @return string the ID of a TDataSourceConfig module. Defaults to empty string, meaning not set.

+	 */

+	public function getConnectionID()

+	{

+		return $this->_connID;

+	}

+

+	/**

+	 * Sets the ID of a TDataSourceConfig module.

+	 * The datasource module will be used to establish the DB connection

+	 * that will be used by the user manager.

+	 * @param string module ID.

+	 */

+	public function setConnectionID($value)

+	{

+		$this->_connID=$value;

+	}

+

+	/**

+	 * @return TDbConnection the database connection that may be used to retrieve user data.

+	 */

+	public function getDbConnection()

+	{

+		if($this->_conn===null)

+			$this->_conn=$this->createDbConnection($this->_connID);

+		return $this->_conn;

+	}

+

+	/**

+	 * Creates the DB connection.

+	 * @param string the module ID for TDataSourceConfig

+	 * @return TDbConnection the created DB connection

+	 * @throws TConfigurationException if module ID is invalid or empty

+	 */

+	protected function createDbConnection($connectionID)

+	{

+		if($connectionID!=='')

+		{

+			$conn=$this->getApplication()->getModule($connectionID);

+			if($conn instanceof TDataSourceConfig)

+				return $conn->getDbConnection();

+			else

+				throw new TConfigurationException('dbusermanager_connectionid_invalid',$connectionID);

+		}

+		else

+			throw new TConfigurationException('dbusermanager_connectionid_empty');

+	}

+}

+

+

+/**

+ * TDbUser class

+ *

+ * TDbUser is the base user class for using together with {@link TDbUserManager}.

+ * Two methods are declared and must be implemented in the descendant classes:

+ * - {@link validateUser()}: validates if username and password are correct entries.

+ * - {@link createUser()}: creates a new user instance given the username

+ *

+ * @author Qiang Xue <qiang.xue@gmail.com>

+ * @version $Id: $

+ * @package System.Security

+ * @since 3.1.0

+ */

+abstract class TDbUser extends TUser

+{

+	private $_connection;

+

+	/**

+	 * Returns a database connection that may be used to retrieve data from database.

+	 *

+	 * @return TDbConnection database connection that may be used to retrieve data from database

+	 */

+	public function getDbConnection()

+	{

+		if($this->_connection===null)

+		{

+			$userManager=$this->getManager();

+			if($userManager instanceof TDbUserManager)

+			{

+				$connection=$userManager->getDbConnection();

+				if($connection instanceof TDbConnection)

+				{

+					$connection->setActive(true);

+					$this->_connection=$connection;

+				}

+			}

+			if($this->_connection===null)

+				throw new TConfigurationException('dbuser_dbconnection_invalid');

+		}

+		return $this->_connection;

+	}

+

+	/**

+	 * Validates if username and password are correct entries.

+	 * Usually, this is accomplished by checking if the user database

+	 * contains this (username, password) pair.

+	 * You may use {@link getDbConnection DbConnection} to deal with database.

+	 * @param string username (case-sensitive)

+	 * @param string password

+	 * @return boolean whether the validation succeeds

+	 */

+	abstract public function validateUser($username,$password);

+

+	/**

+	 * Creates a new user instance given the username.

+	 * This method usually needs to retrieve necessary user information

+	 * (e.g. role, name, rank, etc.) from the user database according to

+	 * the specified username. The newly created user instance should be

+	 * initialized with these information.

+	 *

+	 * If the username is invalid (not found in the user database), null

+	 * should be returned.

+	 *

+	 * You may use {@link getDbConnection DbConnection} to deal with database.

+	 *

+	 * @param string username (case-sensitive)

+	 * @return TDbUser the newly created and initialized user instance

+	 */

+	abstract public function createUser($username);

+}

+

+?>
\ No newline at end of file