Skip to content
GitLab
Commit bad31ada authored by canyonknight's avatar canyonknight Committed by Lukas Fleischer
Browse files

aur.inc.php: Document all functions using PHPDoc format 



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: default avatarcanyonknight <canyonknight@gmail.com>
Signed-off-by: default avatarLukas Fleischer <archlinux@cryptocrack.de>
parent fa147bda
Show whitespace changes
Inline Side-by-side
web/lib/aur.inc.php
View file @ bad31ada
......@@ -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@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@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();
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment