WebSVN – lars-tiefland.prado – /framework/Security/TDbUserManager.php

<?php
/**
 * TDbUserManager class
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @link http://www.pradosoft.com/
 * @copyright Copyright &copy; 2005-2008 PradoSoft
 * @license http://www.pradosoft.com/license/
 * @version $Id: TDbUserManager.php 2541 2008-10-21 15:05:13Z qiang.xue $
 * @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: TDbUserManager.php 2541 2008-10-21 15:05:13Z qiang.xue $
 * @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);
                        $this->_conn->setActive(true);
                }
                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_required');
        }

        /**
         * Returns a user instance according to auth data stored in a cookie.
         * @param THttpCookie the cookie storing user authentication information
         * @return TDbUser the user instance generated based on the cookie auth data, null if the cookie does not have valid auth data.
         * @since 3.1.1
         */
        public function getUserFromCookie($cookie)
        {
                return $this->_userFactory->createUserFromCookie($cookie);
        }

        /**
         * Saves user auth data into a cookie.
         * @param THttpCookie the cookie to receive the user auth data.
         * @since 3.1.1
         */
        public function saveUserToCookie($cookie)
        {
                $user=$this->getApplication()->getUser();
                if($user instanceof TDbUser)
                        $user->saveUserToCookie($cookie);
        }
}


/**
 * 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: TDbUserManager.php 2541 2008-10-21 15:05:13Z qiang.xue $
 * @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);

        /**
         * Creates a new user instance given the cookie containing auth data.
         *
         * This method is invoked when {@link TAuthManager::setAllowAutoLogin AllowAutoLogin} is set true.
         * The default implementation simply returns null, meaning no user instance can be created
         * from the given cookie.
         *
         * If you want to support automatic login (remember login), you should override this method.
         * Typically, you obtain the username and a unique token from the cookie's value.
         * You then verify the token is valid and use the username to create a user instance.
         *
         * @param THttpCookie the cookie storing user authentication information
         * @return TDbUser the user instance generated based on the cookie auth data, null if the cookie does not have valid auth data.
         * @see saveUserToCookie
         * @since 3.1.1
         */
        public function createUserFromCookie($cookie)
        {
                return null;
        }

        /**
         * Saves necessary auth data into a cookie.
         * This method is invoked when {@link TAuthManager::rememberLogin} is invoked.
         * The default implementation does nothing, meaning auth data is not stored in the cookie
         * (and thus automatic login is not supported.)
         *
         * If you want to support automatic login (remember login), you should override this method.
         * Typically, you generate a unique token according to the current login information
         * and save it together with the username in the cookie's value.
         * You should avoid revealing the password in the generated token.
         *
         * @param THttpCookie the cookie to store the user auth information
         * @see createUserFromCookie
         * @since 3.1.1
         */
        public function saveUserToCookie($cookie)
        {
        }
}
Subversion-Projekte lars-tiefland.prado

(root)/framework/Security/TDbUserManager.php @ 14 – Revision 1
