Document models and remove redundant code in yagamodel

models/class.actionmodel.php

@@ -2,7 +2,7 @@
 /* Copyright 2013 Zachary Doll */
 
 /**
- * Reactions
+ * Describe the available actions one can react with to other user content.
  *
  * Events:
  *
@@ -11,9 +11,15 @@
  */
 
 class ActionModel extends Gdn_Model {
-  private static $_Actions = NULL;
+  
   /**
-   * Class constructor. Defines the related database table name.
+   * This is used as a cache.
+   * @var object
+   */
+  private static $_Actions = NULL;
+  
+  /**
+   * Defines the related database table name.
    */
   public function __construct() {
     parent::__construct('Action');
@@ -37,6 +43,7 @@ class ActionModel extends Gdn_Model {
 
   /**
    * Returns data for a specific action
+   * 
    * @param int $ActionID
    * @return dataset
    */
@@ -50,6 +57,11 @@ class ActionModel extends Gdn_Model {
     return $Action;
   }
   
+  /**
+   * Gets the last inserted Action
+   * 
+   * @return DataSet
+   */
   public function GetNewestAction() {
     $Action = $this->SQL
                     ->Select()
@@ -60,11 +72,24 @@ class ActionModel extends Gdn_Model {
     return $Action;
   }
 
+  /**
+   * Determine if a specified action exists
+   * 
+   * @param int $ActionID
+   * @return bool
+   */
   public function ActionExists($ActionID) {
     $temp = $this->GetAction($ActionID);
     return !empty($temp);
   }
 
+  /**
+   * Remove an action from the db
+   * 
+   * @param int $ActionID
+   * @param int $ReplacementID what action ID existing reactions should report
+   * to. Null will delete the associated reactions.
+   */
   public function DeleteAction($ActionID, $ReplacementID = NULL) {
     if($this->ActionExists($ActionID)) {
       $this->SQL->Delete('Action', array('ActionID' => $ActionID));

models/class.badgemodel.php

@@ -2,7 +2,7 @@
 /* Copyright 2013 Zachary Doll */
 
 /**
- * Badges
+ * Describes badges and the associated rule criteria
  *
  * Events:
  *
@@ -11,16 +11,24 @@
  */
 
 class BadgeModel extends Gdn_Model {
-  private static $_Badges = NULL;
+  
   /**
-   * Class constructor. Defines the related database table name.
+   * Used as a cache
+   * @var DataSet
+   */
+  private static $_Badges = NULL;
+  
+  /**
+   * Defines the related database table name.
    */
   public function __construct() {
     parent::__construct('Badge');
   }
 
   /**
-   * Returns a list of all available badges
+   * Returns a list of all badges
+   * 
+   * @return DataSet 
    */
   public function GetBadges() {
     if(empty(self::$_Badges)) {
@@ -30,11 +38,15 @@ class BadgeModel extends Gdn_Model {
               ->OrderBy('BadgeID')
               ->Get()
               ->Result();
-      //decho('Filling the badge cache.');
     }
     return self::$_Badges;
   }
 
+  /**
+   * Returns a list of currently enabled badges
+   * 
+   * @return DataSet
+   */
   public function GetEnabledBadges() {
     return $this->SQL
               ->Select()
@@ -47,8 +59,9 @@ class BadgeModel extends Gdn_Model {
   
   /**
    * Returns data for a specific badge
+   * 
    * @param int $BadgeID
-   * @return dataset
+   * @return DataSet
    */
   public function GetBadge($BadgeID) {
     $Badge = $this->SQL
@@ -60,6 +73,11 @@ class BadgeModel extends Gdn_Model {
     return $Badge;
   }
 
+  /**
+   * Returns the last inserted badge
+   * 
+   * @return DataSet
+   */
   public function GetNewestBadge() {
     $Badge = $this->SQL
                     ->Select()
@@ -70,11 +88,23 @@ class BadgeModel extends Gdn_Model {
     return $Badge;
   }
 
+  /**
+   * Convenience function to determin if a badge id currently exists
+   * 
+   * @param int $BadgeID
+   * @return bool
+   */
   public function BadgeExists($BadgeID) {
     $temp = $this->GetBadge($BadgeID);
     return !empty($temp);
   }
 
+  /**
+   * Enable or disable a badge
+   * 
+   * @param int $BadgeID
+   * @param bool $Enable
+   */
   public function EnableBadge($BadgeID, $Enable) {
     $Enable = (!$Enable) ? FALSE : TRUE;
     $this->SQL
@@ -84,10 +114,15 @@ class BadgeModel extends Gdn_Model {
             ->Put();
   }
 
-  public function DeleteBadge($BadgeID, $ReplacementID = NULL) {
+  /**
+   * Remove a badge and associated awards
+   * 
+   * @todo Actually remove the associated awards
+   * @param int $BadgeID
+   */
+  public function DeleteBadge($BadgeID) {
     if($this->BadgeExists($BadgeID)) {
       $this->SQL->Delete('Badge', array('BadgeID' => $BadgeID));
-      // TODO: Cleanup the related badge awards
 //      if($ReplacementID && $this->BadgeExists($ReplacementID)) {
 //        $this->SQL->Update('Reaction')
 //                ->Set('BadgeID', $ReplacementID)
@@ -99,6 +134,14 @@ class BadgeModel extends Gdn_Model {
     }
   }
   
+  /**
+   * Award a badge to a user and record some activity
+   * 
+   * @param int $BadgeID
+   * @param int $UserID This is the user that should get the award
+   * @param int $InsertUserID This is the user that gave the award
+   * @param string $Reason This is the reason the giver gave with the award
+   */
   public function AwardBadge($BadgeID, $UserID, $InsertUserID = NULL, $Reason = '') {
     if($this->BadgeExists($BadgeID)) {
       if(!$this->UserHasBadge($UserID, $BadgeID)) {
@@ -131,7 +174,7 @@ class BadgeModel extends Gdn_Model {
          
          $ActivityModel->Queue($Activity);
          
-         // Notify the user of the unban.
+         // Notify the user of the award
          $Activity['NotifyUserID'] = $UserID;
          $Activity['Emailed'] = ActivityModel::SENT_PENDING;
          $ActivityModel->Queue($Activity, 'Badges', array('Force' => TRUE));
@@ -141,6 +184,14 @@ class BadgeModel extends Gdn_Model {
     } 
   }
   
+  /**
+   * Returns how many badges the user has of this particular id. It should only 
+   * ever be 1 or zero.
+   * 
+   * @param int $UserID
+   * @param int $BadgeID
+   * @return int
+   */
   public function UserHasBadge($UserID, $BadgeID) {
     return $this->SQL
             ->Select()
@@ -150,6 +201,12 @@ class BadgeModel extends Gdn_Model {
             ->GetCount();
   }
   
+  /**
+   * Returns the badges a user already has
+   * 
+   * @param int $UserID
+   * @return array
+   */
   public function GetUserBadgeAwards($UserID) {
     return $this->SQL
             ->Select()

models/class.reactionmodel.php

@@ -2,26 +2,39 @@
 /* Copyright 2013 Zachary Doll */
 
 /**
- * Reactions
+ * Reactions are the actions a user takes against another user's content
  * 
- * Events:
+ * Events: AfterReactionSave
  * 
  * @package Yaga
  * @since 1.0
  */
 
 class ReactionModel extends Gdn_Model {
-  private static $_Reactions = array();
+  
-  private static $_Actions = NULL;
   /**
-   * Class constructor. Defines the related database table name.
+   * Used to cache the reactions
+   * @var array
+   */
+  private static $_Reactions = array();
+  
+  /**
+   * Used as a cache for the available actions
+   * @var DataSet
+   */
+  private static $_Actions = NULL;
+  
+  /**
+   * Defines the related database table name.
    */
   public function __construct() {
     parent::__construct('Reaction');
   }
 
   /**
-   * Returns a list of all available actions
+   * Returns a list of all available actions.
+   * 
+   * @return DataSet
    */
   public function GetActions() {
     if(empty(self::$_Actions)) {
@@ -31,15 +44,15 @@ class ReactionModel extends Gdn_Model {
               ->OrderBy('ActionID')
               ->Get()
               ->Result();
-      //decho('Filling the action cache.');
     }
     return self::$_Actions;
   }
   
   /**
    * Returns data for a specific action
+   * 
    * @param int $ActionID
-   * @return dataset
+   * @return DataSet
    */
   public function GetActionID($ActionID) {
     return $this->SQL
@@ -51,9 +64,10 @@ class ReactionModel extends Gdn_Model {
   }
 
   /**
-   * Returns the reactions associated a specified ID.
+   * Returns the reactions associated with the specified user content.
+   * 
    * @param int $ID
-   * @param enum $Type is the kind of ID. Valid values are comment and discussion
+   * @param enum $Type is the kind of ID. Valid: comment, discussion, activity
    */
   public function GetReactions($ID, $Type) {
     if(in_array($Type, array('discussion', 'comment', 'activity')) && $ID > 0) {
@@ -74,8 +88,8 @@ class ReactionModel extends Gdn_Model {
                   ->Where('ParentID', $ID)
                   ->Where('ParentType', $Type)
                   ->Get()
-                  ->Result();               
+                  ->Result();
-          //decho($Reaction);
+          
           foreach($Reactions as $Reaction) {
             $ReactionSet[$Index]->UserIDs[] = $Reaction->UserID;
             $ReactionSet[$Index]->Dates[] = $Reaction->DateInserted;
@@ -95,6 +109,14 @@ class ReactionModel extends Gdn_Model {
     }
   }
 
+  /**
+   * Return a list of reactions a user has received
+   * 
+   * @param int $ID
+   * @param enum $Type activity, comment, discussion
+   * @param int $UserID
+   * @return DataSet
+   */
   public function GetUserReaction($ID, $Type, $UserID) {
     return $this->SQL
             ->Select()
@@ -106,6 +128,13 @@ class ReactionModel extends Gdn_Model {
             ->FirstRow();
   }
   
+  /**
+   * Return the count of reactions received by a user
+   * 
+   * @param int $UserID
+   * @param int $ActionID
+   * @return DataSet
+   */
   public function GetUserReactionCount($UserID, $ActionID) {
     return $this->SQL
             ->Select()
@@ -115,6 +144,20 @@ class ReactionModel extends Gdn_Model {
             ->GetCount();
   }
   
+  /**
+   * Sets a users reaction against another user's content. A user can only react
+   * in one way to each unique piece of content. This function makes sure to
+   * enforce this rule
+   * 
+   * Events: AfterReactionSave
+   * 
+   * @param int $ID
+   * @param enum $Type activity, comment, discussion
+   * @param int $AuthorID
+   * @param int $UserID
+   * @param int $ActionID
+   * @return DataSet
+   */
   public function SetReaction($ID, $Type, $AuthorID, $UserID, $ActionID) {
     // clear the cache
     unset(self::$_Reactions[$Type . $ID]);

models/class.yagamodel.php

@@ -2,7 +2,7 @@
 /* Copyright 2013 Zachary Doll */
 
 /**
- * Cross table functions
+ * Cross table functions global to the Yaga application
  * 
  * Events:
  * 
@@ -11,17 +11,35 @@
  */
 
 class YagaModel extends Gdn_Model {
-  private static $_Reactions = array();
+  
-  private static $_Actions = NULL;
   /**
-   * Class constructor. Defines the related database table name.
+   * Used as a cache for reactions
+   * 
+   * @var array
+   */
+  private static $_Reactions = array();
+  
+  /**
+   * Used as a cache for available actions
+   * @var DataSet
+   */
+  private static $_Actions = NULL;
+  
+  /**
+   * Defines the related database table name.
    */
   public function __construct() {
     parent::__construct();
   }
 
+  /**
+   * Returns the total points a user has accumulated through out the application
+   * 
+   * @todo Move this to a calculated column
+   * @param int $UserID
+   * @return int
+   */
   public function GetUserPoints($UserID) {
-    // TODO: Move this to a calculated user column
     $Points = 0;
     
     // Reaction Points
@@ -54,133 +72,4 @@ class YagaModel extends Gdn_Model {
     
     return $Points;
   }
-  /**
-   * Returns a list of all available actions
-   */
-  public function GetActions() {
-    if(empty(self::$_Actions)) {
-      self::$_Actions = $this->SQL
-              ->Select()
-              ->From('Action')
-              ->OrderBy('ActionID')
-              ->Get()
-              ->Result();
-      //decho('Filling the action cache.');
-    }
-    return self::$_Actions;
-  }
-  
-  /**
-   * Returns data for a specific action
-   * @param int $ActionID
-   * @return dataset
-   */
-  public function GetActionID($ActionID) {
-    return $this->SQL
-                    ->Select()
-                    ->From('Action')
-                    ->Where('ActionID', $ActionID)
-                    ->Get()
-                    ->FirstRow();
-  }
-
-  /**
-   * Returns the reactions associated a specified ID.
-   * @param int $ID
-   * @param enum $Type is the kind of ID. Valid values are comment and discussion
-   */
-  public function GetReactions($ID, $Type) {
-    if(in_array($Type, array('discussion', 'comment', 'activity')) && $ID > 0) {
-      $ReactionSet = array();
-      if(empty(self::$_Reactions[$Type . $ID])) {
-        foreach($this->GetActions() as $Index => $Action) {
-          $ReactionSet[$Index]->ActionID = $Action->ActionID;
-          $ReactionSet[$Index]->Name = $Action->Name;
-          $ReactionSet[$Index]->Description = $Action->Description;
-          $ReactionSet[$Index]->Tooltip = $Action->Tooltip;
-          $ReactionSet[$Index]->CssClass = $Action->CssClass;
-          $ReactionSet[$Index]->AwardValue = $Action->AwardValue;
-          
-          $Reactions = $this->SQL
-                  ->Select('InsertUserID as UserID, DateInserted')
-                  ->From('Reaction')
-                  ->Where('ActionID', $Action->ActionID)
-                  ->Where('ParentID', $ID)
-                  ->Where('ParentType', $Type)
-                  ->Get()
-                  ->Result();               
-          //decho($Reaction);
-          foreach($Reactions as $Reaction) {
-            $ReactionSet[$Index]->UserIDs[] = $Reaction->UserID;
-            $ReactionSet[$Index]->Dates[] = $Reaction->DateInserted;
-          }
-        }
-
-        //decho('Filling in the reaction cache for ' . $Type . $ID);
-        self::$_Reactions[$Type . $ID] = $ReactionSet;
-      }
-      return self::$_Reactions[$Type . $ID];
-    }
-    else {
-      return NULL;
-    }
-  }
-
-  public function GetUserReaction($ID, $Type, $UserID) {
-    return $this->SQL
-            ->Select()
-            ->From('Reaction')
-            ->Where('ParentID', $ID)
-            ->Where('ParentType', $Type)
-            ->Where('InsertUserID', $UserID)
-            ->Get()
-            ->FirstRow();
-  }
-  
-  public function GetUserReactionCount($UserID, $ActionID) {
-    return $this->SQL
-            ->Select()
-            ->From('Reaction')
-            ->Where('ActionID', $ActionID)
-            ->Where('ParentAuthorID', $UserID)
-            ->GetCount();
-  }
-  
-  public function SetReaction($ID, $Type, $AuthorID, $UserID, $ActionID) {
-    // clear the cache
-    unset(self::$_Reactions[$Type . $ID]);
-
-    $CurrentReaction = $this->GetUserReaction($ID, $Type, $UserID);
-    if($CurrentReaction) {
-      if($ActionID == $CurrentReaction->ActionID) {
-        // remove the record
-        return $this->SQL->Delete('Reaction', array('ParentID' => $ID,
-                    'ParentType' => $Type,
-                    'InsertUserID' => $UserID,
-                    'ActionID' => $ActionID));
-      }
-      else {
-        // update the record
-        return $this->SQL
-              ->Update('Reaction')
-              ->Set('ActionID', $ActionID)
-              ->Set('DateInserted', date(DATE_ISO8601))
-              ->Where('ParentID', $ID)
-              ->Where('ParentType', $Type)
-              ->Where('InsertUserID', $UserID)
-              ->Put();
-      }
-    }
-    else {
-      // insert a record
-      return $this->SQL
-              ->Insert('Reaction',
-                      array('ActionID' => $ActionID,
-                      'ParentID' =>  $ID,
-                      'ParentType' => $Type,
-                      'ParentAuthorID' => $AuthorID,
-                      'InsertUserID' => $UserID,
-                      'DateInserted' => date(DATE_ISO8601)));
-    }
-  }
 }