[aur-dev] [PATCH] aur.inc.php: Document all functions using PHPDoc format
canyonknight
canyonknight at gmail.com
Sat Sep 22 15:21:48 EDT 2012
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 <canyonknight at 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 foo at 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
-#
+/**
+ * Establish a connection with a database using PDO
+ *
+ * @return \PDO A database connection
+ */
function db_connect() {
try {
$dbh = new PDO(AUR_db_DSN_prefix . ":" . AUR_db_host . ";dbname=" . AUR_db_name, AUR_db_user, AUR_db_pass);
@@ -236,8 +288,15 @@ function db_connect() {
return $dbh;
}
-# common header
-#
+/**
+ * Common AUR header displayed on all pages
+ *
+ * @global string $LANG Language selected by the visitor
+ * @global array $SUPPORTED_LANGS Languages that are supported by the AUR
+ * @param string $title Name of the AUR page to be displayed on browser
+ *
+ * @return void
+ */
function html_header($title="") {
global $LANG;
global $SUPPORTED_LANGS;
@@ -248,16 +307,27 @@ function html_header($title="") {
return;
}
-
-# common footer
-#
+/**
+ * Common AUR footer displayed on all pages
+ *
+ * @param string $ver The AUR version
+ *
+ * @return void
+ */
function html_footer($ver="") {
include('footer.php');
return;
}
-# check to see if the user can submit a package
-#
+/**
+ * Determine if a user has permission to submit a package
+ *
+ * @param string $name Name of the package to be submitted
+ * @param string $sid User's session ID
+ * @param \PDO $dbh Already established database connection
+ *
+ * @return int 0 if the user can't submit, 1 if the user can submit
+ */
function can_submit_pkg($name="", $sid="", $dbh=NULL) {
if (!$name || !$sid) {return 0;}
if(!$dbh) {
@@ -280,8 +350,13 @@ function can_submit_pkg($name="", $sid="", $dbh=NULL) {
return 0;
}
-# recursive delete directory
-#
+/**
+ * Recursively delete a directory
+ *
+ * @param string $dirname Name of the directory to be removed
+ *
+ * @return void
+ */
function rm_tree($dirname) {
if (empty($dirname) || !is_dir($dirname)) return;
@@ -302,8 +377,14 @@ function rm_tree($dirname) {
return;
}
-# obtain the uid given a Users.Username
-#
+ /**
+ * Determine the user's ID in the database using a username
+ *
+ * @param string $username The username of an account
+ * @param \PDO $dbh Already established database connection
+ *
+ * @return string Return user ID if exists for username, otherwise "None"
+ */
function uid_from_username($username="", $dbh=NULL) {
if (!$username) {
return "";
@@ -321,8 +402,14 @@ function uid_from_username($username="", $dbh=NULL) {
return $row[0];
}
-# obtain the uid given a Users.Email
-#
+/**
+ * Determine the user's ID in the database using an e-mail address
+ *
+ * @param string $email An e-mail address in foo at example.com format
+ * @param \PDO $dbh Already established database connection
+ *
+ * @return string The user's ID
+ */
function uid_from_email($email="", $dbh=NULL) {
if (!$email) {
return "";
@@ -340,8 +427,11 @@ function uid_from_email($email="", $dbh=NULL) {
return $row[0];
}
-# check user privileges
-#
+/**
+ * Determine if a user has TU or Developer privileges
+ *
+ * @return bool Return true if the user is a TU or developer, otherwise false
+ */
function check_user_privileges() {
$type = account_from_sid($_COOKIE['AURSID']);
return ($type == 'Trusted User' || $type == 'Developer');
@@ -353,10 +443,10 @@ function check_user_privileges() {
* Makes a clean string of variables for use in URLs based on current $_GET and
* list of values to edit/add to that. Any empty variables are discarded.
*
- * ex. print "http://example.com/test.php?" . mkurl("foo=bar&bar=baz")
+ * @example print "http://example.com/test.php?" . mkurl("foo=bar&bar=baz")
*
* @param string $append string of variables and values formatted as in URLs
- * ex. mkurl("foo=bar&bar=baz")
+ *
* @return string clean string of variables to append to URL, urlencoded
*/
function mkurl($append) {
@@ -381,6 +471,14 @@ function mkurl($append) {
return substr($out, 5);
}
+/**
+ * Determine a user's salt from the database
+ *
+ * @param string $user_id The user ID of the user trying to log in
+ * @param \PDO $dbh Already established database connection
+ *
+ * @return string|void Return the salt for the requested user, otherwise void
+ */
function get_salt($user_id, $dbh=NULL) {
if(!$dbh) {
$dbh = db_connect();
@@ -394,6 +492,13 @@ function get_salt($user_id, $dbh=NULL) {
return;
}
+/**
+ * Save a user's salted password in the database
+ *
+ * @param string $user_id The user ID of the user who is salting their password
+ * @param string $passwd The password of the user logging in
+ * @param \PDO $dbh Already established database connection
+ */
function save_salt($user_id, $passwd, $dbh=NULL) {
if(!$dbh) {
$dbh = db_connect();
@@ -405,10 +510,23 @@ function save_salt($user_id, $passwd, $dbh=NULL) {
$result = $dbh->exec($q);
}
+/**
+ * Generate a string to be used for salting passwords
+ *
+ * @return string MD5 hash of concatenated random number and current time
+ */
function generate_salt() {
return md5(uniqid(mt_rand(), true));
}
+/**
+ * Combine salt and password to form a hash
+ *
+ * @param string $passwd User plaintext password
+ * @param string $salt MD5 hash to be used as user salt
+ *
+ * @return string The MD5 hash of the concatenated salt and user password
+ */
function salted_hash($passwd, $salt) {
if (strlen($salt) != 32) {
trigger_error('Salt does not look like an md5 hash', E_USER_WARNING);
@@ -416,6 +534,13 @@ function salted_hash($passwd, $salt) {
return md5($salt . $passwd);
}
+/**
+ * Process submitted comments so any links can be followed
+ *
+ * @param string $comment Raw user submitted package comment
+ *
+ * @return string User comment with links printed in HTML
+ */
function parse_comment($comment) {
$url_pattern = '/(\b(?:https?|ftp):\/\/[\w\/\#~:.?+=&%@!\-;,]+?' .
'(?=[.:?\-;,]*(?:[^\w\/\#~:.?+=&%@!\-;,]|$)))/iS';
@@ -439,6 +564,11 @@ function parse_comment($comment) {
return $html;
}
+/**
+ * Wrapper for beginning a database transaction
+ *
+ * @param \PDO $dbh Already established database connection
+ */
function begin_atomic_commit($dbh=NULL) {
if(!$dbh) {
$dbh = db_connect();
@@ -446,6 +576,11 @@ function begin_atomic_commit($dbh=NULL) {
$dbh->beginTransaction();
}
+/**
+ * Wrapper for committing a database transaction
+ *
+ * @param \PDO $dbh Already established database connection
+ */
function end_atomic_commit($dbh=NULL) {
if(!$dbh) {
$dbh = db_connect();
@@ -453,6 +588,14 @@ function end_atomic_commit($dbh=NULL) {
$dbh->commit();
}
+/**
+ *
+ * Determine the row ID for the most recently insterted row
+ *
+ * @param \PDO $dbh Already established database connection
+ *
+ * @return string The ID of the last inserted row
+ */
function last_insert_id($dbh=NULL) {
if(!$dbh) {
$dbh = db_connect();
@@ -460,6 +603,14 @@ function last_insert_id($dbh=NULL) {
return $dbh->lastInsertId();
}
+/**
+ * Determine package information for latest package
+ *
+ * @param int $numpkgs Number of packages to get information on
+ * @param \PDO $dbh Already established database connection
+ *
+ * @return array $packages Package info for the specified number of recent packages
+ */
function latest_pkgs($numpkgs, $dbh=NULL) {
if(!$dbh) {
$dbh = db_connect();
--
1.7.12.1
More information about the aur-dev
mailing list