Added PHP Doc comments http://www.phpdoc.org/docs/latest/index.html

application/libraries/Aauth.php

@@ -1,22 +1,55 @@
 <?php if (!defined('BASEPATH')) exit('No direct script access allowed');
 
 /**
- * Description of Aauth
+ * Aauth is a User Authorization Library for CodeIgniter 2.x, which aims to make 
+ * easy some essential jobs such as login, permissions and access operations. 
+ * Despite ease of use, it has also very advanced features like private messages, 
+ * groupping, access management, public access etc..
  *
  * @author      Emre Akay
+ * @contributor Jacob Tomlinson
  *
+ * @copyright 2014 Emre Akay
  *
+ * @license LGPL
+ * @license http://opensource.org/licenses/LGPL-3.0 Lesser GNU Public License
+ *
+ * The latest version of Aauth can be obtained from:
+ * https://github.com/emreakay/CodeIgniter-Aauth
  */
-
-
-//last activity check email
 class Aauth {
 
+    /**
+     * The CodeIgniter object variable
+     * @var object
+     */
     public $CI;
+
+    /**
+     * Variable for loading the config array into
+     * @var array
+     */
     public $config_vars;
+
+    /**
+     * Array to store error messages
+     * @var array
+     */
     public $errors = array();
+
+    /**
+     * Array to store info messages
+     * @var array
+     */
     public $infos = array();
 
+    ########################
+    # Base Functions
+    ########################
+
+    /**
+     * Constructor
+     */
     public function __construct() {
 
         // delete all errors at first :)
@@ -41,8 +74,18 @@ class Aauth {
         $this->config_vars = & $this->CI->config->item('aauth');
     }
 
+    ########################
+    # User Functions
+    ########################
 
-    // open sessions
+    /**
+     * 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
+     * Controls if a logged or public user has permiision
-    // it also updates last activity every time function called
+     * 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
+     * @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
@@ -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
+     * Get user
-    // you can use sessions
+     * 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
+     * Is allowed
-    // admin authorized for anything
+     * 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
+     * List Private Messages
-    // if sender_id given, it returns only pms from given sender
+     * 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 = '<br />'){
 
         $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 = '<br />'){
 
         $msg = '';