diff --git a/application/libraries/Aauth.php b/application/libraries/Aauth.php index 2d97d5a..f26d9c7 100644 --- a/application/libraries/Aauth.php +++ b/application/libraries/Aauth.php @@ -1,22 +1,55 @@ config_vars = & $this->CI->config->item('aauth'); } - - // open sessions + ######################## + # User Functions + ######################## + + /** + * Login user + * Check provided details against the database. Add items to error array on fail, create session if success + * @param string $email + * @param string $pass + * @param bool $remember + * @return bool Indicates successful login. + */ public function login($email, $pass, $remember = FALSE) { // remove cookies first @@ -149,8 +192,11 @@ class Aauth { } } - // checks if user logged in - // also checks remember + /** + * Check user login + * Checks if user logged in, also checks remember. + * @return bool + */ public function is_loggedin() { if($this->CI->session->userdata('loggedin')) @@ -190,10 +236,11 @@ class Aauth { return false; } - // most important function. it controls if a logged or public user has permiision - // if no permission, it stops script - // it also updates last activity every time function called - // if perm_par is not given just control user logged in or not + /** + * Controls if a logged or public user has permiision + * If no permission, it stops script, it also updates last activity every time function called + * @param bool $perm_par If not given just control user logged in or not + */ public function control($perm_par = false){ if(!$perm_par and !$this->is_loggedin()){ @@ -208,16 +255,26 @@ class Aauth { echo $this->config_vars['no_access']; die(); } - } - // do logout + /** + * Logout user + * Destroys the CodeIgniter session to log out user. + * @return bool If session destroy successful + */ public function logout() { - return $this->CI->session->sess_destroy(); } - // return users as an object array + /** + * List users + * Return users as an object array + * @param bool|int $group_par Specify group id to list group or false for all users + * @param string $limit Limit of users to be returned + * @param bool $offset Offset for limited number of users + * @param bool $include_banneds Include banned users + * @return array Array of users + */ public function list_users($group_par = FALSE, $limit = FALSE, $offset = FALSE, $include_banneds = FALSE) { // if group_par is given @@ -229,7 +286,7 @@ class Aauth { ->join($this->config_vars['user_to_group'], $this->config_vars['users'] . ".id = " . $this->config_vars['user_to_group'] . ".user_id") ->where($this->config_vars['user_to_group'] . ".group_id", $group_par); - // if group_par is not given, lists all users + // if group_par is not given, lists all users } else { $this->CI->db->select('*') @@ -241,7 +298,6 @@ class Aauth { $this->CI->db->where('banned != ', 1); } - // limit if ($limit) { @@ -251,13 +307,16 @@ class Aauth { $this->CI->db->limit($limit, $offset); } - $query = $this->CI->db->get(); return $query->result(); } - //do login with id + /** + * Fast login + * Login with just a user id + * @param int $user_id User id to log in + */ public function login_fast($user_id){ $query = $this->CI->db->where('id', $user_id); $query = $this->CI->db->where('banned', 0); @@ -280,7 +339,14 @@ class Aauth { } } - // creates user and returns its id + /** + * Create user + * Creates a new user + * @param string $email User's email address + * @param string $pass User's password + * @param string $name User's name + * @return int|bool False if create fails or returns user id if successful + */ public function create_user($email, $pass, $name='') { $valid = true; @@ -334,7 +400,15 @@ class Aauth { } } - // takes the user id and updates the values given + /** + * Update user + * Updates existing user details + * @param int $user_id User id to update + * @param string|bool $email User's email address, or false if not to be updated + * @param string|bool $pass User's password, or false if not to be updated + * @param string|bool $name User's name, or false if not to be updated + * @return bool Update fails/succeeds + */ public function update_user($user_id, $email = FALSE, $pass = FALSE, $name = FALSE) { $data = array(); @@ -355,7 +429,11 @@ class Aauth { return $this->CI->db->update($this->config_vars['users'], $data); } - // send vertifition mail + /** + * Send verification email + * Sends a verification email based on user id + * @param int $user_id User id to send verification email to + */ public function send_verification($user_id){ $query = $this->CI->db->where( 'id', $user_id ); @@ -381,7 +459,13 @@ class Aauth { //echo $this->CI->email->print_debugger(); } - // activare user + /** + * Verify user + * Activates user account based on verification code + * @param int $user_id User id to activate + * @param string $ver_code Code to validate against + * @return bool Activation fails/succeeds + */ public function verify_user($user_id, $ver_code){ $query = $this->CI->db->where('id', $user_id); @@ -402,7 +486,12 @@ class Aauth { return false; } - // resets attempts + /** + * Reset last login attempts + * Sets a users 'last login attempts' to null + * @param int $user_id User id to reset + * @return bool Reset fails/succeeds + */ public function reset_login_attempts($user_id) { $data['last_login_attempts'] = null; @@ -410,7 +499,12 @@ class Aauth { return $this->CI->db->update($this->config_vars['users'], $data); } - // bans user + /** + * Ban user + * Bans a user account + * @param int $user_id User id to ban + * @return bool Ban fails/succeeds + */ public function ban_user($user_id) { $data = array( @@ -422,7 +516,12 @@ class Aauth { return $this->CI->db->update($this->config_vars['users'], $data); } - // cancels the ban + /** + * Unban user + * Activates user account + * @param int $user_id User id to activate + * @return bool Activation fails/succeeds + */ public function unlock_user($user_id) { $data = array( @@ -434,7 +533,12 @@ class Aauth { return $this->CI->db->update($this->config_vars['users'], $data); } - // check if user banned, return false if banned or not found user + /** + * Check user banned + * Checks if a user is banned + * @param int $user_id User id to check + * @return bool Flase if banned, True if not + */ public function is_banned($user_id) { $query = $this->CI->db->where('id', $user_id); @@ -448,13 +552,23 @@ class Aauth { return FALSE; } + /** + * Delete user + * Delete a user from database. WARNING Can't be undone + * @param int $user_id User id to delete + */ public function delete_user($user_id) { $this->CI->db->where('id', $user_id); $this->CI->db->delete($this->config_vars['users']); } - // if email is available, returns true + /** + * Check email + * Checks if an email address is available + * @param string $email Email to check + * @return bool True if available, False if not + */ public function check_email($email) { $this->CI->db->where("email", $email); @@ -468,6 +582,11 @@ class Aauth { return TRUE; } + /** + * Remind password + * Emails user with link to reset password + * @param string $email Email for account to remind + */ public function remind_password($email){ $query = $this->CI->db->where( 'email', $email ); @@ -490,10 +609,15 @@ class Aauth { $this->config_vars['remind'] . $row->id . '/' . $ver_code ); $this->CI->email->send(); } - - //echo $this->CI->email->print_debugger(); } + /** + * Reset password + * Generate new password and email it to the user + * @param int $user_id User id to reset password for + * @param string $ver_code Verification code for account + * @return bool Password reset fails/succeeds + */ public function reset_password($user_id, $ver_code){ $query = $this->CI->db->where('id', $user_id); @@ -524,11 +648,15 @@ class Aauth { return true; } - //echo $this->CI->email->print_debugger(); return false; } - // updates user's last activity date + /** + * Update activity + * Update user's last activity date + * @param int|bool $user_id User id to update or false for current user + * @return bool Update fails/succeeds + */ public function update_activity($user_id = FALSE) { if ($user_id == FALSE) @@ -542,7 +670,12 @@ class Aauth { return $this->CI->db->update($this->config_vars['users'], $data); } - // updates last login date and time + /** + * Update last login + * Update user's last login date + * @param int|bool $user_id User id to update or false for current user + * @return bool Update fails/succeeds + */ public function update_last_login($user_id = FALSE) { if ($user_id == FALSE) @@ -554,7 +687,14 @@ class Aauth { return $this->CI->db->update($this->config_vars['users'], $data); } - // updates remember time + /** + * Update remember + * Update amount of time a user is remembered for + * @param int $user_id User id to update + * @param int $expression + * @param int $expire + * @return bool Update fails/succeeds + */ public function update_remember($user_id, $expression=null, $expire=null) { $data['remember_time'] = $expire; @@ -564,9 +704,12 @@ class Aauth { return $this->CI->db->update($this->config_vars['users'], $data); } - - // get user information as an array - // you can use sessions + /** + * Get user + * Get user information + * @param int|bool $user_id User id to get or false for current user + * @return object User information + */ public function get_user($user_id = FALSE) { if ($user_id == FALSE) @@ -582,6 +725,12 @@ class Aauth { return $query->row(); } + /** + * Get user id + * Get user id from email address + * @param string $email Email address for user + * @return int User id + */ public function get_user_id($email=false) { if(!$email){ @@ -599,6 +748,12 @@ class Aauth { return $query->row()->id; } + /** + * Get user groups + * Get groups a user is in + * @param int|bool $user_id User id to get or false for current user + * @return array Groups + */ public function get_user_groups($user_id = false){ if ($user_id==false) { $user_id = $this->CI->session->userdata('id'); } @@ -611,7 +766,16 @@ class Aauth { return $query = $this->CI->db->get()->result(); } - // creates a group and returns new group id + ######################## + # Group Functions + ######################## + + /** + * Create group + * Creates a new group + * @param string $group_name New group name + * @return int|bool Group id or false on fail + */ public function create_group($group_name) { $query = $this->CI->db->get_where($this->config_vars['groups'], array('name' => $group_name)); @@ -629,6 +793,13 @@ class Aauth { return FALSE; } + /** + * Update group + * Change a groups name + * @param int $group_id Group id to update + * @param string $group_name New group name + * @return bool Update success/failure + */ public function update_group($group_id, $group_name) { $data['name'] = $group_name; @@ -637,12 +808,25 @@ class Aauth { return $this->CI->db->update($this->config_vars['groups'], $data); } + /** + * Delete group + * Delete a group from database. WARNING Can't be undone + * @param int $group_id User id to delete + * @return bool Delete success/failure + */ public function delete_group($group_id) { $this->CI->db->where('id', $group_id); return $this->CI->db->delete($this->config_vars['groups']); } + /** + * Add member + * Add a user to a group + * @param int $user_id User id to add to group + * @param int|string $group_par Group id or name to add user to + * @return bool Add success/failure + */ public function add_member($user_id, $group_par) { $group_par = $this->get_group_id($group_par); @@ -663,7 +847,13 @@ class Aauth { return true; } - // fire the member from the given group + /** + * Remove member + * Remove a user from a group + * @param int $user_id User id to remove from group + * @param int|string $group_par Group id or name to remove user from + * @return bool Remove success/failure + */ public function fire_member($user_id, $group_par) { $group_par = $this->get_group_id($group_par); @@ -672,7 +862,12 @@ class Aauth { return $this->CI->db->delete($this->config_vars['user_to_group']); } - // group_name or group_id + /** + * Is member + * Check if current user is a member of a group + * @param int|string $group_par Group id or name to check + * @return bool + */ public function is_member($group_par) { $user_id = $this->CI->session->userdata('id'); @@ -708,17 +903,33 @@ class Aauth { } } + /** + * Is admin + * Check if current user is a member of the admin group + * @param int|string $group_par Group id or name to check + * @return bool + */ public function is_admin() { return $this->is_member($this->config_vars['admin_group']); } - // returns groups as an object array + /** + * List groups + * List all groups + * @return object Array of groups + */ public function list_groups() { $query = $this->CI->db->get($this->config_vars['groups']); return $query->result(); } + /** + * Get group name + * Get group name from group id + * @param int $group_id Group id to get + * @return string Group name + */ public function get_group_name($group_id) { $query = $this->CI->db->where('id', $group_id); @@ -731,7 +942,12 @@ class Aauth { return $row->name; } - // takes group paramater (id or name) and returns group id. + /** + * Get group id + * Get group id from group name or id + * @param int|string $group_par Group id or name to get + * @return int Group id + */ public function get_group_id($group_par) { if( is_numeric($group_par) ) { return $group_par; } @@ -746,7 +962,17 @@ class Aauth { return $row->id; } - // creates new permission rule. and returns its id + ######################## + # Permission Functions + ######################## + + /** + * Create permission + * Creates a new permission type + * @param string $perm_name New permission name + * @param string $definition Permission description + * @return int|bool Permission id or false on fail + */ public function create_perm($perm_name, $definition='') { $query = $this->CI->db->get_where($this->config_vars['perms'], array('name' => $perm_name)); @@ -764,7 +990,14 @@ class Aauth { return FALSE; } - // updates permissions name and definiton + /** + * Update permission + * Updates permission name and description + * @param int $perm_id Permission id + * @param string $perm_name New permission name + * @param string $definition Permission description + * @return bool Update success/failure + */ public function update_perm($perm_id, $perm_name, $definition=false) { $data['name'] = $perm_name; @@ -776,16 +1009,25 @@ class Aauth { return $this->CI->db->update($this->config_vars['perms'], $data); } - // remove a permision rule + /** + * Delete permission + * Delete a permission from database. WARNING Can't be undone + * @param int $perm_id Permission id to delete + * @return bool Delete success/failure + */ public function delete_perm($perm_id) { $this->CI->db->where('id', $perm_id); return $this->CI->db->delete($this->config_vars['perms']); } - // checks if a group has permitions for given permition - // if group paramater is empty function checks all groups of current user - // admin authorized for anything + /** + * Is allowed + * Check if group is allowed to do specified action, admin always allowed + * @param int|string|bool $group_par Group id or name to check, or if false checks all user groups + * @param int $perm_par Permission id or name to check + * @return bool + */ public function is_allowed($group_par=false, $perm_par){ $perm_id = $this->get_perm_id($perm_par); @@ -826,10 +1068,15 @@ class Aauth { return false; } - } - // adds a group to permission table + /** + * Allow + * Add group to permission + * @param int|string|bool $group_par Group id or name to allow + * @param int $perm_par Permission id or name to allow + * @return bool Allow success/failure + */ public function allow($group_par, $perm_par) { $perm_id = $this->get_perm_id($perm_par); @@ -851,8 +1098,13 @@ class Aauth { return true; } - // deny or disallow a group for spesific permition - // a group which not allowed is already denied. + /** + * Deny + * Remove group from permission + * @param int|string|bool $group_par Group id or name to deny + * @param int $perm_par Permission id or name to deny + * @return bool Deny success/failure + */ public function deny($group_par, $perm_par) { $perm_id = $this->get_perm_id($perm_par); @@ -864,12 +1116,23 @@ class Aauth { return $this->CI->db->delete($this->config_vars['perm_to_group']); } + /** + * List Permissions + * List all permissions + * @return object Array of permissions + */ public function list_perms() { $query = $this->CI->db->get($this->config_vars['perms']); return $query->result(); } + /** + * Get permission id + * Get permission id from permisison name or id + * @param int|string $perm_par Permission id or name to get + * @return int Permission id + */ public function get_perm_id($perm_par) { if( is_numeric($perm_par) ) { return $perm_par; } @@ -884,7 +1147,19 @@ class Aauth { return $row->id; } - // sends private messages + ######################## + # Private Message Functions + ######################## + + /** + * Send Private Message + * Send a private message to another user + * @param int $sender_id User id of private message sender + * @param int $receiver_id User id of private message receiver + * @param string $title Message title/subject + * @param string $message Message body/content + * @return bool Send successful/failed + */ public function send_pm( $sender_id, $receiver_id, $title, $message ){ if ( !is_numeric($receiver_id) or $sender_id == $receiver_id ){ @@ -914,9 +1189,15 @@ class Aauth { return $query = $this->CI->db->insert( $this->config_vars['pms'], $data ); } - // returns an object consist of list of pms - // if receiver id not given it retruns current user's pms - // if sender_id given, it returns only pms from given sender + /** + * List Private Messages + * If receiver id not given retruns current user's pms, if sender_id given, it returns only pms from given sender + * @param int $limit Number of private messages to be returned + * @param int $offset Offset for private messages to be returned (for pagination) + * @param int $sender_id User id of private message sender + * @param int $receiver_id User id of private message receiver + * @return object Array of private messages + */ public function list_pms($limit=5, $offset=0, $receiver_id = false, $sender_id=false){ $query=''; @@ -932,10 +1213,15 @@ class Aauth { $query = $this->CI->db->order_by('id','DESC'); $query = $this->CI->db->get( $this->config_vars['pms'], $limit, $offset); return $query->result(); - } - // gets pm and sets as read unless $set_as_read is false + /** + * Get Private Message + * Get private message by id + * @param int $pm_id Private message id to be returned + * @param bool $set_as_read Whether or not to mark message as read + * @return object Private message + */ public function get_pm($pm_id, $set_as_read = true){ if ($set_as_read) $this->set_as_read_pm($pm_id); @@ -950,12 +1236,22 @@ class Aauth { return $query->result(); } - // deletes pm + /** + * Delete Private Message + * Delete private message by id + * @param int $pm_id Private message id to be deleted + * @return bool Delete success/failure + */ public function delete_pm($pm_id){ return $this->CI->db->delete( $this->config_vars['pms'], array('id' => $pm_id) ); } - // counts unread pms and return integer. + /** + * Count unread Private Message + * Count number of unread private messages + * @param int|bool $receiver_id User id for message receiver, if false returns for current user + * @return int Number of unread messages + */ public function count_unread_pms($receiver_id=false){ if(!$receiver_id){ @@ -969,7 +1265,11 @@ class Aauth { return $query->num_rows(); } - // sets a pm as unread + /** + * Set Private Message as read + * Set private message as read + * @param int $pm_id Private message id to mark as read + */ public function set_as_read_pm($pm_id){ $data = array( @@ -979,16 +1279,26 @@ class Aauth { $this->CI->db->update( $this->config_vars['pms'], $data, "id = $pm_id"); } + ######################## + # Error/Info Functions + ######################## - - ///// Updated Error Functions ///// - + /** + * Error + * Add message to error array and set flash data + * @param string $message Message to add to array + */ public function error($message){ $this->errors[] = $message; $this->CI->session->set_flashdata('errors', $this->errors); } + /** + * Get Errors Array + * Return array of errors + * @return array|bool Array of messages or false if no errors + */ public function get_errors_array(){ if (!count($this->errors)==0){ @@ -998,6 +1308,12 @@ class Aauth { } } + /** + * Get Errors + * Return string of errors separated by delimiter + * @param string $divider Separator for errors + * @return string String of errors separated by delimiter + */ public function get_errors($divider = '
'){ $msg = ''; @@ -1014,12 +1330,22 @@ class Aauth { return $msg; } + /** + * Info + * Add message to info array and set flash data + * @param string $message Message to add to array + */ public function info($message){ $this->infos[] = $message; $this->CI->session->set_flashdata('infos', $this->errors); } + /** + * Get Info Array + * Return array of info + * @return array|bool Array of messages or false if no errors + */ public function get_infos_array(){ if (!count($this->infos)==0){ @@ -1029,6 +1355,12 @@ class Aauth { } } + /** + * Get Info + * Return string of info separated by delimiter + * @param string $divider Separator for info + * @return string String of info separated by delimiter + */ public function get_infos($divider = '
'){ $msg = '';