From ff628f0e611870fc9249b57e067a57b6630906df Mon Sep 17 00:00:00 2001
From: Quitta <Quitta@localhost>
Date: Wed, 11 Sep 2013 01:38:53 +0200
Subject: [PATCH] added more documentation..

---
 .../ryzom_ams/ams_lib/autoload/assigned.php   |  2 -
 .../ams_lib/autoload/gui_elements.php         | 30 ++++++-
 .../ryzom_ams/ams_lib/autoload/helpers.php    | 57 ++++++++++--
 .../ams_lib/autoload/in_support_group.php     | 62 +++++++++++--
 .../ams_lib/autoload/mail_handler.php         | 90 +++++++++++++++----
 .../ryzom_ams/ams_lib/autoload/mycrypt.php    | 38 +++++++-
 6 files changed, 240 insertions(+), 39 deletions(-)

diff --git a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/assigned.php b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/assigned.php
index 4989767aa..8de17a9e2 100644
--- a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/assigned.php
+++ b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/assigned.php
@@ -3,7 +3,6 @@
 * Handles the assigning of a ticket to a user. This is being used to make someone responsible for the handling and solving of a ticket.
 * The idea is that someone can easily assign a ticket to himself and by doing that, he makes aware to the other moderators that he will deal with the ticket in the future.
 * @author Daan Janssens, mentored by Matthew Lagoe
