Liveuser cosmetic patch

hello here is a small patch: - cosmetics - phpdoc ps: what license will be chosen for it ?

Index: Liveuser.php =================================================================== RCS file: /repository/pear/Perm_LiveUser/Liveuser.php,v retrieving revision 1.3 diff -u -r1.3 Liveuser.php --- Liveuser.php 8 Sep 2002 18:36:01 -0000 1.3 +++ Liveuser.php 19 Sep 2002 18:49:30 -0000 @@ -17,86 +17,85 @@ /** * Class LiveUser - * + * * Description: * This class provides a set of functions for implementing a user * authorisation system on live websites. - * + * * Requirements: - * - When using "DB" backend: + * - When using "DB" backend: * PEAR::DB database abstraction layer * - LiveUser admin GUI for easy user administration and setup of * authorisation areas and rights - * + * * Authors: * - Markus Wolff, 21st Media GbR: base and backend classes * - Florian Herlitschke, 21st Media GbR: admin GUI - * + * * Thanks to: * Björn Schotte (www.rent-a-phpwizard.de) for his ideas on creating * a single-signon-blackbox (which we haven't yet fully achieved, but * we're working on it ;-)) - * + * * @author Markus Wolff <wolff@21st.de> * @author Florian Herlitschke <f.herlitschke@21st.de> * @version $Id: Liveuser.php,v 1.3 2002/09/08 18:36:01 lsmith Exp $ - **/ - -class LiveUser + */ +class LiveUser { /** * The handle (username) of the current user * @var string - **/ + */ var $handle = ""; /** * The password of the current user as given to the * login() method. * @var string - **/ + */ var $passwd = ""; /** * Current user's database record id * @var integer - **/ + */ var $user_id = 0; /** * One-Dimensional array containing current user's AuthAreas * and his rights in each of these areas. This already includes * grouprights and possible overrides by individual right - * settings. - * + * settings. + * * Format: "AreaName" => "RightName" - * + * * @var mixed - **/ + */ var $rights = FALSE; /** * Two-dimensional array containing only the individual - * rights for the actual user. - * + * rights for the actual user. + * * Format: "AreaName" => "RightName" => "Value" - * + * * @var array - **/ + */ var $userRights = array(); /** * Two-dimensional array containing all groups that * the user belongs to and the grouprights defined for * each area. - * + * * Format: "GroupName" => "AreaName" => "RightName" - * + * * @var array * @see $userRights * @see $rights - **/ - var $groupRights = array(); + */ + var $groupRights = array(); /** * Is the current user allowed to login at all? If false, @@ -107,7 +106,7 @@ * Default: FALSE * @var boolean * @see $logged_in - **/ + */ var $is_active = FALSE; /** @@ -115,19 +114,19 @@ * Default: FALSE * @var boolean * @see $is_active - **/ + */ var $logged_in = FALSE; /** * Timestamp of last login (previous to currentLogin) * @var integer - **/ + */ var $lastLogin = 0; /** * Timestamp of current login (last to be written) * @var integer - **/ + */ var $currentLogin = 0; /** @@ -135,27 +134,27 @@ * to be counted as a new login. Comes in handy in * some situations. Default: 12 * @var integer - **/ + */ var $loginTimeout = 12; /** * Allow multiple users in the database to have the same * login handle. Default: FALSE. * @var boolean - **/ + */ var $allowDuplicateHandles = FALSE; /** * Defines the algorhythm used for encrypting/decrypting * passwords. Default: "MD5". * @var string - **/ + */ var $passwordEncryptionMode = "PLAIN"; /** * Defines the user type. * @var integer - **/ + */ var $user_type = LIVEUSER_ANONYMOUS_TYPE_ID; /** @@ -163,41 +162,41 @@ * If the user is an area admin this variable will be filled * with an array of all areas in which the user is area admin * @var mixed - **/ + */ var $area_admin = FALSE; /** * Defines if the user rights should be retrieved ondemand. * @var boolean - **/ + */ var $ondemand = FALSE; /** * Defines the (sub)groups in which the user is a memember * @var mixed - **/ + */ var $group_ids = FALSE; /** * Defines the members of all (sub)groups in which the user is a memember * @var mixed - **/ + */ var $group_user_ids = FALSE; - + /** * Defines the array index number of the LoginManager´s "backends" property. * Only used by the LoginManager for unfreeze()ing the session object * with the right connection data. * @var integer - **/ - var $backendArrayIndex = 0; + */ + var $backendArrayIndex = 0; /** * LiveUser::liveUser() - * + * * Class constructor. Feel free to override in backend subclasses. - **/ + */ function liveUser() { // I do nothing, override me plenty ;-) @@ -213,20 +212,22 @@ // I do nothing, override me plenty ;-) } + // {{{ decryptPW() + /** * LiveUser::decryptPW() - * + * * Decrypts a password so that it can be compared with the user * input. Uses the algorhythm defined in the passwordEncryptionMode * property. - * + * * @param string $encryptedPW * @return string The decrypted password - **/ + */ function decryptPW ($encryptedPW) { $decryptedPW = "Encryption type not supported."; - + switch ($this->passwordEncryptionMode) { case "PLAIN": $decryptedPW = $encryptedPW; @@ -236,24 +237,27 @@ $decryptedPW = $encryptedPW; break; } - + return $decryptedPW; } + // }}} + // {{{ encryptPW() + /** * LiveUser::encryptPW() - * + * * Encrypts a password for storage in a backend container. * Uses the algorhythm defined in the passwordEncryptionMode * property. - * + * * @param string $plainPW * @return string The encrypted password - **/ + */ function encryptPW($plainPW) { $encryptedPW = "Encryption type not supported."; - + switch ($this->passwordEncryptionMode) { case "PLAIN": $encryptedPW = $plainPW; @@ -262,18 +266,21 @@ $encryptedPW = md5($plainPW); break; } - + return $encryptedPW; } + // }}} + // {{{ isNewLogin() + /** * LiveUser::isNewLogin() - * + * * Checks if there's enough time between lastLogin * and currentLogin to count as a new login. - * + * * @return boolean - **/ + */ function isNewLogin () { $meantime = $this->loginTimeout * 3600; @@ -284,9 +291,12 @@ } } + // }}} + // {{{ login() + /** * LiveUser::login() - * + * * Tries to make a login with the given handle and password. * If $checkpw is set to FALSE, the password won't be * validated and the user will be logged in anyway. Set this @@ -294,19 +304,19 @@ * authenticated by a simple cookie... however, this is * NOT RECOMMENDED !!! * In any case, a user can't login if he's not active. - * + * * @param $handle * @param $passwd * @param boolean $checkpw * @param boolean $updateLastLogin - **/ + */ function login($handle, $passwd, $checkpw = TRUE, $updateLastLogin = TRUE) { // Init value: Has user data successfully been read? $success = FALSE; // Init value: Is user logged in? $this->logged_in = FALSE; - + // Read user data from database if ($this->allowDuplicateHandles == TRUE || $checkpw == TRUE) { // If duplicate handles are allowed or the password _has_ @@ -318,11 +328,11 @@ // on the handle $success = $this->readUserData($handle); } - + // If login is successful (user data has been read) if ($success == TRUE) { $pwCheck = FALSE; // Init value - + // ...check again if we have to check the password... if ($checkpw == TRUE) { // If yes, does the password from the database match the given one? @@ -335,7 +345,7 @@ // regardless of the user's input $pwCheck = TRUE; } - + // ...we still need to check if this user is declared active and // if the pwCheck Flag is set to TRUE... if ($this->is_active != FALSE && $pwCheck == TRUE) { @@ -343,7 +353,7 @@ $this->logged_in = TRUE; } } - + if ($updateLastLogin == TRUE && $this->logged_in == TRUE) { // In case Login was successful, check if this can be counted // as a _new_ login by definition... @@ -355,21 +365,24 @@ } } + // }}} + // {{{ readRights() + /** * LiveUser::readRights() - * + * * Reads all rights of current user into a * two-dimensional associative array, having the * area names as the key of the 1st dimension. * Group rights and invididual rights are being merged * in the process. - **/ + */ function readRights() { $this->readUserRights(); $this->readGroups(); $this->readGroupRights(); - + // Flatten group rights if (is_array($this->groupRights)) { foreach ($this->groupRights as $currentGroup => $groupAreas) { @@ -382,7 +395,7 @@ } else { $this->groupRights = FALSE; } - + // Check if user has individual rights... if (is_array($this->userRights)) { // Overwrite values from temporary array with values from userrights @@ -402,7 +415,7 @@ } else { $this->userRights = FALSE; } - + // Strip values from array if level is not greater than zero if (isset($tmpRights) && is_array($tmpRights)) { foreach ($tmpRights as $currentArea => $areaRights) { @@ -413,7 +426,7 @@ } } } - + if (isset($cRights) && is_array($cRights)) { $this->rights = $cRights; } else { @@ -421,30 +434,33 @@ } } + // }}} + // {{{ checkArea() + /** * LiveUser::checkArea() - * + * * Checks if the current user has a rights in a * given area. If no third parameter is given, this also * checks if the user is logged in and will only return * TRUE if he has the right in question AND is currently * logged in. - * + * * @param string $area_name The name of the AuthArea to use * @param boolean $checkLogin Flag: Shall the login status also be checked? * @return boolean - **/ + */ function checkArea($area_name, $checkLogin = TRUE) { $hasright = FALSE; - + if($this->rights) { if ($this->user_type > LIVEUSER_AREAADMIN_TYPE_ID || ($this->user_type == LIVEUSER_AREAADMIN_TYPE_ID && $this->area_admin && in_array($area_name, $this->area_admin))) { $hasright = TRUE; - // Check if user has rights in this area at all. + // Check if user has rights in this area at all. } else if(is_array($this->rights[$area_name])) { // Now let's see if we shall check the login status, too if ($checkLogin == TRUE) { @@ -466,9 +482,12 @@ return $hasright; } + // }}} + // {{{ checkRight() + /** * LiveUser::checkRight() - * + * * Checks if the current user has a certain right in a * given area. If no third parameter is given, this also * checks if the user is logged in and will only return @@ -476,23 +495,23 @@ * logged in. Set the third parameter to FALSE if you * just want to check wheter the user has a certain * right or not while ignoring the login status. - * + * * @param string $area_name The name of the AuthArea to use * @param string $right_name The name of the right within the AuthArea to check for * @param boolean $checkLogin Flag: Shall the login status also be checked? * @return integer level of the right - **/ + */ function checkRight($area_name, $right_name, $checkLogin = TRUE) { $hasright = FALSE; - + if($this->rights) { if ($this->user_type > LIVEUSER_AREAADMIN_TYPE_ID || ($this->user_type == LIVEUSER_AREAADMIN_TYPE_ID && $this->area_admin && in_array($area_name, $this->area_admin))) { $hasright = LIVEUSER_MAX_LEVEL; - // Check if user has rights in this area at all. + // Check if user has rights in this area at all. } else if(is_array($this->rights[$area_name])) { // If he does, look for the right in question if (in_array($right_name, array_keys($this->rights[$area_name]))) { @@ -517,9 +536,12 @@ return $hasright; } + // }}} + // {{{ checkLevel() + /** - * LiveUser::checkRightLevel() - * + * LiveUser::checkLevel() + * * Checks if the current user has a certain right in a * given area at the necessary level. * If no third parameter is given, this also @@ -528,9 +550,9 @@ * logged in. Set the third parameter to FALSE if you * just want to check wheter the user has a certain * right or not while ignoring the login status. - * + * * Level 1: requires that owner_user_id matches $this->user_id - * Level 2: requires that the $owner_group_id matches the id one of + * Level 2: requires that the $owner_group_id matches the id one of * the (sub)groups that $this->user_id is a memember of * or requires that the $owner_user_id matches a user_id of a memeber of one of $this->user_id's (sub)groups @@ -548,11 +570,11 @@ * which the right is requested * @return boolean TRUE if the level is sufficient to grant access * else FALSE - **/ + */ function checkLevel($level, $owner_user_id, $owner_group_id) { $hasright = FALSE; - + // highest level (that is level 3) if ($level == LIVEUSER_MAX_LEVEL) { $hasright = TRUE; @@ -576,9 +598,12 @@ return $hasright; } + // }}} + // {{{ checkRightLevel() + /** * LiveUser::checkRightLevel() - * + * * Checks if the current user has a certain right in a * given area with the sufficient level to gain access * to a specific ressource in that area. @@ -588,7 +613,7 @@ * logged in. Set the third parameter to FALSE if you * just want to check wheter the user has a certain * right or not while ignoring the login status. - * + * * @param string $area_name The name of the AuthArea to use * @param string $right_name The name of the right within the AuthArea to check for * @param mixed $owner_user_id id of the owner of the ressource for @@ -598,7 +623,7 @@ * @param boolean $checkLogin Flag: Shall the login status also be checked? * @return boolean TRUE if the level is sufficient to grant access * else FALSE - **/ + */ function checkRightLevel($area_name, $right_name, $owner_user_id, $owner_group_id, $checkLogin = TRUE) { $level = $this->checkRight($area_name, $right_name, $checkLogin); @@ -606,54 +631,66 @@ return $hasright; } + // }}} + // {{{ readUserRights() + /** * LiveUser::readUserRights() - * + * * Reads all individual rights of current user into * a two-dimensional array of this format: * AreaName => RightName -> Value - * + * * Again, this does nothing in the base class. The * described functionality must be implemented in a * subclass overriding this method. - **/ + */ function readUserRights() { // Override me plenty ;-) } + // }}} + // {{{ readGroupRights() + /** * LiveUser::readGroupRights() - * + * * Reads all individual rights of current user into * a two-dimensional array of this format: * "GroupName" => "AreaName" -> "RightName" - * + * * Again, this does nothing in the base class. The * described functionality must be implemented in a * subclass overriding this method. - **/ + */ function readGroupRights() { // Override me plenty ;-) } + // }}} + // {{{ updateUserData() + /** * LiveUser::updateUserData() - * + * * Writes current values for user back to the database. * This method does nothing in the base class and is supposed to * be overridden in subclasses according to the supported backend. - * - **/ + * + */ function updateUserData () - { + { // Override me plenty ;-) } + // }}} + // {{{ readUserData() + /** * LiveUser::readUserData() - * + * * Reads user_id, password, is_active flag, current * and last login timestamp from the database * If only $handle is given, it will read the data @@ -665,23 +702,26 @@ * multiple users having the same handle but different * passwords - yep, some people want this). * If no match is found, FALSE is being returned. - * + * * Again, this does nothing in the base class. The * described functionality must be implemented in a * subclass overriding this method. - * + * * @param $handle * @param boolean $passwd - * @return - **/ + * @return + */ function readUserData($handle, $passwd=FALSE) { // Override me plenty ;-) } + // }}} + // {{{ userExists() + /** * LiveUser::userExists() - * + * * Helper function that checks if there is a user in * the database who's matching the given parameters. * If $checkHandle is given and $checkPW is set to @@ -704,18 +744,26 @@ * should be pretty safe, though - having more than * one user with the same handle/password combination * in the database would be pretty stupid anyway. - * + * * Again, this does nothing in the base class. The * described functionality must be implemented in a * subclass overriding this method. - * + * * @param boolean $checkHandle * @param boolean $checkPW * @return mixed - **/ + */ function userExists($checkHandle=FALSE,$checkPW=FALSE) { // Override me plenty ;-) } } + +/* + * Local Variables: + * mode: php + * tab-width: 4 + * c-basic-offset: 4 + * End: + */ ?>