From 9a6da858057e305471994eb6d4d426ce911e08a5 Mon Sep 17 00:00:00 2001 From: Quitta Date: Wed, 11 Sep 2013 23:51:23 +0200 Subject: [PATCH] added extra documentation. Man, writing documentation for the ticket class was quite a job :D --HG-- branch : quitta-gsoc-2013 --- .../ryzom_ams/ams_lib/autoload/querycache.php | 2 +- .../ryzom_ams/ams_lib/autoload/sync.php | 19 +- .../ryzom_ams/ams_lib/autoload/ticket.php | 276 ++++++++++++++---- .../ams_lib/autoload/ticket_category.php | 56 +++- .../ams_lib/autoload/ticket_content.php | 53 +++- 5 files changed, 326 insertions(+), 80 deletions(-) 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 6be551225..3da0887c9 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,7 +1,7 @@ execute(" SELECT * FROM `ticket` WHERE `TId` = :ticket_id", array('ticket_id' => $id) )->rowCount() ){ return true; }else{ @@ -26,26 +34,31 @@ class Ticket{ } } - /*FUNCTION: getStatusArray - * returns all possible statusses - * + + /** + * return an array of the possible statuses + * @return an array containing the string values that represent the different statuses. */ public static function getStatusArray() { return Array("Waiting on user reply","Waiting on support","Waiting on Dev reply","Closed"); } - - /*FUNCTION: getPriorityArray - * returns all possible statusses - * + + + /** + * return an array of the possible priorities + * @return an array containing the string values that represent the different priorities. */ public static function getPriorityArray() { return Array("Low","Normal","High","Super Dupa High"); } - /*FUNCTION: getEntireTicket - * return all ticket of the given author's id. - * + /** + * return an entire ticket. + * returns the ticket object and an array of all replies to that ticket. + * @param $id the id of the ticket. + * @param $view_as_admin true if the viewer of the ticket is a mod, else false (depending on this it will also show the hidden comments) + * @return an array containing the 'ticket_obj' and a 'reply_array', which is an array containing all replies to that ticket. */ public static function getEntireTicket($id,$view_as_admin) { $ticket = new Ticket(); @@ -55,10 +68,12 @@ class Ticket{ } - /*FUNCTION: getTicketTitlesOf - * return all ticket of the given author's id. - * - */ + /** + * return all tickets of a specific user. + * an array of all tickets created by a specific user are returned by this function. + * @param $author the id of the user of whom we want all tickets from. + * @return an array containing all ticket objects related to a user. + */ public static function getTicketsOf($author) { $dbl = new DBLayer("lib"); $statement = $dbl->execute("SELECT * FROM ticket INNER JOIN ticket_user ON ticket.Author = ticket_user.TUserId and ticket_user.ExternId=:id", array('id' => $author)); @@ -79,10 +94,21 @@ class Ticket{ } - /*FUNCTION: create_Ticket() - * creates a ticket + first initial reply and fills in the content of it! - * for_support_group defines to which support group the ticket has to be forwarded - */ + + /** + * function that creates a new ticket. + * A new ticket will be created, in case the extra_info != 0 and the http request came from ingame, then a ticket_info page will be created. + * A log entry will be written, depending on the $real_authors value. In case the for_support_group parameter is set, the ticket will be forwarded immediately. + * Also the mail handler will create a new email that will be sent to the author to notify him that his ticket is freshly created. + * @param $title the title we want to give to the ticket. + * @param $content the content we want to give to the starting post of the ticket. + * @param $category the id of the category that should be related to the ticket. + * @param $author the person who's id will be stored in the database as creator of the ticket. + * @param $real_author should be the same id, or a moderator/admin who creates a ticket for another user (this is used for logging purposes). + * @param $for_support_group in case you directly want to forward the ticket after creating it. (default value = 0 = don't forward) + * @param $extra_info used for creating an ticket_info page related to the ticket, this only happens when the ticket is made ingame. + * @return the created tickets id. + */ public static function create_Ticket( $title, $content, $category, $author, $real_author, $for_support_group = 0, $extra_info = 0) { //create the new ticket! @@ -117,10 +143,14 @@ class Ticket{ } - /*FUNCTION: updateTicketStatus() - * - * - */ + + /** + * updates the ticket's status. + * A log entry about this will be created only if the newStatus is different from the current status. + * @param $ticket_id the id of the ticket of which we want to change the status. + * @param $newStatus the new status value (integer) + * @param $author the user (id) that performed the update status action + */ public static function updateTicketStatus( $ticket_id, $newStatus, $author) { $ticket = new Ticket(); @@ -134,10 +164,15 @@ class Ticket{ } - /*FUNCTION: updateTicketStatusAndPriority() - * creates a ticket + first initial reply and fills in the content of it! - * - */ + /** + * updates the ticket's status & priority. + * A log entry about this will be created only if the newStatus is different from the current status and also when the newPriority is different from the current priority. + * @todo break this function up into a updateStatus (already exists) and updatePriority function and perhaps write a wrapper function for the combo. + * @param $ticket_id the id of the ticket of which we want to change the status & priority + * @param $newStatus the new status value (integer) + * @param $newPriority the new priority value (integer) + * @param $author the user (id) that performed the update + */ public static function updateTicketStatusAndPriority( $ticket_id, $newStatus, $newPriority, $author) { $ticket = new Ticket(); @@ -154,7 +189,12 @@ class Ticket{ } - //return the latest reply. + + /** + * return the latest reply of a ticket + * @param $ticket_id the id of the ticket. + * @return a ticket_reply object. + */ public static function getLatestReply( $ticket_id) { $dbl = new DBLayer("lib"); $statement = $dbl->execute("SELECT * FROM ticket_reply WHERE Ticket =:id ORDER BY TReplyId DESC LIMIT 1 ", array('id' => $ticket_id)); @@ -163,6 +203,16 @@ class Ticket{ return $reply; } + + /** + * create a new reply for a ticket. + * A reply will only be added if the content isn't empty and if the ticket isn't closed. + * The ticket creator will be notified by email that someone else replied on his ticket. + * @param $content the content of the reply + * @param $author the author of the reply + * @param $ticket_id the id of the ticket to which we want to add the reply. + * @param $hidden boolean that specifies if the reply should only be shown to mods/admins or all users. + */ public static function createReply($content, $author, $ticket_id, $hidden){ //if not empty if(! ( Trim ( $content ) === '' )){ @@ -187,7 +237,14 @@ class Ticket{ } } - //returns SUCCESS_ASSIGNED, TICKET_NOT_EXISTING or ALREADY_ASSIGNED + + /** + * assign a ticket to a user. + * Checks if the ticket exists, if so then it will try to assign the user to it, a log entry will be written about this. + * @param $user_id the id of user trying to be assigned to the ticket. + * @param $ticket_id the id of the ticket that we try to assign to the user. + * @return SUCCESS_ASSIGNED, TICKET_NOT_EXISTING or ALREADY_ASSIGNED + */ public static function assignTicket($user_id, $ticket_id){ if(self::ticketExists($ticket_id)){ $returnvalue = Assigned::assignTicket($user_id, $ticket_id); @@ -198,7 +255,14 @@ class Ticket{ } } - //returns SUCCESS_UNASSIGNED, TICKET_NOT_EXISTING or NOT_ASSIGNED + + /** + * unassign a ticket of a user. + * Checks if the ticket exists, if so then it will try to unassign the user of it, a log entry will be written about this. + * @param $user_id the id of user trying to be assigned to the ticket. + * @param $ticket_id the id of the ticket that we try to assign to the user. + * @return SUCCESS_UNASSIGNED, TICKET_NOT_EXISTING or NOT_ASSIGNED + */ public static function unAssignTicket($user_id, $ticket_id){ if(self::ticketExists($ticket_id)){ $returnvalue = Assigned::unAssignTicket($user_id, $ticket_id); @@ -209,6 +273,16 @@ class Ticket{ } } + + /** + * forward a ticket to a specific support group. + * Checks if the ticket exists, if so then it will try to forward the ticket to the support group specified, a log entry will be written about this. + * if no log entry should be written then the user_id should be 0, else te $user_id will be used in the log to specify who forwarded it. + * @param $user_id the id of user trying to forward the ticket. + * @param $ticket_id the id of the ticket that we try to forward to a support group. + * @param $group_id the id of the support group. + * @return SUCCESS_FORWARDED, TICKET_NOT_EXISTING or INVALID_SGROUP + */ public static function forwardTicket($user_id, $ticket_id, $group_id){ if(self::ticketExists($ticket_id)){ if(isset($group_id) && $group_id != ""){ @@ -234,12 +308,21 @@ class Ticket{ ////////////////////////////////////////////Methods//////////////////////////////////////////////////// + + /** + * A constructor. + * Empty constructor + */ public function __construct() { } - //Set ticket object + /** + * sets the object's attributes. + * @param $values should be an array of the form array('TId' => ticket_id, 'Title' => title, 'Status'=> status, 'Timestamp' => ts, 'Queue' => queue, + * 'Ticket_Category' => tc, 'Author' => author, 'Priority' => priority). + */ public function set($values){ if(isset($values['TId'])){ $this->tId = $values['TId']; @@ -253,7 +336,11 @@ class Ticket{ $this->priority = $values['Priority']; } - //create ticket by writing private data to DB. + + /** + * creates a new 'ticket' entry. + * this method will use the object's attributes for creating a new 'ticket' entry in the database. + */ public function create(){ $dbl = new DBLayer("lib"); $query = "INSERT INTO ticket (Timestamp, Title, Status, Queue, Ticket_Category, Author, Priority) VALUES (now(), :title, :status, :queue, :tcat, :author, :priority)"; @@ -261,7 +348,12 @@ class Ticket{ $this->tId = $dbl->executeReturnId($query, $values); ; } - //return constructed element based on TId + + /** + * loads the object's attributes. + * loads the object's attributes by giving a TId (ticket id). + * @param $id the id of the ticket that should be loaded + */ public function load_With_TId( $id) { $dbl = new DBLayer("lib"); $statement = $dbl->execute("SELECT * FROM ticket WHERE TId=:id", array('id' => $id)); @@ -276,7 +368,10 @@ class Ticket{ $this->priority = $row['Priority']; } - //update private data to DB. + + /** + * update the objects attributes to the db. + */ public function update(){ $dbl = new DBLayer("lib"); $query = "UPDATE ticket SET Timestamp = :timestamp, Title = :title, Status = :status, Queue = :queue, Ticket_Category = :tcat, Author = :author, Priority = :priority WHERE TId=:id"; @@ -284,67 +379,102 @@ class Ticket{ $statement = $dbl->execute($query, $values); } - //hasInfo + + /** + * check if a ticket has a ticket_info page or not. + * @return true or false + */ public function hasInfo(){ return Ticket_Info::TicketHasInfo($this->getTId()); } - /*FUNCTION: postreply - * returns all possible statusses - * - * - public function postReply() { - return Array("Waiting on user reply","Waiting on support","Waiting on Dev reply","Closed"); - }*/ + ////////////////////////////////////////////Getters//////////////////////////////////////////////////// + /** + * get tId attribute of the object. + */ public function getTId(){ return $this->tId; } + /** + * get timestamp attribute of the object in the format defined in the outputTime function of the Helperclass. + */ public function getTimestamp(){ return Helpers::outputTime($this->timestamp); } + /** + * get title attribute of the object. + */ public function getTitle(){ return $this->title; } + /** + * get status attribute of the object. + */ public function getStatus(){ return $this->status; } + /** + * get status attribute of the object in the form of text (string). + */ public function getStatusText(){ $statusArray = Ticket::getStatusArray(); return $statusArray[$this->getStatus()]; } + /** + * get category attribute of the object in the form of text (string). + */ public function getCategoryName(){ $category = Ticket_Category::constr_TCategoryId($this->getTicket_Category()); return $category->getName(); } + /** + * get queue attribute of the object. + */ public function getQueue(){ return $this->queue; } + /** + * get ticket_category attribute of the object (int). + */ public function getTicket_Category(){ return $this->ticket_category; } + /** + * get author attribute of the object (int). + */ public function getAuthor(){ return $this->author; } + /** + * get priority attribute of the object (int). + */ public function getPriority(){ return $this->priority; } + /** + * get priority attribute of the object in the form of text (string). + */ public function getPriorityText(){ $priorityArray = Ticket::getPriorityArray(); return $priorityArray[$this->getPriority()]; } + /** + * get the user assigned to the ticket. + * or return 0 in case not assigned. + */ public function getAssigned(){ $user_id = Assigned::getUserAssignedToTicket($this->getTId()); if ($user_id == ""){ @@ -354,6 +484,10 @@ class Ticket{ } } + /** + * get the name of the support group to whom the ticket is forwarded + * or return 0 in case not forwarded. + */ public function getForwardedGroupName(){ $group_id = Forwarded::getSGroupOfTicket($this->getTId()); if ($group_id == ""){ @@ -363,6 +497,10 @@ class Ticket{ } } + /** + * get the id of the support group to whom the ticket is forwarded + * or return 0 in case not forwarded. + */ public function getForwardedGroupId(){ $group_id = Forwarded::getSGroupOfTicket($this->getTId()); if ($group_id == ""){ @@ -373,34 +511,66 @@ class Ticket{ } ////////////////////////////////////////////Setters//////////////////////////////////////////////////// + /** + * set tId attribute of the object. + * @param $id integer id of the ticket + */ public function setTId($id){ $this->tId = $id; } + /** + * set timestamp attribute of the object. + * @param $ts timestamp of the ticket + */ public function setTimestamp($ts){ $this->timestamp = $ts; } + /** + * set title attribute of the object. + * @param $t title of the ticket + */ public function setTitle($t){ $this->title = $t; } + /** + * set status attribute of the object. + * @param $s status of the ticket(int) + */ public function setStatus($s){ $this->status = $s; } + /** + * set queue attribute of the object. + * @param $q queue of the ticket + */ public function setQueue($q){ $this->queue = $q; } + /** + * set ticket_category attribute of the object. + * @param $tc ticket_category id of the ticket(int) + */ public function setTicket_Category($tc){ $this->ticket_category = $tc; } + /** + * set author attribute of the object. + * @param $a author of the ticket + */ public function setAuthor($a){ $this->author = $a; } + /** + * set priority attribute of the object. + * @param $p priority of the ticket + */ public function setPriority($p){ $this->priority = $p; } diff --git a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_category.php b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_category.php index c2fd6a5d4..92e603d12 100644 --- a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_category.php +++ b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_category.php @@ -1,14 +1,19 @@ setTCategoryId($id); return $instance; } - //returns list of all category objects + + /** + * return a list of all category objects. + * @return an array consisting of all category objects. + */ public static function getAllCategories() { $dbl = new DBLayer("lib"); $statement = $dbl->executeWithoutParams("SELECT * FROM ticket_category"); @@ -43,10 +55,19 @@ class Ticket_Category{ ////////////////////////////////////////////Methods//////////////////////////////////////////////////// + /** + * A constructor. + * Empty constructor + */ public function __construct() { } - //return constructed element based on TCategoryId + + /** + * loads the object's attributes. + * loads the object's attributes by giving a categories id. + * @param $id the id of the ticket_category that should be loaded + */ public function load_With_TCategoryId( $id) { $dbl = new DBLayer("lib"); $statement = $dbl->execute("SELECT * FROM ticket_category WHERE TCategoryId=:id", array('id' => $id)); @@ -56,7 +77,9 @@ class Ticket_Category{ } - //update private data to DB. + /** + * update object attributes to the DB. + */ public function update(){ $dbl = new DBLayer("lib"); $query = "UPDATE ticket_category SET Name = :name WHERE TCategoryId=:id"; @@ -66,6 +89,9 @@ class Ticket_Category{ ////////////////////////////////////////////Getters//////////////////////////////////////////////////// + /** + * get name attribute of the object. + */ public function getName(){ if ($this->name == ""){ $this->load_With_TCategoryId($this->tCategoryId); @@ -73,7 +99,9 @@ class Ticket_Category{ return $this->name; } - + /** + * get tCategoryId attribute of the object. + */ public function getTCategoryId(){ return $this->tCategoryId; } @@ -81,10 +109,18 @@ class Ticket_Category{ ////////////////////////////////////////////Setters//////////////////////////////////////////////////// + /** + * set name attribute of the object. + * @param $n name of the category + */ public function setName($n){ $this->name = $n; } + /** + * set tCategoryId attribute of the object. + * @param $id integer id of the category + */ public function setTCategoryId($id){ $this->tCategoryId = $id; } diff --git a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_content.php b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_content.php index bc9ca8398..445cad867 100644 --- a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_content.php +++ b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_content.php @@ -1,14 +1,25 @@ setTContentId($id); @@ -18,10 +29,18 @@ class Ticket_Content{ ////////////////////////////////////////////Methods//////////////////////////////////////////////////// + /** + * A constructor. + * Empty constructor + */ public function __construct() { } - //Creates a ticket_content entry in the DB + + /** + * creates a new 'tickt_content' entry. + * this method will use the object's attributes for creating a new 'ticket_content' entry in the database. + */ public function create() { $dbl = new DBLayer("lib"); $query = "INSERT INTO ticket_content (Content) VALUES (:content)"; @@ -29,7 +48,12 @@ class Ticket_Content{ $this->tContentId = $dbl->executeReturnId($query, $values); ; } - //return constructed element based on TContentId + + /** + * loads the object's attributes. + * loads the object's attributes by giving a ticket_content's id, + * @param $id the id of the ticket_content entry that should be loaded + */ public function load_With_TContentId( $id) { $dbl = new DBLayer("lib"); $statement = $dbl->execute("SELECT * FROM ticket_content WHERE TContentId=:id", array('id' => $id)); @@ -38,7 +62,9 @@ class Ticket_Content{ $this->content = $row['Content']; } - //update private data to DB. + /** + * update the object's attributes to the database. + */ public function update(){ $dbl = new DBLayer("lib"); $query = "UPDATE ticket_content SET Content = :content WHERE TContentId=:id"; @@ -48,6 +74,9 @@ class Ticket_Content{ ////////////////////////////////////////////Getters//////////////////////////////////////////////////// + /** + * get content attribute of the object. + */ public function getContent(){ if ($this->content == ""){ $this->load_With_TContentId($this->tContentId); @@ -55,7 +84,9 @@ class Ticket_Content{ return $this->content; } - + /** + * get tContentId attribute of the object. + */ public function getTContentId(){ return $this->tContentId; } @@ -63,10 +94,18 @@ class Ticket_Content{ ////////////////////////////////////////////Setters//////////////////////////////////////////////////// + /** + * set content attribute of the object. + * @param $c content of a reply + */ public function setContent($c){ $this->content = $c; } + /** + * set tContentId attribute of the object. + * @param $c integer id of ticket_content entry + */ public function setTContentId($c){ $this->tContentId = $c; }