git.sur5r.net Git - bacula/bacula/blob - gui/baculum/framework/Security/TDbUserManager.php

   1 <?php
   2 /**
   3  * TDbUserManager class
   4  *
   5  * @author Qiang Xue <qiang.xue@gmail.com>
   6  * @link http://www.pradosoft.com/
   7  * @copyright Copyright &copy; 2005-2013 PradoSoft
   8  * @license http://www.pradosoft.com/license/
   9  * @version $Id: TDbUserManager.php 3245 2013-01-07 20:23:32Z ctrlaltca $
  10  * @package System.Security
  11  */
  12
  13 /**
  14  * Using IUserManager interface
  15  */
  16 Prado::using('System.Security.IUserManager');
  17 Prado::using('System.Data.TDataSourceConfig');
  18 Prado::using('System.Security.TUser');
  19
  20 /**
  21  * TDbUserManager class
  22  *
  23  * TDbUserManager manages user accounts that are stored in a database.
  24  * TDbUserManager is mainly designed to be used together with {@link TAuthManager}
  25  * which manages how users are authenticated and authorized in a Prado application.
  26  *
  27  * To use TDbUserManager together with TAuthManager, configure them in
  28  * the application configuration like following:
  29  * <code>
  30  * <module id="db"
  31  *     class="System.Data.TDataSourceConfig" ..../>
  32  * <module id="users"
  33  *     class="System.Security.TDbUserManager"
  34  *     UserClass="Path.To.MyUserClass"
  35  *     ConnectionID="db" />
  36  * <module id="auth"
  37  *     class="System.Security.TAuthManager"
  38  *     UserManager="users" LoginPage="Path.To.LoginPage" />
  39  * </code>
  40  *
  41  * In the above, {@link setUserClass UserClass} specifies what class will be used
  42  * to create user instance. The class must extend from {@link TDbUser}.
  43  * {@link setConnectionID ConnectionID} refers to the ID of a {@link TDataSourceConfig} module
  44  * which specifies how to establish database connection to retrieve user information.
  45  *
  46  * @author Qiang Xue <qiang.xue@gmail.com>
  47  * @version $Id: TDbUserManager.php 3245 2013-01-07 20:23:32Z ctrlaltca $
  48  * @package System.Security
  49  * @since 3.1.0
  50  */
  51 class TDbUserManager extends TModule implements IUserManager
  52 {
  53         private $_connID='';
  54         private $_conn;
  55         private $_guestName='Guest';
  56         private $_userClass='';
  57         private $_userFactory;
  58
  59         /**
  60          * Initializes the module.
  61          * This method is required by IModule and is invoked by application.
  62          * @param TXmlElement module configuration
  63          */
  64         public function init($config)
  65         {
  66                 if($this->_userClass==='')
  67                         throw new TConfigurationException('dbusermanager_userclass_required');
  68                 $this->_userFactory=Prado::createComponent($this->_userClass,$this);
  69                 if(!($this->_userFactory instanceof TDbUser))
  70                         throw new TInvalidDataTypeException('dbusermanager_userclass_invalid',$this->_userClass);
  71         }
  72
  73         /**
  74          * @return string the user class name in namespace format. Defaults to empty string, meaning not set.
  75          */
  76         public function getUserClass()
  77         {
  78                 return $this->_userClass;
  79         }
  80
  81         /**
  82          * @param string the user class name in namespace format. The user class must extend from {@link TDbUser}.
  83          */
  84         public function setUserClass($value)
  85         {
  86                 $this->_userClass=$value;
  87         }
  88
  89         /**
  90          * @return string guest name, defaults to 'Guest'
  91          */
  92         public function getGuestName()
  93         {
  94                 return $this->_guestName;
  95         }
  96
  97         /**
  98          * @param string name to be used for guest users.
  99          */
 100         public function setGuestName($value)
 101         {
 102                 $this->_guestName=$value;
 103         }
 104
 105         /**
 106          * Validates if the username and password are correct.
 107          * @param string user name
 108          * @param string password
 109          * @return boolean true if validation is successful, false otherwise.
 110          */
 111         public function validateUser($username,$password)
 112         {
 113                 return $this->_userFactory->validateUser($username,$password);
 114         }
 115
 116         /**
 117          * Returns a user instance given the user name.
 118          * @param string user name, null if it is a guest.
 119          * @return TUser the user instance, null if the specified username is not in the user database.
 120          */
 121         public function getUser($username=null)
 122         {
 123                 if($username===null)
 124                 {
 125                         $user=Prado::createComponent($this->_userClass,$this);
 126                         $user->setIsGuest(true);
 127                         return $user;
 128                 }
 129                 else
 130                         return $this->_userFactory->createUser($username);
 131         }
 132
 133         /**
 134          * @return string the ID of a TDataSourceConfig module. Defaults to empty string, meaning not set.
 135          */
 136         public function getConnectionID()
 137         {
 138                 return $this->_connID;
 139         }
 140
 141         /**
 142          * Sets the ID of a TDataSourceConfig module.
 143          * The datasource module will be used to establish the DB connection
 144          * that will be used by the user manager.
 145          * @param string module ID.
 146          */
 147         public function setConnectionID($value)
 148         {
 149                 $this->_connID=$value;
 150         }
 151
 152         /**
 153          * @return TDbConnection the database connection that may be used to retrieve user data.
 154          */
 155         public function getDbConnection()
 156         {
 157                 if($this->_conn===null)
 158                 {
 159                         $this->_conn=$this->createDbConnection($this->_connID);
 160                         $this->_conn->setActive(true);
 161                 }
 162                 return $this->_conn;
 163         }
 164
 165         /**
 166          * Creates the DB connection.
 167          * @param string the module ID for TDataSourceConfig
 168          * @return TDbConnection the created DB connection
 169          * @throws TConfigurationException if module ID is invalid or empty
 170          */
 171         protected function createDbConnection($connectionID)
 172         {
 173                 if($connectionID!=='')
 174                 {
 175                         $conn=$this->getApplication()->getModule($connectionID);
 176                         if($conn instanceof TDataSourceConfig)
 177                                 return $conn->getDbConnection();
 178                         else
 179                                 throw new TConfigurationException('dbusermanager_connectionid_invalid',$connectionID);
 180                 }
 181                 else
 182                         throw new TConfigurationException('dbusermanager_connectionid_required');
 183         }
 184
 185         /**
 186          * Returns a user instance according to auth data stored in a cookie.
 187          * @param THttpCookie the cookie storing user authentication information
 188          * @return TDbUser the user instance generated based on the cookie auth data, null if the cookie does not have valid auth data.
 189          * @since 3.1.1
 190          */
 191         public function getUserFromCookie($cookie)
 192         {
 193                 return $this->_userFactory->createUserFromCookie($cookie);
 194         }
 195
 196         /**
 197          * Saves user auth data into a cookie.
 198          * @param THttpCookie the cookie to receive the user auth data.
 199          * @since 3.1.1
 200          */
 201         public function saveUserToCookie($cookie)
 202         {
 203                 $user=$this->getApplication()->getUser();
 204                 if($user instanceof TDbUser)
 205                         $user->saveUserToCookie($cookie);
 206         }
 207 }
 208
 209
 210 /**
 211  * TDbUser class
 212  *
 213  * TDbUser is the base user class for using together with {@link TDbUserManager}.
 214  * Two methods are declared and must be implemented in the descendant classes:
 215  * - {@link validateUser()}: validates if username and password are correct entries.
 216  * - {@link createUser()}: creates a new user instance given the username
 217  *
 218  * @author Qiang Xue <qiang.xue@gmail.com>
 219  * @version $Id: TDbUserManager.php 3245 2013-01-07 20:23:32Z ctrlaltca $
 220  * @package System.Security
 221  * @since 3.1.0
 222  */
 223 abstract class TDbUser extends TUser
 224 {
 225         private $_connection;
 226
 227         /**
 228          * Returns a database connection that may be used to retrieve data from database.
 229          *
 230          * @return TDbConnection database connection that may be used to retrieve data from database
 231          */
 232         public function getDbConnection()
 233         {
 234                 if($this->_connection===null)
 235                 {
 236                         $userManager=$this->getManager();
 237                         if($userManager instanceof TDbUserManager)
 238                         {
 239                                 $connection=$userManager->getDbConnection();
 240                                 if($connection instanceof TDbConnection)
 241                                 {
 242                                         $connection->setActive(true);
 243                                         $this->_connection=$connection;
 244                                 }
 245                         }
 246                         if($this->_connection===null)
 247                                 throw new TConfigurationException('dbuser_dbconnection_invalid');
 248                 }
 249                 return $this->_connection;
 250         }
 251
 252         /**
 253          * Validates if username and password are correct entries.
 254          * Usually, this is accomplished by checking if the user database
 255          * contains this (username, password) pair.
 256          * You may use {@link getDbConnection DbConnection} to deal with database.
 257          * @param string username (case-sensitive)
 258          * @param string password
 259          * @return boolean whether the validation succeeds
 260          */
 261         abstract public function validateUser($username,$password);
 262
 263         /**
 264          * Creates a new user instance given the username.
 265          * This method usually needs to retrieve necessary user information
 266          * (e.g. role, name, rank, etc.) from the user database according to
 267          * the specified username. The newly created user instance should be
 268          * initialized with these information.
 269          *
 270          * If the username is invalid (not found in the user database), null
 271          * should be returned.
 272          *
 273          * You may use {@link getDbConnection DbConnection} to deal with database.
 274          *
 275          * @param string username (case-sensitive)
 276          * @return TDbUser the newly created and initialized user instance
 277          */
 278         abstract public function createUser($username);
 279
 280         /**
 281          * Creates a new user instance given the cookie containing auth data.
 282          *
 283          * This method is invoked when {@link TAuthManager::setAllowAutoLogin AllowAutoLogin} is set true.
 284          * The default implementation simply returns null, meaning no user instance can be created
 285          * from the given cookie.
 286          *
 287          * If you want to support automatic login (remember login), you should override this method.
 288          * Typically, you obtain the username and a unique token from the cookie's value.
 289          * You then verify the token is valid and use the username to create a user instance.
 290          *
 291          * @param THttpCookie the cookie storing user authentication information
 292          * @return TDbUser the user instance generated based on the cookie auth data, null if the cookie does not have valid auth data.
 293          * @see saveUserToCookie
 294          * @since 3.1.1
 295          */
 296         public function createUserFromCookie($cookie)
 297         {
 298                 return null;
 299         }
 300
 301         /**
 302          * Saves necessary auth data into a cookie.
 303          * This method is invoked when {@link TAuthManager::setAllowAutoLogin AllowAutoLogin} is set true.
 304          * The default implementation does nothing, meaning auth data is not stored in the cookie
 305          * (and thus automatic login is not supported.)
 306          *
 307          * If you want to support automatic login (remember login), you should override this method.
 308          * Typically, you generate a unique token according to the current login information
 309          * and save it together with the username in the cookie's value.
 310          * You should avoid revealing the password in the generated token.
 311          *
 312          * @param THttpCookie the cookie to store the user auth information
 313          * @see createUserFromCookie
 314          * @since 3.1.1
 315          */
 316         public function saveUserToCookie($cookie)
 317         {
 318         }
 319 }
 320