From 135e57720c1de22c21fb007b8683ccf8641c204d Mon Sep 17 00:00:00 2001 From: Quitta Date: Wed, 11 Sep 2013 16:56:00 +0200 Subject: [PATCH] Even more docs! writing documentation sucks.. --- .../ryzom_ams/ams_lib/autoload/pagination.php | 51 ++++- .../ryzom_ams/ams_lib/autoload/querycache.php | 69 +++++-- .../ams_lib/autoload/support_group.php | 186 +++++++++++++++--- 3 files changed, 267 insertions(+), 39 deletions(-) diff --git a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/pagination.php b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/pagination.php index 3c4473170..182d9f5af 100644 --- a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/pagination.php +++ b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/pagination.php @@ -1,12 +1,28 @@ current= 1; @@ -52,22 +68,47 @@ class Pagination{ } + /** + * return the number of the 'last' object attribute + * @return the number of the last page + */ public function getLast(){ return $this->last; } + + /** + * return the number of the 'current' object attribute + * @return the number of the current page + */ public function getCurrent(){ return $this->current; } + + /** + * return the elements array of the object + * @return the elements of a specific page (these are instantiations of the class passed as parameter ($resultClass) to the constructor) + */ public function getElements(){ return $this->element_array; } + + /** + * return total amount of rows for the original query + * @return the total amount of rows for the original query + */ public function getAmountOfRows(){ return $this->amountOfRows; } + /** + * return the page links. + * (for browsing the pages, placed under a table for example) the $nrOfLinks parameter specifies the amount of links you want to return. + * it will show the links closest to the current page on both sides (in case one side can't show more, it will show more on the other side) + * @return an array of integerswhich refer to the clickable pagenumbers for browsing other pages. + */ public function getLinks($nrOfLinks){ $pageLinks = Array(); //if amount of showable links is greater than the amount of pages: show all! diff --git a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/querycache.php b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/querycache.php index 9ca6c627d..6be551225 100644 --- a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/querycache.php +++ b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/querycache.php @@ -1,21 +1,37 @@ sid, 'type' => type, 'query' => query, 'db' => db). + */ public function set($values) { $this->setSID($values['SID']); $this->setType($values['type']); @@ -24,7 +40,11 @@ class Querycache{ } - //return constructed element based on SID + /** + * loads the object's attributes. + * loads the object's attributes by giving a SID as parameter + * @param $id the id of the querycaches row + */ public function load_With_SID( $id) { $dbl = new DBLayer("lib"); $statement = $dbl->execute("SELECT * FROM ams_querycache WHERE SID=:id", array('id' => $id)); @@ -33,7 +53,9 @@ class Querycache{ } - //update private data to DB. + /** + * updates the entry. + */ public function update(){ $dbl = new DBLayer("lib"); $query = "UPDATE ams_querycache SET type= :t, query = :q, db = :d WHERE SID=:id"; @@ -43,39 +65,64 @@ class Querycache{ ////////////////////////////////////////////Getters//////////////////////////////////////////////////// + /** + * get SID attribute of the object. + */ public function getSID(){ return $this->SID; } - + /** + * get type attribute of the object. + */ public function getType(){ return $this->type; } - + /** + * get query attribute of the object. + */ public function getQuery(){ return $this->query; } + /** + * get db attribute of the object. + */ public function getDb(){ return $this->db; } ////////////////////////////////////////////Setters//////////////////////////////////////////////////// + /** + * set SID attribute of the object. + * @param $s integer id + */ public function setSID($s){ $this->SID = $s; } - + /** + * set type attribute of the object. + * @param $t type of the query, could be changePassword, changePermissions, changeEmail, createUser + */ public function setType($t){ $this->type = $t; } + /** + * set query attribute of the object. + * @param $q query string + */ public function setQuery($q){ $this->query= $q; } + /** + * set db attribute of the object. + * @param $d the name of the database in the config global var that we want to use. + */ public function setDb($d){ $this->db= $d; } diff --git a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/support_group.php b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/support_group.php index 6975cb183..919f82608 100644 --- a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/support_group.php +++ b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/support_group.php @@ -1,18 +1,27 @@ execute("SELECT * FROM support_group WHERE SGroupId = :id", array('id' => $id)); @@ -23,7 +32,11 @@ class Support_Group{ } - //return all groups + + /** + * return all support_group objects. + * @return an array containing all support_group objects. + */ public static function getGroups() { $dbl = new DBLayer("lib"); $statement = $dbl->executeWithoutParams("SELECT * FROM support_group ORDER BY Name ASC"); @@ -38,7 +51,14 @@ class Support_Group{ return $result; } - //wrapper for creating a support group + + /** + * Wrapper for creating a support group. + * It will check if the support group doesn't exist yet, if the tag or name already exists then NAME_TAKEN or TAG_TAKEN will be returned. + * If the name is bigger than 20 characters or smaller than 4 and the tag greater than 7 or smaller than 2 a SIZE_ERROR will be returned. + * Else it will return SUCCESS + * @return a string that specifies if it was a success or not (SUCCESS, SIZE_ERROR, NAME_TAKEN or TAG_TAKEN ) + */ public static function createSupportGroup( $name, $tag, $groupemail, $imap_mailserver, $imap_username, $imap_password) { if(strlen($name) < 21 && strlen($name) > 4 &&strlen($tag) < 8 && strlen($tag) > 1 ){ @@ -70,7 +90,12 @@ class Support_Group{ } } - //check if group exists + /** + * check if support group name/tag doesn't exist yet. + * @param $name the name of the group we want to check + * @param $tag the tag of the group we want to check + * @return if name is already taken return NAME_TAKEN, else if tag is already taken return TAG_TAKEN, else return success. + */ public static function supportGroup_EntryNotExists( $name, $tag) { $dbl = new DBLayer("lib"); //check if name is already used @@ -85,7 +110,11 @@ class Support_Group{ } - //check if group exists + /** + * check if support group entry coupled to a given id exist or not. + * @param $id the id of the group we want to check + * @return true or false. + */ public static function supportGroup_Exists( $id) { $dbl = new DBLayer("lib"); //check if supportgroup id exist @@ -97,14 +126,23 @@ class Support_Group{ } - //return constructed element based on SGroupId + /** + * construct an object based on the SGroupId. + * @param $id the id of the group we want to construct + * @return the constructed support group object + */ public static function constr_SGroupId( $id) { $instance = new self(); $instance->setSGroup($id); return $instance; } - //returns list of all users that are enlisted to a support group + + /** + * get list of all users that are enlisted to a support group. + * @param $id the id of the group we want to query + * @return an array of ticket_user objects that are in the support group. + */ public static function getAllUsersOfSupportGroup($group_id) { $dbl = new DBLayer("lib"); $statement = $dbl->execute("SELECT * FROM `in_support_group` INNER JOIN `ticket_user` ON ticket_user.TUserId = in_support_group.User WHERE in_support_group.Group=:id", array('id' => $group_id)); @@ -120,7 +158,13 @@ class Support_Group{ return $result; } - //wrapper for adding user to a support group + + /** + * wrapper for deleting a support group. + * We will first check if the group really exists, if not than "GROUP_NOT_EXISING" will be returned. + * @param $group_id the id of the group we want to delete + * @return an array of ticket_user objects that are in the support group. + */ public static function deleteSupportGroup($group_id) { //check if group id exists @@ -135,7 +179,15 @@ class Support_Group{ } - //wrapper for adding user to a support group + /** + * wrapper for deleting a user that's in a specified support group. + * We will first check if the group really exists, if not than "GROUP_NOT_EXISING" will be returned. + * Afterwards we will check if the user exists in the support group, if not "USER_NOT_IN_GROUP" will be returned. + * Else the users entry in the in_support_group table will be deleted and "SUCCESS" will be returned. + * @param $user_id the id of the user we want to remove out of the group. + * @param $group_id the id of the group the user should be in + * @return a string (SUCCESS, USER_NOT_IN_GROUP or GROUP_NOT_EXISTING) + */ public static function deleteUserOfSupportGroup( $user_id, $group_id) { //check if group id exists @@ -164,7 +216,16 @@ class Support_Group{ } - //wrapper for adding user to a support group + + /** + * wrapper for adding a user to a specified support group. + * We will first check if the group really exists, if not than "GROUP_NOT_EXISING" will be returned. + * Afterwards we will check if the user exists in the support group, if so "ALREADY_ADDED" will be returned. + * Else the user will be added to the in_support_group table and "SUCCESS" will be returned. + * @param $user_id the id of the user we want to add to the group. + * @param $group_id the id of the group the user wants to be in + * @return a string (SUCCESS, ALREADY_ADDED or GROUP_NOT_EXISTING) + */ public static function addUserToSupportGroup( $user_id, $group_id) { //check if group id exists if (self::supportGroup_Exists($group_id)){ @@ -191,7 +252,12 @@ class Support_Group{ } - //returns list of all category objects + + /** + * return all support_group objects. + * @return an array containing all support_group objects. + * @deprecated should be removed in the future, because getGroups does the same. + */ public static function getAllSupportGroups() { $dbl = new DBLayer("lib"); $statement = $dbl->executeWithoutParams("SELECT * FROM `support_group`"); @@ -206,10 +272,19 @@ class Support_Group{ } ////////////////////////////////////////////Methods//////////////////////////////////////////////////// + + /** + * A constructor. + * Empty constructor + */ public function __construct() { } - //set values + + /** + * sets the object's attributes. + * @param $values should be an array of the form array('SGroupId' => groupid, 'Name' => name, 'Tag' => tag, 'GroupEmail' => mail, 'IMAP_MailServer' => server, 'IMAP_Username' => username,'IMAP_Password' => pass). + */ public function set($values) { $this->setSGroupId($values['SGroupId']); $this->setName($values['Name']); @@ -220,6 +295,11 @@ class Support_Group{ $this->setIMAP_Password($values['IMAP_Password']); } + + /** + * creates a new 'support_group' entry. + * this method will use the object's attributes for creating a new 'support_group' entry in the database. + */ public function create() { $dbl = new DBLayer("lib"); $query = "INSERT INTO support_group (Name, Tag, GroupEmail, IMAP_MailServer, IMAP_Username, IMAP_Password) VALUES (:name, :tag, :groupemail, :imap_mailserver, :imap_username, :imap_password)"; @@ -227,7 +307,12 @@ class Support_Group{ $dbl->execute($query, $values); } - //Load with sGroupId + + /** + * loads the object's attributes. + * loads the object's attributes by giving a group id, it will put the matching groups attributes in the object. + * @param $id the id of the support group that should be loaded + */ public function load_With_SGroupId( $id) { $dbl = new DBLayer("lib"); $statement = $dbl->execute("SELECT * FROM `support_group` WHERE `SGroupId` = :id", array('id' => $id)); @@ -236,7 +321,9 @@ class Support_Group{ } - //update private data to DB. + /** + * update the objects attributes to the db. + */ public function update(){ $dbl = new DBLayer("lib"); $query = "UPDATE `support_group` SET `Name` = :name, `Tag` = :tag, `GroupEmail` = :groupemail, `IMAP_MailServer` = :mailserver, `IMAP_Username` = :username, `IMAP_Password` = :password WHERE `SGroupId` = :id"; @@ -244,7 +331,11 @@ class Support_Group{ $statement = $dbl->execute($query, $values); } - //delete entry + + /** + * deletes an existing 'support_group' entry. + * this method will use the object's attributes for deleting an existing 'support_group' entry in the database. + */ public function delete(){ $dbl = new DBLayer("lib"); $query = "DELETE FROM `support_group` WHERE `SGroupId` = :id"; @@ -254,59 +345,108 @@ class Support_Group{ ////////////////////////////////////////////Getters//////////////////////////////////////////////////// + /** + * get sGroupId attribute of the object. + */ public function getSGroupId(){ return $this->sGroupId; } + /** + * get name attribute of the object. + */ public function getName(){ return $this->name; } + /** + * get tag attribute of the object. + */ public function getTag(){ return $this->tag; } + /** + * get groupEmail attribute of the object. + */ public function getGroupEmail(){ return $this->groupEmail; } + /** + * get iMAP_MailServer attribute of the object. + */ public function getIMAP_MailServer(){ return $this->iMAP_MailServer; } + /** + * get iMAP_Username attribute of the object. + */ public function getIMAP_Username(){ return $this->iMAP_Username; } + /** + * get iMAP_Password attribute of the object. + */ public function getIMAP_Password(){ return $this->iMap_Password; } ////////////////////////////////////////////Setters//////////////////////////////////////////////////// + /** + * set sGroupId attribute of the object. + * @param $id integer id of the group + */ public function setSGroupId($id){ $this->sGroupId = $id; } + /** + * set name attribute of the object. + * @param $n name of the group + */ public function setName($n){ $this->name = $n; } + /** + * set tag attribute of the object. + * @param $t tag of the group + */ public function setTag($t){ $this->tag = $t; } + /** + * set groupEmail attribute of the object. + * @param $ge email of the group + */ public function setGroupEmail($ge){ $this->groupEmail = $ge; } + /** + * set iMAP_MailServer attribute of the object. + * @param $ms mailserver of the group + */ public function setIMAP_MailServer($ms){ $this->iMAP_MailServer = $ms; } + /** + * set iMAP_Username attribute of the object. + * @param $u imap username of the group + */ public function setIMAP_Username($u){ $this->iMAP_Username = $u; } + /** + * set iMAP_Password attribute of the object. + * @param $p imap password of the group + */ public function setIMAP_Password($p){ $this->iMap_Password = $p; }