From e3b096d55722bdac9100646b096503eb606ef735 Mon Sep 17 00:00:00 2001 From: Zachary Doll Date: Tue, 12 Nov 2013 10:05:27 -0600 Subject: [PATCH] Document models and remove redundant code in yagamodel --- models/class.actionmodel.php | 31 ++++++- models/class.badgemodel.php | 75 ++++++++++++++-- models/class.reactionmodel.php | 67 +++++++++++--- models/class.yagamodel.php | 157 +++++---------------------------- 4 files changed, 172 insertions(+), 158 deletions(-) diff --git a/models/class.actionmodel.php b/models/class.actionmodel.php index 0f0228b..6954e2d 100644 --- a/models/class.actionmodel.php +++ b/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)); diff --git a/models/class.badgemodel.php b/models/class.badgemodel.php index 0bd2699..e889569 100644 --- a/models/class.badgemodel.php +++ b/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() diff --git a/models/class.reactionmodel.php b/models/class.reactionmodel.php index cfd3c10..0163a85 100644 --- a/models/class.reactionmodel.php +++ b/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(); - //decho($Reaction); + ->Result(); + 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]); diff --git a/models/class.yagamodel.php b/models/class.yagamodel.php index a209ca4..1c42c52 100644 --- a/models/class.yagamodel.php +++ b/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))); - } - } } \ No newline at end of file