Signed-off-by: canyonknight
---
web/lib/acctfuncs.inc.php | 351 +++++++++++++++++++++++++++++++++++-----------
1 file changed, 270 insertions(+), 81 deletions(-)
diff --git a/web/lib/acctfuncs.inc.php b/web/lib/acctfuncs.inc.php
index 8c96e6f..bce00f8 100644
--- a/web/lib/acctfuncs.inc.php
+++ b/web/lib/acctfuncs.inc.php
@@ -1,6 +1,12 @@
$new_sid, 'error' => $login_error);
}
-/*
- * Only checks if the name itself is valid
- * Longer or equal to USERNAME_MIN_LEN
- * Shorter or equal to USERNAME_MAX_LEN
- * Starts and ends with a letter or number
- * Contains at most ONE dot, hyphen, or underscore
- * Returns the username if it is valid
- * Returns nothing if it isn't valid
+/**
+ * Validate a username against a collection of rules
+ *
+ * The username must be longer or equal to USERNAME_MIN_LEN. It must be shorter
+ * or equal to USERNAME_MAX_LEN. It must start and end with either a letter or
+ * a number. It can contain one period, hypen, or underscore. Returns username
+ * if it meets all of those rules.
+ *
+ * @param string $user Username to validate
+ *
+ * @return string|void Return username if it meets criteria, otherwise void
*/
function valid_username($user) {
if (!empty($user)) {
@@ -472,9 +509,13 @@ function valid_username($user) {
return;
}
-/*
- * Checks if the username is valid and if it exists in the database
- * Returns the username ID or nothing
+/**
+ * Determine if a username exists in the database
+ *
+ * @param string $user Username to check in the database
+ * @param \PDO $dbh An already established database connection
+ *
+ * @return string|void Return user ID if in database, otherwise void
*/
function valid_user($user, $dbh=NULL) {
/* if ( $user = valid_username($user) ) { */
@@ -497,7 +538,14 @@ function valid_user($user, $dbh=NULL) {
return;
}
-# Check for any open proposals about a user. Used to prevent multiple proposals.
+/**
+ * Determine if a user already has a proposal open about themselves
+ *
+ * @param string $user Username to checkout for open proposal
+ * @param \PDO $dbh An already established database connection
+ *
+ * @return bool True if there is an open proposal about the user, otherwise false
+ */
function open_user_proposals($user, $dbh=NULL) {
if(!$dbh) {
$dbh = db_connect();
@@ -513,8 +561,17 @@ function open_user_proposals($user, $dbh=NULL) {
}
}
-# Creates a new trusted user proposal from entered agenda.
-# Optionally takes proposal about specific user. Length of vote set by submitter.
+/**
+ * Add a new Trusted User proposal to the database
+ *
+ * @param string $agenda The agenda of the vote
+ * @param string $user The use the vote is about
+ * @param int $votelength The length of time for the vote to last
+ * @param string $submitteruid The user ID of the individual who submitted the proposal
+ * @param \PDO $dbh An already established database connection
+ *
+ * @return void
+ */
function add_tu_proposal($agenda, $user, $votelength, $submitteruid, $dbh=NULL) {
if(!$dbh) {
$dbh = db_connect();
@@ -527,7 +584,15 @@ function add_tu_proposal($agenda, $user, $votelength, $submitteruid, $dbh=NULL)
$result = $dbh->exec($q);
}
-# Add a reset key for a specific user
+/**
+ * Add a reset key to the database for a specified user
+ *
+ * @param string $resetkey A password reset key to be stored in database
+ * @param string $uid The user ID to store the reset key for
+ * @param \PDO $dbh An already established database connection
+ *
+ * @return void
+ */
function create_resetkey($resetkey, $uid, $dbh=NULL) {
if(!$dbh) {
$dbh = db_connect();
@@ -538,7 +603,17 @@ function create_resetkey($resetkey, $uid, $dbh=NULL) {
$dbh->exec($q);
}
-# Change a password and save the salt only if reset key and email are correct
+/**
+ * Change a user's password in the database if reset key and e-mail are correct
+ *
+ * @param string $hash New MD5 hash of a user's password
+ * @param string $salt New salt for the user's password
+ * @param string $resetkey Code e-mailed to a user to reset a password
+ * @param string $email E-mail address of the user resetting their password
+ * @param \PDO $dbh An already established database connection
+ *
+ * @return string|void Redirect page if successful, otherwise return error message
+ */
function password_reset($hash, $salt, $resetkey, $email, $dbh=NULL) {
if(!$dbh) {
$dbh = db_connect();
@@ -561,6 +636,13 @@ function password_reset($hash, $salt, $resetkey, $email, $dbh=NULL) {
}
}
+/**
+ * Determine if the password is longer than the minimum length
+ *
+ * @param string $passwd The password to check
+ *
+ * @return bool True if longer than minimum length, otherwise false
+ */
function good_passwd($passwd) {
if ( strlen($passwd) >= PASSWD_MIN_LEN ) {
return true;
@@ -568,8 +650,14 @@ function good_passwd($passwd) {
return false;
}
-/* Verifies that the password is correct for the userID specified.
- * Returns true or false
+/**
+ * Determine if the password is correct and salt it if it hasn't been already
+ *
+ * @param string $userID The user ID to check the password against
+ * @param string $passwd The password the visitor sent
+ * @param \PDO $dbh An already established database connection
+ *
+ * @return bool True if password was correct and properly salted, otherwise false
*/
function valid_passwd($userID, $passwd, $dbh=NULL) {
if (!$dbh) {
@@ -613,16 +701,25 @@ function valid_passwd($userID, $passwd, $dbh=NULL) {
return false;
}
-/*
- * Checks if the PGP key fingerprint is valid (must be 40 hexadecimal digits).
+/**
+ * Determine if the PGP key fingerprint is valid (must be 40 hexadecimal digits)
+ *
+ * @param string $fingerprint PGP fingerprint to check if valid
+ *
+ * @return bool True if the fingerprint is 40 hexadecimal digits, otherwise false
*/
function valid_pgp_fingerprint($fingerprint) {
$fingerprint = str_replace(" ", "", $fingerprint);
return (strlen($fingerprint) == 40 && ctype_xdigit($fingerprint));
}
-/*
- * Is the user account suspended?
+/**
+ * Determine if the user account has been suspended
+ *
+ * @param string $id The ID of user to check if suspended
+ * @param \PDO $dbh An already established database connection
+ *
+ * @return bool True if the user is suspended, otherwise false
*/
function user_suspended($id, $dbh=NULL) {
if (!$dbh) {
@@ -642,8 +739,13 @@ function user_suspended($id, $dbh=NULL) {
return false;
}
-/*
- * This should be expanded to return something
+/**
+ * Delete a specified user account from the database
+ *
+ * @param int $id The user ID of the account to be deleted
+ * @param \PDO $dbh An already established database connection
+ *
+ * @return void
*/
function user_delete($id, $dbh=NULL) {
if (!$dbh) {
@@ -654,9 +756,13 @@ function user_delete($id, $dbh=NULL) {
return;
}
-/*
- * A different way of determining a user's privileges
- * rather than account_from_sid()
+/**
+ * Determine if a user is either a Trusted User or Developer
+ *
+ * @param string $id The ID of the user to check if privileged
+ * @param \PDO $dbh An already established database connection
+ *
+ * @return int|string Return 0 if un-privileged, "2" if Trusted User, "3" if Developer
*/
function user_is_privileged($id, $dbh=NULL) {
if (!$dbh) {
@@ -674,7 +780,14 @@ function user_is_privileged($id, $dbh=NULL) {
}
-# Remove session on logout
+/**
+ * Remove the session from the database on logout
+ *
+ * @param string $sid User's session ID
+ * @param \PDO $dbh An already established database connection
+ *
+ * @return void
+ */
function delete_session_id($sid, $dbh=NULL) {
if(!$dbh) {
$dbh = db_connect();
@@ -684,7 +797,14 @@ function delete_session_id($sid, $dbh=NULL) {
$dbh->query($q);
}
-# Clear out old expired sessions.
+/**
+ * Remove sessions from the database that have exceed the timeout
+ *
+ * @global int $LOGIN_TIMEOUT Time until session expires
+ * @param \PDO $dbh An already established database connection
+ *
+ * @return void
+ */
function clear_expired_sessions($dbh=NULL) {
global $LOGIN_TIMEOUT;
@@ -698,6 +818,15 @@ function clear_expired_sessions($dbh=NULL) {
return;
}
+/**
+ * Get account details for a specific user
+ *
+ * @param string $uid The User ID of account to get information for
+ * @param string $username The username of the account to get for
+ * @param \PDO $dbh An already established database connection
+ *
+ * @return array Account details for the specified user
+ */
function account_details($uid, $username, $dbh=NULL) {
if(!$dbh) {
$dbh = db_connect();
@@ -719,6 +848,15 @@ function account_details($uid, $username, $dbh=NULL) {
return $row;
}
+/**
+ * Determine if a user has already voted on a specific proposal
+ *
+ * @param string $voteid The ID of the Trusted User proposal
+ * @param string $uid The ID to check if the user already voted
+ * @param \PDO $dbh An already established database connection
+ *
+ * @return bool True if the user has already voted, otherwise false
+ */
function tu_voted($voteid, $uid, $dbh=NULL) {
if (!$dbh) {
$dbh = db_connect();
@@ -735,6 +873,14 @@ function tu_voted($voteid, $uid, $dbh=NULL) {
}
}
+/**
+ * Get all current Trusted User proposals from the database
+ *
+ * @param string $order Ascending or descending order for the proposal listing
+ * @param \PDO $dbh An already established database connection
+ *
+ * @return array The details for all current Trusted User proposals
+ */
function current_proposal_list($order, $dbh=NULL) {
if (!$dbh) {
$dbh = db_connect();
@@ -751,6 +897,15 @@ function current_proposal_list($order, $dbh=NULL) {
return $details;
}
+/**
+ * Get a subset of all past Trusted User proposals from the database
+ *
+ * @param string $order Ascending or descending order for the proposal listing
+ * @param string $lim The number of proposals to list with the offset
+ * @param \PDO $dbh An already established database connection
+ *
+ * @return array The details for the subset of past Trusted User proposals
+ */
function past_proposal_list($order, $lim, $dbh=NULL) {
if (!$dbh) {
$dbh = db_connect();
@@ -767,6 +922,13 @@ function past_proposal_list($order, $lim, $dbh=NULL) {
return $details;
}
+/**
+ * Determine the total number of Trusted User proposals
+ *
+ * @param \PDO $dbh An already established database connection
+ *
+ * @return string The total number of Trusted User proposals
+ */
function proposal_count($dbh=NULL) {
if (!$dbh) {
$dbh = db_connect();
@@ -779,6 +941,14 @@ function proposal_count($dbh=NULL) {
return $row[0];
}
+/**
+ * Get all details related to a specific vote from the database
+ *
+ * @param string $voteid The ID of the Trusted User proposal
+ * @param \PDO $dbh An already established database connection
+ *
+ * @return array All stored details for a specific vote
+ */
function vote_details($voteid, $dbh=NULL) {
if (!$dbh) {
$dbh = db_connect();
@@ -793,6 +963,14 @@ function vote_details($voteid, $dbh=NULL) {
return $row;
}
+/**
+ * Get an alphabetical list of users who voted for a proposal with HTML links
+ *
+ * @param string $voteid The ID of the Trusted User proposal
+ * @param \PDO $dbh An already established database connection
+ *
+ * @return array All users (and HTML links) who voted for a specific proposal
+ */
function voter_list($voteid, $dbh=NULL) {
if (!$dbh) {
$dbh = db_connect();
@@ -815,6 +993,17 @@ function voter_list($voteid, $dbh=NULL) {
return $whovoted;
}
+/**
+ * Cast a vote for a specific user proposal
+ *
+ * @param string $voteid The ID of the proposal being voted on
+ * @param string $uid The user ID of the individual voting
+ * @param string $vote Vote position, either "Yes", "No", or "Abstain"
+ * @param int $newtotal The total number of votes after the user has voted
+ * @param \PDO $dbh An already established database connection
+ *
+ * @return void
+ */
function cast_proposal_vote($voteid, $uid, $vote, $newtotal, $dbh=NULL) {
if (!$dbh) {
$dbh = db_connect();
--
1.7.12.1