From 349b5f3f56f83d681fe6658c1a8475992dde9eea Mon Sep 17 00:00:00 2001 From: Frédéric Guillot Date: Sun, 27 Apr 2014 19:02:38 -0400 Subject: Add some phpdoc comments --- models/board.php | 2 +- models/project.php | 208 ++++++++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 200 insertions(+), 10 deletions(-) diff --git a/models/board.php b/models/board.php index 01c3e832..3229c44e 100644 --- a/models/board.php +++ b/models/board.php @@ -340,4 +340,4 @@ class Board extends Base $v->getErrors() ); } -} \ No newline at end of file +} diff --git a/models/project.php b/models/project.php index 8b7a2293..b9def0be 100644 --- a/models/project.php +++ b/models/project.php @@ -10,14 +10,51 @@ require_once __DIR__.'/task.php'; use \SimpleValidator\Validator; use \SimpleValidator\Validators; +/** + * Project model + * + * @package model + * @author Frederic Guillot + */ class Project extends Base { + /** + * SQL table name for projects + * + * @var string + */ const TABLE = 'projects'; + + /** + * SQL table name for users + * + * @var string + */ const TABLE_USERS = 'project_has_users'; + + /** + * Value for active project + * + * @var integer + */ const ACTIVE = 1; + + /** + * Value for inactive project + * + * @var integer + */ const INACTIVE = 0; - // Get a list of people that can by assigned for tasks + /** + * Get a list of people that can be assigned for tasks + * + * @access public + * @param integer $project_id Project id + * @param bool $prepend_unassigned Prepend the 'Unassigned' value + * @param bool $prepend_everybody Prepend the 'Everbody' value + * @return array + */ public function getUsersList($project_id, $prepend_unassigned = true, $prepend_everybody = false) { $allowed_users = $this->getAllowedUsers($project_id); @@ -38,7 +75,13 @@ class Project extends Base return $allowed_users; } - // Get a list of allowed people for a project + /** + * Get a list of allowed people for a project + * + * @access public + * @param integer $project_id Project id + * @return array + */ public function getAllowedUsers($project_id) { return $this->db @@ -49,7 +92,13 @@ class Project extends Base ->listing('user_id', 'username'); } - // Get allowed and not allowed users for a project + /** + * Get allowed and not allowed users for a project + * + * @access public + * @param integer $project_id Project id + * @return array + */ public function getAllUsers($project_id) { $users = array( @@ -72,7 +121,14 @@ class Project extends Base return $users; } - // Allow a specific user for a given project + /** + * Allow a specific user for a given project + * + * @access public + * @param integer $project_id Project id + * @param integer $user_id User id + * @return bool + */ public function allowUser($project_id, $user_id) { return $this->db @@ -80,7 +136,14 @@ class Project extends Base ->save(array('project_id' => $project_id, 'user_id' => $user_id)); } - // Revoke a specific user for a given project + /** + * Revoke a specific user for a given project + * + * @access public + * @param integer $project_id Project id + * @param integer $user_id User id + * @return bool + */ public function revokeUser($project_id, $user_id) { return $this->db @@ -90,7 +153,14 @@ class Project extends Base ->remove(); } - // Check if a specific user is allowed to access to a given project + /** + * Check if a specific user is allowed to access to a given project + * + * @access public + * @param integer $project_id Project id + * @param integer $user_id User id + * @return bool + */ public function isUserAllowed($project_id, $user_id) { // If there is nobody specified, everybody have access to the project @@ -118,21 +188,49 @@ class Project extends Base ->count(); } + /** + * Get a project by the id + * + * @access public + * @param integer $project_id Project id + * @return array + */ public function getById($project_id) { return $this->db->table(self::TABLE)->eq('id', $project_id)->findOne(); } + /** + * Fetch project data by using the token + * + * @access public + * @param string $token Token + * @return array + */ public function getByToken($token) { return $this->db->table(self::TABLE)->eq('token', $token)->findOne(); } + /** + * Return the first project from the database (no sorting) + * + * @access public + * @return array + */ public function getFirst() { return $this->db->table(self::TABLE)->findOne(); } + /** + * Get all projects, optionaly fetch stats for each project and can check users permissions + * + * @access public + * @param bool $fetch_stats If true, return metrics about each projects + * @param bool $check_permissions If true, remove projects not allowed for the current user + * @return array + */ public function getAll($fetch_stats = false, $check_permissions = false) { if (! $fetch_stats) { @@ -142,9 +240,9 @@ class Project extends Base $this->db->startTransaction(); $projects = $this->db - ->table(self::TABLE) - ->asc('name') - ->findAll(); + ->table(self::TABLE) + ->asc('name') + ->findAll(); $boardModel = new Board($this->db, $this->event); $taskModel = new Task($this->db, $this->event); @@ -176,6 +274,13 @@ class Project extends Base return $projects; } + /** + * Return the list of all projects + * + * @access public + * @param bool $prepend If true, prepend to the list the value 'None' + * @return array + */ public function getList($prepend = true) { if ($prepend) { @@ -185,6 +290,13 @@ class Project extends Base return $this->db->table(self::TABLE)->asc('name')->listing('id', 'name'); } + /** + * Get all projects with all its data for a given status + * + * @access public + * @param integer $status Proejct status: self::ACTIVE or self:INACTIVE + * @return array + */ public function getAllByStatus($status) { return $this->db @@ -194,6 +306,13 @@ class Project extends Base ->findAll(); } + /** + * Get a list of project by status + * + * @access public + * @param integer $status Proejct status: self::ACTIVE or self:INACTIVE + * @return array + */ public function getListByStatus($status) { return $this->db @@ -203,6 +322,13 @@ class Project extends Base ->listing('id', 'name'); } + /** + * Return the number of projects by status + * + * @access public + * @param integer $status Status: self::ACTIVE or self:INACTIVE + * @return integer + */ public function countByStatus($status) { return $this->db @@ -211,6 +337,14 @@ class Project extends Base ->count(); } + /** + * Return a list of projects for a given user + * + * @access public + * @param array $projects Project list: ['project_id' => 'project_name'] + * @param integer $user_id User id + * @return array + */ public function filterListByAccess(array $projects, $user_id) { foreach ($projects as $project_id => $project_name) { @@ -222,6 +356,13 @@ class Project extends Base return $projects; } + /** + * Create a project + * + * @access public + * @param array $values Form values + * @return integer Project id + */ public function create(array $values) { $this->db->startTransaction(); @@ -248,16 +389,37 @@ class Project extends Base return (int) $project_id; } + /** + * Update a project + * + * @access public + * @param array $values Form values + * @return bool + */ public function update(array $values) { return $this->db->table(self::TABLE)->eq('id', $values['id'])->save($values); } + /** + * Remove a project + * + * @access public + * @param integer $project_id Project id + * @return bool + */ public function remove($project_id) { return $this->db->table(self::TABLE)->eq('id', $project_id)->remove(); } + /** + * Enable a project + * + * @access public + * @param integer $project_id Project id + * @return bool + */ public function enable($project_id) { return $this->db @@ -266,6 +428,13 @@ class Project extends Base ->save(array('is_active' => 1)); } + /** + * Disable a project + * + * @access public + * @param integer $project_id Project id + * @return bool + */ public function disable($project_id) { return $this->db @@ -274,6 +443,13 @@ class Project extends Base ->save(array('is_active' => 0)); } + /** + * Validate project creation + * + * @access public + * @param array $array Form values + * @return array $valid, $errors [0] = Success or not, [1] = List of errors + */ public function validateCreation(array $values) { $v = new Validator($values, array( @@ -288,6 +464,13 @@ class Project extends Base ); } + /** + * Validate project modification + * + * @access public + * @param array $array Form values + * @return array $valid, $errors [0] = Success or not, [1] = List of errors + */ public function validateModification(array $values) { $v = new Validator($values, array( @@ -304,6 +487,13 @@ class Project extends Base ); } + /** + * Validate allowed users + * + * @access public + * @param array $array Form values + * @return array $valid, $errors [0] = Success or not, [1] = List of errors + */ public function validateUserAccess(array $values) { $v = new Validator($values, array( -- cgit v1.2.3