-* 
 */
 class Assigned{
 
@@ -92,7 +91,6 @@ class Assigned{
     
     ////////////////////////////////////////////Methods////////////////////////////////////////////////////
     
-    
     /**
     * A constructor.
     * Empty constructor
diff --git a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/gui_elements.php b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/gui_elements.php
index e9748fc04..e09de1621 100644
--- a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/gui_elements.php
+++ b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/gui_elements.php
@@ -1,7 +1,21 @@
 <?php
-
+/**
+* Helper class for generating gui related elements.
+* This class contains functions that generate data-arrays for tables, or other visual entities
+* @author Daan Janssens, mentored by Matthew Lagoe
+* 
+*/
 class Gui_Elements{
     
+    /**
+    * creates an array of information out of a list of objects which can be used to form a table.
+    * The idea of this is that you can pass an array of objects, an array of functions to perform on each object and a name for the index of the returning array to store
+    * the result.
+    * @param $inputList the list of objects of which we want to make a table.
+    * @param $funcArray a list of methods of that object we want to perform.
+    * @param $fieldArray a list of strings, that will be used to store our result into.
+    * @return an array with the indexes listed in $fieldArray and which holds the results of the methods in $funcArray on each object in the $inputList
+    */
     public static function make_table( $inputList, $funcArray ,$fieldArray){
         $i = 0; 
         $result = Array();
@@ -36,7 +50,14 @@ class Gui_Elements{
         return $result;  
     }
     
-    
+    /**
+    * creates an array of information out of a list of objects which can be used to form a table with a key as id.
+    * The idea is comparable to the make_table() function, though this time the results are stored in the index that is returned by the idFunction()
+    * @param $inputList the list of objects of which we want to make a table.
+    * @param $funcArray a list of methods of that object we want to perform.
+    * @param $idFunction a function that returns an id that will be used as index to store our result
+    * @return an array which holds the results of the methods in $funcArray on each object in the $inputList, though thearrays indexes are formed by using the idFunction.
+    */
     public static function make_table_with_key_is_id( $inputList, $funcArray, $idFunction){
         $result = Array();
         foreach($inputList as $element){
@@ -48,6 +69,11 @@ class Gui_Elements{
     }
     
     
+    /**
+    * returns the elapsed time from a timestamp up till now.
+    * @param $ptime a timestamp.
+    * @return a string in the form of A years, B months, C days, D hours, E minutes, F seconds ago.
+    */
     public static function time_elapsed_string($ptime){
         global $TIME_FORMAT;
         $ptime = DateTime::createFromFormat($TIME_FORMAT, $ptime)->getTimestamp();
diff --git a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/helpers.php b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/helpers.php
index 24bfc5abd..24aed5483 100644
--- a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/helpers.php
+++ b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/helpers.php
@@ -1,8 +1,20 @@
 <?php
-
+/**
+* Helper class for more site specific functions.
+* @author Daan Janssens, mentored by Matthew Lagoe
+* 
+*/
 class Helpers{
      
-
+     /**
+    * workhorse of the website, it loads the template and shows it or returns th html.
+    * it uses smarty to load the $template, but before displaying the template it will pass the $vars to smarty. Also based on your language settings a matching
+    * array of words & sentences for that page will be loaded. In case the $returnHTML parameter is set to true, it will return the html instead of displaying the template.
+    * @param $template the name of the template(page) that we want to load.
+    * @param $vars an array of variables that should be loaded by smarty before displaying or returning the html.
+    * @param $returnHTML (default=false) if set to true, the html that should have been displayed, will be returned.
+    * @return in case $returnHTML=true, it returns the html of the template being loaded.
+    */
      public static function loadTemplate( $template, $vars = array (), $returnHTML = false )
     {
          global $AMS_LIB;
@@ -23,8 +35,11 @@ class Helpers{
          $smarty -> caching = false;
          $smarty -> cache_lifetime = 120;
 
+          //needed by smarty.
          helpers :: create_folders ();
           global $FORCE_INGAME;
+          
+          //if ingame, then use the ingame templates
           if ( helpers::check_if_game_client() or $FORCE_INGAME ){
              $smarty -> template_dir = $AMS_LIB . '/ingame_templates/';
              $smarty -> setConfigDir( $AMS_LIB . '/configs' );
@@ -41,12 +56,13 @@ class Helpers{
              $smarty -> assign( $key, $value );
              }
              
-      
+          //load page specific variables that are language dependent
          $variables = Helpers::handle_language();
          foreach ( $variables[$template] as $key => $value ){
              $smarty -> assign( $key, $value );
              }
 
+          //smarty inheritance for loading the matching wrapper layout (with the matching menu bar)
           if( isset($vars['permission']) && $vars['permission'] == 3 ){
                $inherited = "extends:layout_admin.tpl|";
           }else if( isset($vars['permission']) && $vars['permission'] == 2){
@@ -57,8 +73,7 @@ class Helpers{
                $inherited ="";
           }
 
-          
-         
+          //if $returnHTML is set to true, return the html by fetching the template else display the template.
           if($returnHTML == true){
                return $smarty ->fetch($inherited . $template . '.tpl' );
           }else{
@@ -66,6 +81,11 @@ class Helpers{
           }
      }
 
+
+     /**
+    * creates the folders that are needed for smarty.
+    * @todo for the drupal module it might be possible that drupal_mkdir needs to be used instead of mkdir, also this should be in the install.php instead.
+    */
      static public function create_folders(){
          global $AMS_LIB;
          global $SITEBASE;
@@ -78,8 +98,8 @@ class Helpers{
              $SITEBASE . '/configs'
              );
          foreach ( $arr as & $value ){
+          
              if ( !file_exists( $value ) ){
-                 //echo $value;
                  print($value);
                  mkdir($value);
                  }
@@ -87,6 +107,11 @@ class Helpers{
 
          }
 
+
+     /**
+     * check if the http request is sent ingame or not.
+     * @return returns true in case it's sent ingame, else false is returned.
+     */
      static public function check_if_game_client()
     {
          // if HTTP_USER_AGENT is not set then its ryzom core
@@ -98,6 +123,13 @@ class Helpers{
           }
      }
        
+       
+     /**
+     * Handles the language specific aspect.
+     * The language can be changed by setting the $_GET['Language'] & $_GET['setLang'] together. This will also change the language entry of the user in the db.
+     * Cookies are also being used in case the user isn't logged in.
+     * @return returns the parsed content of the language .ini file related to the users language setting.
+     */
      static public function handle_language(){
           global $DEFAULT_LANGUAGE;
           global $AMS_TRANS;
@@ -149,8 +181,11 @@ class Helpers{
           
      }
      
-     
-     //Time output function for handling the time display function.
+
+     /**
+     * Time output function for handling the time display.
+     * @return returns the time in the format specified in the $TIME_FORMAT global variable.
+     */
      static public function outputTime($time, $str = 1){
           global $TIME_FORMAT;
           if($str){
@@ -160,6 +195,12 @@ class Helpers{
           }
      }
      
+     /**
+     * Auto login function for ingame use.
+     * This function will allow users who access the website ingame, to log in without entering the username and password. It uses the COOKIE entry in the open_ring db.
+     * it checks if the cookie sent by the http request matches the one in the db. This cookie in the db is changed everytime the user relogs.
+     * @return returns "FALSE" if the cookies didn't match, else it returns an array with the user's id and name.
+     */
      static public function  check_login_ingame(){
           if ( helpers :: check_if_game_client () or $forcelibrender = false ){
                $dbr = new DBLayer("ring");
diff --git a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/in_support_group.php b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/in_support_group.php
index b01517db2..bf10d3d9a 100644
--- a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/in_support_group.php
+++ b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/in_support_group.php
@@ -1,13 +1,23 @@
 <?php
-
+/**
+* Handles the linkage of users being in a support group.
+* Moderators and Admins can be part of a support group, this class offers functionality to check if a link between a user and group is existing.
+* @author Daan Janssens, mentored by Matthew Lagoe
+* 
+*/
 class In_Support_Group{
     
-    private $user;
-    private $group;
+    private $user; /**< The id of the user being in a support group */ 
+    private $group; /**< The id of the support group*/ 
     
     ////////////////////////////////////////////Functions////////////////////////////////////////////////////
-  
-    //check if user is in in_support_group
+    
+    /**
+    * Check if user is in in_support_group.
+    * @param $user_id the id of the user.
+    * @param $group_id the id of the support group.
+    * @return true is returned in case the user is in the support group, else false is returned.
+    */
     public static function userExistsInSGroup( $user_id, $group_id) {
         $dbl = new DBLayer("lib");
         //check if name is already used
@@ -20,15 +30,28 @@ class In_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('User' => user_id, 'Group' => support_groups_id).
+    */
     public function set($values) {
         $this->setUser($values['User']);
         $this->setGroup($values['Group']);
     }
     
+    
+    /**
+    * creates a new 'in_support_group' entry.
+    * this method will use the object's attributes for creating a new 'in_support_group' entry in the database.
+    */
     public function create() {
         $dbl = new DBLayer("lib");
         $query = "INSERT INTO `in_support_group` (`User`,`Group`) VALUES (:user, :group)";
@@ -36,7 +59,11 @@ class In_Support_Group{
         $dbl->execute($query, $values);
     }
     
-    //delete entry
+    
+    /**
+    * deletes an existing 'in_support_group' entry.
+    * this method will use the object's attributes for deleting an existing 'in_support_group' entry in the database.
+    */
     public function delete() {
         $dbl = new DBLayer("lib");
         $query = "DELETE FROM `in_support_group` WHERE `User` = :user_id and `Group` = :group_id";
@@ -44,31 +71,48 @@ class In_Support_Group{
         $dbl->execute($query, $values);
     }
 
-    //Load with sGroupId
-    public function load( $user_id, $group_id) {
+    /*
+    public function load($group_id) {
         $dbl = new DBLayer("lib");
         $statement = $dbl->execute("SELECT * FROM `in_support_group` WHERE `Group` = :group_id", Array('group_id' => $group_id));
         $row = $statement->fetch();
         $this->set($row);
     }
+    */
     
 
     ////////////////////////////////////////////Getters////////////////////////////////////////////////////
     
+    /**
+    * get user attribute of the object.
+    */
     public function getUser(){
         return $this->user;
     }
     
+    
+    /**
+    * get group attribute of the object.
+    */
     public function getGroup(){
         return $this->group;
     }
     
     ////////////////////////////////////////////Setters////////////////////////////////////////////////////
 
+    /**
+    * set user attribute of the object.
+    * @param $u integer id of the user
+    */
     public function setUser($u){
         $this->user = $u;
     }
     
+    
+    /**
+    * set group attribute of the object.
+    * @param $g integer id of the support group
+    */
     public function setGroup($g){
         $this->group = $g;
     }
diff --git a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/mail_handler.php b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/mail_handler.php
index 4434c62db..18422474f 100644
--- a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/mail_handler.php
+++ b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/mail_handler.php
@@ -1,23 +1,42 @@
  <?php
- 
+/**
+* Handles the mailing functionality.
+* This class covers the reading of the mail boxes of the support_groups, handling those emails, updating tickets accoring to the content & title of the emails,
+* but also the sending of emails after creating a new ticket and when someone else replies on your ticket.
+* @author Daan Janssens, mentored by Matthew Lagoe
+*/
 class Mail_Handler{
     
-    private $db;
-        
-    public function mail_fork() {   
+    private $db; /**< db object used by various methods. */
+    
+    /**
+    * Start a new child process and return the process id
+    * this is used because imap might take some time, we dont want the cron parent process waiting on that.
+    * @return return the child process id
+    */    
+    private function mail_fork() {   
         //Start a new child process and return the process id!
         $pid = pcntl_fork();
         return $pid;
         
     }
     
-    
+    /**
+    * Wrapper for sending emails, creates the content of the email
+    * Based on the type of the ticketing mail it will create a specific email, it will use the language.ini files to load the correct language of the email for the receiver.
+    * Also if the $TICKET_MAILING_SUPPORT is set to false or if the user's personal 'ReceiveMail' entry is set to false then no mail will be sent.
+    * @param $receiver if integer, then it refers to the id of the user to whom we want to mail, if it's a string(email-address) then we will use that.
+    * @param $ticketObj the ticket object itself, this is being used for including ticket related information into the email.
+    * @param $content the content of a reply or new ticket
+    * @param $type REPLY, NEW, WARNAUTHOR, WARNSENDER, WARNUNKNOWNSENDER
+    * @param $sender (default = 0 (if it is not forwarded)) else use the id of the support group to which the ticket is currently forwarded, the support groups email address will be used to send the ticket.
+    */    
     public static function send_ticketing_mail($receiver, $ticketObj, $content, $type, $sender = 0) {
         
         global $TICKET_MAILING_SUPPORT;
         if($TICKET_MAILING_SUPPORT){
             global $MAIL_LOG_PATH;
-            error_log("Receiver: {$receiver}, content: {$content}, type: {$type}, SendingId: {$sender} \n", 3, $MAIL_LOG_PATH);
+            //error_log("Receiver: {$receiver}, content: {$content}, type: {$type}, SendingId: {$sender} \n", 3, $MAIL_LOG_PATH);
             if($sender == 0){
                 //if it is not forwarded (==public == which returns 0) then make it NULL which is needed to be placed in the DB.
                 $sender = NULL;
@@ -84,7 +103,15 @@ class Mail_Handler{
         }
     } 
     
-    
+    /**
+    * send mail function that will add the email to the db.
+    * this function is being used by the send_ticketing_mail() function. It adds the email as an entry to the `email` table in the database, which will be sent later on when we run the cron job.
+    * @param $recipient if integer, then it refers to the id of the user to whom we want to mail, if it's a string(email-address) then we will use that.
+    * @param $subject the subject of the email
+    * @param $body the body of the email
+    * @param $ticket_id the id of the ticket
+    * @param $from the sending support_group's id (NULL in case the default group is sending))
+    */    
     public static function send_mail($recipient, $subject, $body, $ticket_id = 0, $from = NULL) {
         $id_user = NULL;
         if(is_numeric($recipient)) {
@@ -100,7 +127,12 @@ class Mail_Handler{
     }
     
      
-    //the main function
+    /**
+    * the cron funtion (workhorse of the mailing system).
+    * The cron job will create a child process, which will first send the emails that are in the email table in the database, we use some kind of semaphore (a temp file) to make sure that
+    * if the cron job is called multiple times, it wont email those mails multiple times. After this, we will read the mail inboxes of the support groups and the default group using IMAP
+    * and we will add new tickets or new replies according to the incoming emails.
+    */    
     function cron() {
         global $cfg;
         global $MAIL_LOG_PATH;
@@ -206,7 +238,7 @@ class Mail_Handler{
                         $tkey = self::incoming_mail_handler($mbox, $i,$group);
             
                         if($tkey) {
-                            //TODO: base file on Ticket + timestamp
+                            //base file on Ticket + timestamp
                             $file = fopen($MAIL_DIR."/ticket".$tkey, 'w');
                             error_log("Email was written to ".$MAIL_DIR."/ticket".$tkey."\n", 3, $MAIL_LOG_PATH);
                             fwrite($file, imap_fetchheader($mbox, $i) . imap_body($mbox, $i));     
@@ -231,6 +263,12 @@ class Mail_Handler{
     
      
     
+    /**
+    * creates a new message id for a email about to send.
+    * @param $ticket_id the ticket id of the ticket that is mentioned in the email.
+    * @return returns a string, that consist out of some variable parts, a consistent part and the ticket_id. The ticket_id will be used lateron, if someone replies on the message,
+    * to see to which ticket the reply should be added.
+    */    
     function new_message_id($ticketId) {
         $time = time();
         $pid = getmypid();
@@ -241,6 +279,12 @@ class Mail_Handler{
     
     }
     
+    /**
+    * try to fetch the ticket_id out of the subject.
+    * The subject should have a substring of the form [Ticket #ticket_id], where ticket_id should be the integer ID of the ticket.
+    * @param $subject, the subject of an incomming email.
+    * @return if the ticket's id is succesfully parsed, it will return the ticket_id, else it returns 0.
+    */   
     function get_ticket_id_from_subject($subject){
         $startpos = strpos($subject, "[Ticket #");
         if($startpos){
@@ -258,6 +302,16 @@ class Mail_Handler{
     }
     
     
+    /**
+    * Handles an incomming email
+    * Read the content of one email by using imap's functionality. If a ticket id is found inside the message_id or else in the subject line, then a reply will be added
+    * (if the email is not being sent from the authors email address it won't be added though and a warning will be sent to both parties).  If no ticket id is found, then a new
+    * ticket will be created.
+    * @param $mbox a mailbox object
+    * @param $i the email's id in the mailbox (integer)
+    * @param $group the group object that owns the inbox.
+    * @return a string based on the found ticket i and timestamp (will be used to store a copy of the email locally)
+    */   
     function incoming_mail_handler($mbox,$i,$group){
         
         global $MAIL_LOG_PATH;
@@ -352,7 +406,11 @@ class Mail_Handler{
     }
     
      
-    
+    /**
+    * decode utf8
+    * @param $str str to be decoded
+    * @return decoded string
+    */  
     function decode_utf8($str) {
     
         preg_match_all("/=\?UTF-8\?B\?([^\?]+)\?=/i",$str, $arr);
@@ -364,10 +422,12 @@ class Mail_Handler{
     
     }
     
-     
-    
-     
-    
+    /**
+    * returns the mime type of a structure of a email
+    * @param &$structure the structure of an email message.
+    * @return "TEXT", "MULTIPART","MESSAGE", "APPLICATION", "AUDIO","IMAGE", "VIDEO", "OTHER","TEXT/PLAIN"
+    * @todo take care of the HTML part of incoming emails.
+    */  
     function get_mime_type(&$structure) {
     
         $primary_mime_type = array("TEXT", "MULTIPART","MESSAGE", "APPLICATION", "AUDIO","IMAGE", "VIDEO", "OTHER");
@@ -379,7 +439,7 @@ class Mail_Handler{
     }
     
      
-    
+    //to document..
     function get_part($stream, $msg_number, $mime_type, $structure = false, $part_number = false) {
     
         if(!$structure) {
diff --git a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/mycrypt.php b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/mycrypt.php
index 2a90f21a8..6c027e52a 100644
--- a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/mycrypt.php
+++ b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/mycrypt.php
@@ -1,14 +1,28 @@
 <?php
-
+/**
+* Basic encryption/decryption class.
+* We use this class atm for encrypting & decrypting the imap passwords.
+*/
 class MyCrypt{
     
-    private $config;
+    private $config; /**< array that should contain the enc_method & hash_method & key */
     
+    
+    /**
+    * constructor.
+    * loads the config array with the given argument.
+    * @param $cryptinfo an array containing the info needed to encrypt & decrypt.(enc_method & hash_method & key)
+    */
     function __construct($cryptinfo) {
         $this->config = $cryptinfo;
     }
     
-
+    /**
+    * encrypts by using the given enc_method and hash_method.
+    * It will first check if the methods are supported, if not it will throw an error, if so it will encrypt the $data
+    * @param $data the string that we want to encrypt.
+    * @return the encrypted string.
+    */
     public function encrypt($data) {
         
         self::check_methods($this->config['enc_method'], $this->config['hash_method']);
@@ -17,6 +31,11 @@ class MyCrypt{
         return $infostr . openssl_encrypt($data, $this->config['enc_method'], $this->config['key'], false, $iv);
     }
 
+    /**
+    * decrypts by using the given enc_method and hash_method.
+    * @param $edata the encrypted string that we want to decrypt
+    * @return the decrypted string.
+    */
     public function decrypt($edata) {
         $e_arr = explode('$', $edata);
         if( count($e_arr) != 4 ) {
@@ -29,6 +48,13 @@ class MyCrypt{
         return openssl_decrypt($e_arr[3], $this->config['enc_method'], $this->config['key'], false, $iv);
     }
 
+    /**
+    * hashes the key by using a hash method specified.
+    * @param $key the key to be hashed
+    * @param $method the metho of hashing to be used
+    * @param $iv_size the size of the initialization vector.
+    * @return return the hashed key up till the size of the iv_size param.
+    */
     private static function hashIV($key, $method, $iv_size) {
         $myhash = hash($method, $key, TRUE);
         while( strlen($myhash) < $iv_size ) {
@@ -37,6 +63,12 @@ class MyCrypt{
         return substr($myhash, 0, $iv_size);
     }
 
+    /**
+    * checks if the encryption and hash methods are supported
+    * @param $enc the encryption method.
+    * @param $hash the hash method.
+    * @throw Exception in case a method is not supported.
+    */
     private static function check_methods($enc, $hash) {
         
         if( ! function_exists('openssl_encrypt') ) {