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
...@@ -16,8 +16,19 @@ include_once("version.inc.php"); ...@@ -16,8 +16,19 @@ include_once("version.inc.php");
include_once("acctfuncs.inc.php"); include_once("acctfuncs.inc.php");
include_once("cachefuncs.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) { function check_sid($dbh=NULL) {
global $_COOKIE; global $_COOKIE;
global $LOGIN_TIMEOUT; global $LOGIN_TIMEOUT;
...@@ -77,8 +88,11 @@ function check_sid($dbh=NULL) { ...@@ -77,8 +88,11 @@ function check_sid($dbh=NULL) {
return; 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() { function check_token() {
if (isset($_POST['token'])) { if (isset($_POST['token'])) {
return ($_POST['token'] == $_COOKIE['AURSID']); return ($_POST['token'] == $_COOKIE['AURSID']);
...@@ -87,8 +101,13 @@ function check_token() { ...@@ -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) { function valid_email($addy) {
// check against RFC 3696 // check against RFC 3696
if (filter_var($addy, FILTER_VALIDATE_EMAIL) === false) { if (filter_var($addy, FILTER_VALIDATE_EMAIL) === false) {
...@@ -104,15 +123,23 @@ function valid_email($addy) { ...@@ -104,15 +123,23 @@ function valid_email($addy) {
return true; 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() { function new_sid() {
return md5($_SERVER['REMOTE_ADDR'] . uniqid(mt_rand(), true)); 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) { function username_from_id($id="", $dbh=NULL) {
if (!$id) { if (!$id) {
return ""; return "";
...@@ -130,9 +157,14 @@ function username_from_id($id="", $dbh=NULL) { ...@@ -130,9 +157,14 @@ function username_from_id($id="", $dbh=NULL) {
return $row[0]; 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) { function username_from_sid($sid="", $dbh=NULL) {
if (!$sid) { if (!$sid) {
return ""; return "";
...@@ -153,8 +185,14 @@ function username_from_sid($sid="", $dbh=NULL) { ...@@ -153,8 +185,14 @@ function username_from_sid($sid="", $dbh=NULL) {
return $row[0]; 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) { function email_from_sid($sid="", $dbh=NULL) {
if (!$sid) { if (!$sid) {
return ""; return "";
...@@ -175,9 +213,14 @@ function email_from_sid($sid="", $dbh=NULL) { ...@@ -175,9 +213,14 @@ function email_from_sid($sid="", $dbh=NULL) {
return $row[0]; 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) { function account_from_sid($sid="", $dbh=NULL) {
if (!$sid) { if (!$sid) {
return ""; return "";
...@@ -199,8 +242,14 @@ function account_from_sid($sid="", $dbh=NULL) { ...@@ -199,8 +242,14 @@ function account_from_sid($sid="", $dbh=NULL) {
return $row[0]; 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) { function uid_from_sid($sid="", $dbh=NULL) {
if (!$sid) { if (!$sid) {
return ""; return "";
...@@ -221,8 +270,11 @@ function uid_from_sid($sid="", $dbh=NULL) { ...@@ -221,8 +270,11 @@ function uid_from_sid($sid="", $dbh=NULL) {
return $row[0]; return $row[0];
} }
# connect to the database /**
# * Establish a connection with a database using PDO
*
* @return \PDO A database connection
*/
function db_connect() { function db_connect() {
try { try {
$dbh = new PDO(AUR_db_DSN_prefix . ":" . AUR_db_host . ";dbname=" . AUR_db_name, AUR_db_user, AUR_db_pass); $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() { ...@@ -236,8 +288,15 @@ function db_connect() {
return $dbh; 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="") { function html_header($title="") {
global $LANG; global $LANG;
global $SUPPORTED_LANGS; global $SUPPORTED_LANGS;
...@@ -248,16 +307,27 @@ function html_header($title="") { ...@@ -248,16 +307,27 @@ function html_header($title="") {
return; return;
} }
/**
# common footer * Common AUR footer displayed on all pages
# *
* @param string $ver The AUR version
*
* @return void
*/
function html_footer($ver="") { function html_footer($ver="") {
include('footer.php'); include('footer.php');
return; 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) { function can_submit_pkg($name="", $sid="", $dbh=NULL) {
if (!$name || !$sid) {return 0;} if (!$name || !$sid) {return 0;}
if(!$dbh) { if(!$dbh) {
...@@ -280,8 +350,13 @@ function can_submit_pkg($name="", $sid="", $dbh=NULL) { ...@@ -280,8 +350,13 @@ function can_submit_pkg($name="", $sid="", $dbh=NULL) {
return 0; 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) { function rm_tree($dirname) {
if (empty($dirname) || !is_dir($dirname)) return; if (empty($dirname) || !is_dir($dirname)) return;
...@@ -302,8 +377,14 @@ function rm_tree($dirname) { ...@@ -302,8 +377,14 @@ function rm_tree($dirname) {
return; 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) { function uid_from_username($username="", $dbh=NULL) {
if (!$username) { if (!$username) {
return ""; return "";
...@@ -321,8 +402,14 @@ function uid_from_username($username="", $dbh=NULL) { ...@@ -321,8 +402,14 @@ function uid_from_username($username="", $dbh=NULL) {
return $row[0]; 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) { function uid_from_email($email="", $dbh=NULL) {
if (!$email) { if (!$email) {
return ""; return "";
...@@ -340,8 +427,11 @@ function uid_from_email($email="", $dbh=NULL) { ...@@ -340,8 +427,11 @@ function uid_from_email($email="", $dbh=NULL) {
return $row[0]; 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() { function check_user_privileges() {
$type = account_from_sid($_COOKIE['AURSID']); $type = account_from_sid($_COOKIE['AURSID']);
return ($type == 'Trusted User' || $type == 'Developer'); return ($type == 'Trusted User' || $type == 'Developer');
...@@ -353,10 +443,10 @@ function check_user_privileges() { ...@@ -353,10 +443,10 @@ function check_user_privileges() {
* Makes a clean string of variables for use in URLs based on current $_GET and * 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. * 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 * @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 * @return string clean string of variables to append to URL, urlencoded
*/ */
function mkurl($append) { function mkurl($append) {
...@@ -381,6 +471,14 @@ function mkurl($append) { ...@@ -381,6 +471,14 @@ function mkurl($append) {
return substr($out, 5); 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) { function get_salt($user_id, $dbh=NULL) {
if(!$dbh) { if(!$dbh) {
$dbh = db_connect(); $dbh = db_connect();
...@@ -394,6 +492,13 @@ function get_salt($user_id, $dbh=NULL) { ...@@ -394,6 +492,13 @@ function get_salt($user_id, $dbh=NULL) {
return; 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) { function save_salt($user_id, $passwd, $dbh=NULL) {
if(!$dbh) { if(!$dbh) {
$dbh = db_connect(); $dbh = db_connect();
...@@ -405,10 +510,23 @@ function save_salt($user_id, $passwd, $dbh=NULL) { ...@@ -405,10 +510,23 @@ function save_salt($user_id, $passwd, $dbh=NULL) {
$result = $dbh->exec($q); $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() { function generate_salt() {
return md5(uniqid(mt_rand(), true)); 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) { function salted_hash($passwd, $salt) {
if (strlen($salt) != 32) { if (strlen($salt) != 32) {
trigger_error('Salt does not look like an md5 hash', E_USER_WARNING); trigger_error('Salt does not look like an md5 hash', E_USER_WARNING);
...@@ -416,6 +534,13 @@ function salted_hash($passwd, $salt) { ...@@ -416,6 +534,13 @@ function salted_hash($passwd, $salt) {
return md5($salt . $passwd); 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) { function parse_comment($comment) {
$url_pattern = '/(\b(?:https?|ftp):\/\/[\w\/\#~:.?+=&%@!\-;,]+?' . $url_pattern = '/(\b(?:https?|ftp):\/\/[\w\/\#~:.?+=&%@!\-;,]+?' .
'(?=[.:?\-;,]*(?:[^\w\/\#~:.?+=&%@!\-;,]|$)))/iS'; '(?=[.:?\-;,]*(?:[^\w\/\#~:.?+=&%@!\-;,]|$)))/iS';
...@@ -439,6 +564,11 @@ function parse_comment($comment) { ...@@ -439,6 +564,11 @@ function parse_comment($comment) {
return $html; return $html;
} }
/**
* Wrapper for beginning a database transaction
*
* @param \PDO $dbh Already established database connection
*/
function begin_atomic_commit($dbh=NULL) { function begin_atomic_commit($dbh=NULL) {
if(!$dbh) { if(!$dbh) {
$dbh = db_connect(); $dbh = db_connect();
...@@ -446,6 +576,11 @@ function begin_atomic_commit($dbh=NULL) { ...@@ -446,6 +576,11 @@ function begin_atomic_commit($dbh=NULL) {
$dbh->beginTransaction(); $dbh->beginTransaction();
} }
/**
* Wrapper for committing a database transaction
*
* @param \PDO $dbh Already established database connection
*/
function end_atomic_commit($dbh=NULL) { function end_atomic_commit($dbh=NULL) {
if(!$dbh) { if(!$dbh) {
$dbh = db_connect(); $dbh = db_connect();
...@@ -453,6 +588,14 @@ function end_atomic_commit($dbh=NULL) { ...@@ -453,6 +588,14 @@ function end_atomic_commit($dbh=NULL) {
$dbh->commit(); $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) { function last_insert_id($dbh=NULL) {
if(!$dbh) { if(!$dbh) {
$dbh = db_connect(); $dbh = db_connect();
...@@ -460,6 +603,14 @@ function last_insert_id($dbh=NULL) { ...@@ -460,6 +603,14 @@ function last_insert_id($dbh=NULL) {
return $dbh->lastInsertId(); 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) { function latest_pkgs($numpkgs, $dbh=NULL) {
if(!$dbh) { if(!$dbh) {
$dbh = db_connect(); $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