PHPDoc is a standardized format for commenting on PHP code.
Using it allows for a more cohesive use of IDEs and documentation
generators with the AUR code.
Signed-off-by: canyonknight canyonkni...@gmail.com
---
web/lib/aur.inc.php | 231 +++-
1 file changed, 191 insertions(+), 40 deletions(-)
diff --git a/web/lib/aur.inc.php b/web/lib/aur.inc.php
index a23cd3e..93ae23b 100644
--- a/web/lib/aur.inc.php
+++ b/web/lib/aur.inc.php
@@ -16,8 +16,19 @@ include_once(version.inc.php);
include_once(acctfuncs.inc.php);
include_once(cachefuncs.inc.php);
-# see if the visitor is already logged in
-#
+/**
+ * Check if a visitor is logged in
+ *
+ * Query Sessions table with supplied cookie. Determine if the cookie is
valid
+ * or not. Unset the cookie if invalid or session timeout reached. Update the
+ * session timeout if it is still valid.
+ *
+ * @global array $_COOKIE User cookie values
+ * @global string $LOGIN_TIMEOUT Time until session times out
+ * @param \PDO $dbh Already established database connection
+ *
+ * @return void
+ */
function check_sid($dbh=NULL) {
global $_COOKIE;
global $LOGIN_TIMEOUT;
@@ -77,8 +88,11 @@ function check_sid($dbh=NULL) {
return;
}
-# Verify the supplied token matches the expected token for POST forms
-#
+/**
+ * Verify the supplied CSRF token matches expected token
+ *
+ * @return bool True if the CSRF token is the same as the cookie SID,
otherwise false
+ */
function check_token() {
if (isset($_POST['token'])) {
return ($_POST['token'] == $_COOKIE['AURSID']);
@@ -87,8 +101,13 @@ function check_token() {
}
}
-# verify that an email address looks like it is legitimate
-#
+/**
+ * Verify a user supplied e-mail against RFC 3696 and DNS records
+ *
+ * @param string $addy E-mail address being validated in f...@example.com
format
+ *
+ * @return bool True if e-mail passes validity checks, otherwise false
+ */
function valid_email($addy) {
// check against RFC 3696
if (filter_var($addy, FILTER_VALIDATE_EMAIL) === false) {
@@ -104,15 +123,23 @@ function valid_email($addy) {
return true;
}
-# generate a (hopefully) unique session id
-#
+/**
+ * Generate a unique session ID
+ *
+ * @return string MD5 hash of the concatenated user IP, random number, and
current time
+ */
function new_sid() {
return md5($_SERVER['REMOTE_ADDR'] . uniqid(mt_rand(), true));
}
-
-# obtain the username if given their Users.ID
-#
+/**
+ * Determine the user's username in the database using a user ID
+ *
+ * @param string $id User's ID
+ * @param \PDO $dbh Already established database connection
+ *
+ * @return string Username if it exists, otherwise None
+ */
function username_from_id($id=, $dbh=NULL) {
if (!$id) {
return ;
@@ -130,9 +157,14 @@ function username_from_id($id=, $dbh=NULL) {
return $row[0];
}
-
-# obtain the username if given their current SID
-#
+/**
+ * Determine the user's username in the database using a session ID
+ *
+ * @param string $sid User's session ID
+ * @param \PDO $dbh Already established database connection
+ *
+ * @return string Username of the visitor
+ */
function username_from_sid($sid=, $dbh=NULL) {
if (!$sid) {
return ;
@@ -153,8 +185,14 @@ function username_from_sid($sid=, $dbh=NULL) {
return $row[0];
}
-# obtain the email address if given their current SID
-#
+/**
+ * Determine the user's e-mail address in the database using a session ID
+ *
+ * @param string $sid User's session ID
+ * @param \PDO $dbh Already established database connection
+ *
+ * @return string User's e-mail address as given during registration
+ */
function email_from_sid($sid=, $dbh=NULL) {
if (!$sid) {
return ;
@@ -175,9 +213,14 @@ function email_from_sid($sid=, $dbh=NULL) {
return $row[0];
}
-# obtain the account type if given their current SID
-# Return either , User, Trusted User, Developer
-#
+/**
+ * Determine the user's account type in the database using a session ID
+ *
+ * @param string $sid User's session ID
+ * @param \PDO $dbh Already established database connection
+ *
+ * @return string Account type of user (User, Trusted User, or Developer)
+ */
function account_from_sid($sid=, $dbh=NULL) {
if (!$sid) {
return ;
@@ -199,8 +242,14 @@ function account_from_sid($sid=, $dbh=NULL) {
return $row[0];
}
-# obtain the Users.ID if given their current SID
-#
+/**
+ * Determine the user's ID in the database using a session ID
+ *
+ * @param string $sid User's session ID
+ * @param \PDO $dbh Already established database connection
+ *
+ * @return string|int The user's name, 0 on query failure
+ */
function uid_from_sid($sid=, $dbh=NULL) {
if (!$sid) {
return ;
@@ -221,8 +270,11 @@ function uid_from_sid($sid=, $dbh=NULL) {
return $row[0];
}
-# connect to the database
