From 03b48ea0d3b1083a11f255ee99f6fd7bf79e7c2f Mon Sep 17 00:00:00 2001
From: Quitta <none@none>
Date: Thu, 12 Sep 2013 06:13:28 +0200
Subject: [PATCH] some more documented classes..

--HG--
branch : quitta-gsoc-2013
---
 .../ams_lib/autoload/ticket_info.php          | 220 +++++++++++++++---
 .../ryzom_ams/ams_lib/autoload/ticket_log.php | 121 +++++++++-
 2 files changed, 300 insertions(+), 41 deletions(-)

diff --git a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_info.php b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_info.php
index 513967c99..fc852d093 100644
--- a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_info.php
+++ b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_info.php
@@ -1,38 +1,54 @@
 <?php
-
+/**
+* Class that handles additional info sent by ticket creation ingame.
+* If a user creates a ticket ingame, there are a lot of extra $_GET parameters being sent inside the http request that might have something todo with the ticket.
+* for example the OS the user uses or the processor of it's computer, but also the current client version etc.
+* This information can be stored and retrieved by using the ticket_info class.
+* @author Daan Janssens, mentored by Matthew Lagoe
+*/
 class Ticket_Info{
     
-    private $tInfoId;
-    private $ticket; 
-    private $shardid;
-    private $user_position;
-    private $view_position;
-    private $client_version;
-    private $patch_version;
-    private $server_tick;
-    private $connect_state;
-    private $local_address;    
-    private $memory;
-    private $os;
-    private $processor;  
-    private $cpu_id;
-    private $cpu_mask;
-    private $ht;
-    private $nel3d;
-    private $user_id;
+    private $tInfoId; /**< The id of ticket_info entry */
+    private $ticket;  /**< The ticket linked to this ticket_info entry */
+    
+    private $shardid; /**< The shard id */
+    private $user_position; /**< The user's character position */
+    private $view_position; /**< The view position of the character */
+    private $client_version; /**< The client version in use */
+    private $patch_version; /**< The patch version in use */
+    private $server_tick; /**< The current server tick */
+    private $connect_state; /**< The connect state */
+    private $local_address;  /**< local ip */
+    private $memory; /**< memory usage information */
+    private $os; /**< os information */
+    private $processor;  /**< processor information */
+    private $cpu_id; /**< the cpu id */
+    private $cpu_mask; /**< the cpu mask */
+    private $ht; /**< tbh I have no idea :D */
+    private $nel3d; /**< the nel3d version */
+    private $user_id; /**< The users id */
 
     
     ////////////////////////////////////////////Functions////////////////////////////////////////////////////
     
-   
     
-    //Creates a log entry
+    /**
+    * create a ticket_info entry.
+    * @param $info_array the info array (this can be the entire $_GET array being sent by the ingame browser)
+    */
     public static function create_Ticket_Info($info_array) {
         $ticket_info = new self();
         $ticket_info->set($info_array);
         $ticket_info->create();
     }
      
+     
+    /**
+    * check if a specific ticket has extra info or not.
+    * Not all tickets have extra info, only tickets made ingame do. This function checks if a specific ticket does have a ticket_info entry linked to it.
+    * @param $ticket_id the id of the ticket that we want to query
+    * @return true or false
+    */
     public static function TicketHasInfo($ticket_id) {
         $dbl = new DBLayer("lib");
         //check if ticket is already assigned
@@ -42,12 +58,22 @@ class Ticket_Info{
             return false;
         } 
     }
+    
+    
     ////////////////////////////////////////////Methods////////////////////////////////////////////////////
      
+    /**
+    * A constructor.
+    * Empty constructor
+    */
     public function __construct() {
     }
     
-    //set values
+    
+    /**
+    * sets the object's attributes.
+    * @param $values should be an array.
+    */
     public function set($values) {
         $this->setTicket($values['Ticket']);
         $this->setShardId($values['ShardId']);
@@ -69,7 +95,11 @@ class Ticket_Info{
       
     } 
 
-    //Load with tInfoId
+    /**
+    * loads the object's attributes by using a ticket_info id.
+    * loads the object's attributes by giving a ticket_info's entry id.
+    * @param $id the id of the ticket_info entry that should be loaded
+    */
     public function load_With_TInfoId( $id) {
         $dbl = new DBLayer("lib");
         $statement = $dbl->execute("SELECT * FROM ticket_info WHERE TInfoId=:id", array('id' => $id));
@@ -77,7 +107,12 @@ class Ticket_Info{
         $this->set($row);
     }
     
-    //Load with ticket Id
+    
+    /**
+    * loads the object's attributes by using a ticket's id.
+    * loads the object's attributes by giving a ticket's entry id.
+    * @param $id the id of the ticket, the ticket_info entry of that ticket should be loaded.
+    */
     public function load_With_Ticket( $id) {
         $dbl = new DBLayer("lib");
         $statement = $dbl->execute("SELECT * FROM ticket_info WHERE Ticket=:id", array('id' => $id));
@@ -85,7 +120,11 @@ class Ticket_Info{
         $this->set($row);
     }
     
-    //create ticket info
+    
+    /**
+    * creates a new 'ticket_info' entry.
+    * this method will use the object's attributes for creating a new 'ticket_info' entry in the database.
+    */
     public function create() {
         $dbl = new DBLayer("lib");
         $query = "INSERT INTO ticket_info ( Ticket, ShardId, UserPosition,ViewPosition, ClientVersion, PatchVersion,ServerTick, ConnectState, LocalAddress, Memory, OS, 
@@ -99,75 +138,128 @@ Processor, CPUID, CpuMask, HT, NeL3D,  UserId) VALUES ( :ticket, :shardid, :user
     
     ////////////////////////////////////////////Getters////////////////////////////////////////////////////
     
+    /**
+    * get tInfoId attribute of the object.
+    */
     public function getTInfoId(){
         return $this->tInfoId;
     }
     
+    /**
+    * get ticket attribute of the object.
+    */
     public function getTicket(){
         return $this->ticket;
     }
     
+    /**
+    * get shardid attribute of the object.
+    */
     public function getShardId(){
         return $this->shardid;
     }
     
+    /**
+    * get user_position attribute of the object.
+    */
     public function getUser_Position(){
         return $this->user_position;
     }
    
+    /**
+    * get view_position attribute of the object.
+    */
     public function getView_Position(){
         return $this->view_position;
     }
     
+    /**
+    * get client_version attribute of the object.
+    */
     public function getClient_Version(){
         return $this->client_version;
     }
     
+    /**
+    * get patch_version attribute of the object.
+    */
     public function getPatch_Version(){
        return $this->patch_version;
     }
     
+    /**
+    * get server_tick attribute of the object.
+    */
     public function getServer_Tick(){
         return $this->server_tick;
     }
     
+    /**
+    * get connect_state attribute of the object.
+    */
     public function getConnect_State(){
         return $this->connect_state;
     }
    
+    /**
+    * get local_address attribute of the object.
+    */
     public function getLocal_Address(){
         return $this->local_address;
     }
     
+    /**
+    * get memory attribute of the object.
+    */
     public function getMemory(){
         return $this->memory;
     }
     
+    /**
+    * get os attribute of the object.
+    */
     public function getOS(){
        return $this->os;
     }
     
+    /**
+    * get processor attribute of the object.
+    */
     public function getProcessor(){
         return $this->processor;
     }
     
-    
+    /**
+    * get cpu_id attribute of the object.
+    */
     public function getCPUId(){
         return $this->cpu_id;
     }
     
+    /**
+    * get cpu_mask attribute of the object.
+    */
     public function getCPU_Mask(){
        return $this->cpu_mask;
     }
     
+    /**
+    * get ht attribute of the object.
+    */
     public function getHT(){
        return $this->ht;
     }
     
+    /**
+    * get nel3d attribute of the object.
+    */
     public function getNel3D(){
         return $this->nel3d;
     }
     
+    /**
+    * get user_id attribute of the object.
+    */
     public function getUser_Id(){
        return $this->user_id;
     }
@@ -175,75 +267,145 @@ Processor, CPUID, CpuMask, HT, NeL3D,  UserId) VALUES ( :ticket, :shardid, :user
 
     ////////////////////////////////////////////Setters////////////////////////////////////////////////////
      
+    /**
+    * set tInfoId attribute of the object.
+    * @param $id integer id of ticket_info object itself
+    */
     public function setTInfoId($id){
         $this->tInfoId = $id;
     }   
-        
+    
+    /**
+    * set ticket attribute of the object.
+    * @param $t integer id of the ticket linked to the info object
+    */
     public function setTicket($t){
         $this->ticket = $t;
     }
     
+    /**
+    * set shardid attribute of the object.
+    * @param $s (integer) shard id
+    */
     public function setShardId($s){
         $this->shardid = $s;
     }
     
+    /**
+    * set user_position attribute of the object.
+    * @param $u the users position
+    */
     public function setUser_Position($u){
         $this->user_position = $u;
     }
-   
+    
+    /**
+    * set view_position attribute of the object.
+    * @param $v the view position
+    */
     public function setView_Position($v){
         $this->view_position = $v;
     }
     
+    /**
+    * set client_version attribute of the object.
+    * @param $c client version number
+    */
     public function setClient_Version($c){
         $this->client_version = $c;
     }
     
+    /**
+    * set patch_version attribute of the object.
+    * @param $p patch version number
+    */
     public function setPatch_Version($p){
        $this->patch_version = $p;
     }
     
+    /**
+    * set server_tick attribute of the object.
+    * @param $s integer that resembles the server tick
+    */
     public function setServer_Tick($s){
         $this->server_tick = $s;
     }
     
+    /**
+    * set connect_state attribute of the object.
+    * @param $c string that defines the connect state.
+    */
     public function setConnect_State($c){
         $this->connect_state = $c;
     }
    
+    /**
+    * set local_address attribute of the object.
+    * @param $l local address
+    */
     public function setLocal_Address($l){
         $this->local_address = $l;
     }
     
+    /**
+    * set memory attribute of the object.
+    * @param $m memory usage 
+    */
     public function setMemory($m){
         $this->memory = $m;
     }
     
+    /**
+    * set os attribute of the object.
+    * @param $o set os version information
+    */
     public function setOS($o){
        $this->os = $o;
     }
     
+    /**
+    * set processor attribute of the object.
+    * @param $p processor information
+    */
     public function setProcessor($p){
         $this->processor = $p;
     }
     
-    
+    /**
+    * set cpu_id attribute of the object.
+    * @param $c cpu id information
+    */
     public function setCPUId($c){
         $this->cpu_id = $c;
     }
     
+    /**
+    * set cpu_mask attribute of the object.
+    * @param $c mask of the cpu
+    */
     public function setCPU_Mask($c){
        $this->cpu_mask = $c;
     }
     
+    /**
+    * set ht attribute of the object.
+    */
     public function setHT($h){
        $this->ht = $h;
     }
     
+    /**
+    * set nel3d attribute of the object.
+    * @param $n version information about NeL3D
+    */
     public function setNel3D($n){
         $this->nel3d = $n;
     }
     
+    /**
+    * set user_id attribute of the object.
+    * @param $u the user_id.
+    */
     public function setUser_Id($u){
         $this->user_id = $u;
     }
diff --git a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_log.php b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_log.php
index ee6f6b9ef..70eef6b91 100644
--- a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_log.php
+++ b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_log.php
@@ -1,12 +1,29 @@
 <?php
+/**
+* Class that handles the logging. The logging will be used when a ticket is created, a reply is added, if someone views a ticket,
+* if someone assigns a ticket to him or if someone forwards a ticket. This class provides functions to get retrieve those logs and also make them.
+* 
+*-the Action IDs being used are:
+* -# User X Created ticket
+* -# Admin X created ticket for arg
+* -# Read ticket
+* -# Added Reply ID: arg to ticket
+* -# Changed status to arg
+* -# Changed Priority to arg
+* -# assigned to the ticket
+* -# forwarded ticket to support group arg
+* -# unassigned to the ticket
+*
+* @author Daan Janssens, mentored by Matthew Lagoe
+*/
 
 class Ticket_Log{
     
-    private $tLogId;
-    private $timestamp;
-    private $query;
-    private $author;
-    private $ticket;
+    private $tLogId; /**< The id of the log entry */ 
+    private $timestamp; /**< The timestamp of the log entry */ 
+    private $query; /**< The query (json encoded array containing action id & argument) */ 
+    private $author; /**< author of the log */ 
+    private $ticket; /**< the id of the ticket related to the log entry */ 
     
     /****************************************
      *Action ID's:
@@ -25,7 +42,11 @@ class Ticket_Log{
     
     ////////////////////////////////////////////Functions////////////////////////////////////////////////////
     
-     //return all logs that are related to a ticket
+    /**
+    * return all log entries related to a ticket.
+    * @param $ticket_id the id of the ticket of which we want all related log entries returned.
+    * @return an array of ticket_log objects, be aware that the author in the ticket_log object is a ticket_user object on its own (so not a simple integer).
+    */
     public static function getLogsOfTicket( $ticket_id) {
         $dbl = new DBLayer("lib");
         $statement = $dbl->execute("SELECT * FROM ticket_log INNER JOIN ticket_user ON ticket_log.Author = ticket_user.TUserId and ticket_log.Ticket=:id ORDER BY ticket_log.TLogId ASC", array('id' => $ticket_id));
@@ -47,7 +68,16 @@ class Ticket_Log{
         return $result; 
     }
     
-    //Creates a log entry
+    
+    /**
+    * create a new log entry.
+    * It will check if the $TICKET_LOGGING global var is true, this var is used to turn logging on and off. In case it's on, the log message will be stored.
+    * the action id and argument (which is -1 by default), will be json encoded and stored in the query field in the db.
+    * @param $ticket_id the id of the ticket related to the new log entry
+    * @param $author_id the id of the user that instantiated the logging.
+    * @param $action the action id (see the list in the class description)
+    * @param $arg argument for the action (default = -1)
+    */
     public static function createLogEntry( $ticket_id, $author_id, $action, $arg = -1) {
         global $TICKET_LOGGING;
         if($TICKET_LOGGING){
@@ -59,14 +89,23 @@ class Ticket_Log{
     }
 
 
-    //return constructed element based on TLogId
+    /**
+    * return constructed element based on TLogId
+    * @param $ticket_log id of the entry that we want to load into our object.
+    * @return constructed ticket_log object.
+    */
     public static function constr_TLogId( $id) {
         $instance = new self();
         $instance->setTLogId($id);
         return $instance;
     }
     
-    //returns list of all logs of a ticket
+    /**
+    * return all log entries related to a ticket.
+    * @param $ticket_id the id of the ticket of which we want all related log entries returned.
+    * @return an array of ticket_log objects, here the author is an integer.
+    * @todo only use one of the 2 comparable functions in the future and make the other depricated.
+    */
     public static function getAllLogs($ticket_id) {
         $dbl = new DBLayer("lib");
         $statement = $dbl->execute("SELECT * FROM ticket_log INNER JOIN ticket_user ON ticket_log.Author = ticket_user.TUserId and ticket_log.Ticket=:id", array('id' => $ticket_id));
@@ -83,10 +122,17 @@ class Ticket_Log{
     
     ////////////////////////////////////////////Methods////////////////////////////////////////////////////
      
+    /**
+    * A constructor.
+    * Empty constructor
+    */
     public function __construct() {
     }
     
-    //set values
+    /**
+    * sets the object's attributes.
+    * @param $values should be an array.
+    */
     public function set($values) {
         $this->setTLogId($values['TLogId']);
         $this->setTimestamp($values['Timestamp']);
@@ -95,7 +141,11 @@ class Ticket_Log{
         $this->setAuthor($values['Author']);
     } 
 
-    //Load with tlogId
+    /**
+    * loads the object's attributes.
+    * loads the object's attributes by giving a ticket_log entries ID (TLogId).
+    * @param id the id of the ticket_log entry that should be loaded
+    */
     public function load_With_TLogId( $id) {
         $dbl = new DBLayer("lib");
         $statement = $dbl->execute("SELECT * FROM ticket_log WHERE TLogId=:id", array('id' => $id));
@@ -104,7 +154,9 @@ class Ticket_Log{
     }
     
     
-    //update private data to DB.
+    /**
+    * update attributes of the object to the DB.
+    */
     public function update(){
         $dbl = new DBLayer("lib");
         $query = "UPDATE ticket_log SET Timestamp = :timestamp, Query = :query, Author = :author, Ticket = :ticket WHERE TLogId=:id";
@@ -114,36 +166,61 @@ class Ticket_Log{
     
     ////////////////////////////////////////////Getters////////////////////////////////////////////////////
     
+    /**
+    * get tLogId attribute of the object.
+    */
     public function getTLogId(){
         return $this->tLogId;
     }
     
+    /**
+    * get timestamp attribute of the object.
+    */
     public function getTimestamp(){
         return Helpers::outputTime($this->timestamp);
     }
     
+    /**
+    * get query attribute of the object.
+    */
     public function getQuery(){
         return $this->query;
     }
     
+    /**
+    * get author attribute of the object.
+    */
     public function getAuthor(){
         return $this->author;
     }
    
+    /**
+    * get ticket attribute of the object.
+    */
     public function getTicket(){
         return $this->ticket;
     }
     
+    /**
+    * get the action id out of the query by decoding it.
+    */
     public function getAction(){
         $decodedQuery = json_decode($this->query);
         return $decodedQuery[0];
     }
     
+    /**
+    * get the argument out of the query by decoding it.
+    */
     public function getArgument(){
         $decodedQuery = json_decode($this->query);
         return $decodedQuery[1];
     }
     
+    /**
+    * get the action text(string) array.
+    * this is being read from the language .ini files.
+    */
     public function getActionTextArray(){
        $variables = Helpers::handle_language();
        $result = array();
@@ -155,22 +232,42 @@ class Ticket_Log{
     
     ////////////////////////////////////////////Setters////////////////////////////////////////////////////
      
+    /**
+    * set tLogId attribute of the object.
+    * @param $id integer id of the log entry
+    */
     public function setTLogId($id){
         $this->tLogId = $id;
     }
     
+    /**
+    * set timestamp attribute of the object.
+    * @param $t timestamp of the log entry
+    */
     public function setTimestamp($t){
         $this->timestamp = $t;
     }
     
+    /**
+    * set query attribute of the object.
+    * @param $q the encoded query
+    */
     public function setQuery($q){
         $this->query = $q;
     }
     
+    /**
+    * set author attribute of the object.
+    * @param $a integer id of the user who created the log entry
+    */
     public function setAuthor($a){
         $this->author = $a;
     }
     
+    /**
+    * set ticket attribute of the object.
+    * @param $t integer id of ticket of which the log entry is related to.
+    */
     public function setTicket($t){
         $this->ticket = $t;
     }