Skip to content

Q
question2answer
Commit b1d9d397 by Scott Vivian
Options

DocBlock comments in qa-db.php

parent 1ac995e0
Showing with 112 additions and 122 deletions
qa-include/Q2A/Util/Usage.php
......@@ -18,7 +18,7 @@ class Q2A_Util_Usage
private $databaseQueryLog;
/**
* Initialize the counts of resource usage
* Initialize the counts of resource usage.
*/
public function __construct()
{
......@@ -30,7 +30,7 @@ class Q2A_Util_Usage
}
/**
* Return an array representing the resource usage as of now
* Return an array representing the resource usage as of now.
*/
public function getCurrent()
{
......@@ -56,7 +56,7 @@ class Q2A_Util_Usage
}
/**
* Mark the beginning of a new stage of script execution and store usages accordingly
* Mark the beginning of a new stage of script execution and store usages accordingly.
*/
public function mark($stage)
{
......@@ -66,7 +66,7 @@ class Q2A_Util_Usage
}
/**
* Logs query and updates database usage stats
* Logs query and updates database usage stats.
*/
public function logDatabaseQuery($query, $usedtime, $gotrows, $gotcolumns)
{
......@@ -86,7 +86,7 @@ class Q2A_Util_Usage
}
/**
* Output an (ugly) block of HTML detailing all resource usage and database queries
* Output an (ugly) block of HTML detailing all resource usage and database queries.
*/
public function output()
{
......@@ -130,7 +130,7 @@ class Q2A_Util_Usage
/**
* Return the difference between two resource usage arrays, as an array
* Return the difference between two resource usage arrays, as an array.
*/
private function delta($oldusage, $newusage)
{
......@@ -143,7 +143,7 @@ class Q2A_Util_Usage
}
/**
* Return HTML to represent the resource $usage, showing appropriate proportions of $totalusage
* Return HTML to represent the resource $usage, showing appropriate proportions of $totalusage.
*/
private function line($stage, $usage, $totalusage)
{
......
qa-include/qa-db.php
......@@ -30,11 +30,11 @@
}
/**
* Indicates to the Q2A database layer that database connections are permitted fro this point forwards
* (before this point, some plugins may not have had a chance to override some database access functions).
*/
function qa_db_allow_connect()
/*
Indicates to the Q2A database layer that database connections are permitted fro this point forwards
(before this point, some plugins may not have had a chance to override some database access functions)
*/
{
if (qa_to_override(__FUNCTION__)) { $args=func_get_args(); return qa_call_override(__FUNCTION__, $args); }
......@@ -44,11 +44,11 @@
}
/**
* Connect to the Q2A database, select the right database, optionally install the $failhandler (and call it if necessary).
* Uses mysqli as of Q2A 1.7.
*/
function qa_db_connect($failhandler=null)
/*
Connect to the Q2A database, select the right database, optionally install the $failhandler (and call it if necessary).
Uses mysqli as of Q2A 1.6.4.
*/
{
if (qa_to_override(__FUNCTION__)) { $args=func_get_args(); return qa_call_override(__FUNCTION__, $args); }
......@@ -74,13 +74,9 @@
if ($conn_error)
qa_db_fail_error('connect', $db->connect_errno, $conn_error);
/*
From Q2A 1.5, we explicitly set the character encoding of the MySQL connection, instead of
using lots of "SELECT BINARY col"-style queries. Testing showed that overhead is minimal,
so this seems worth trading off against the benefit of more straightforward queries,
especially for plugin developers.
*/
// From Q2A 1.5, we explicitly set the character encoding of the MySQL connection, instead of using lots of "SELECT BINARY col"-style queries.
// Testing showed that overhead is minimal, so this seems worth trading off against the benefit of more straightforward queries, especially
// for plugin developers.
if (!$db->set_charset('utf8'))
qa_db_fail_error('set_charset', $db->errno, $db->error);
......@@ -90,10 +86,10 @@
}
/**
* If a DB error occurs, call the installed fail handler (if any) otherwise report error and exit immediately.
*/
function qa_db_fail_error($type, $errno=null, $error=null, $query=null)
/*
If a DB error occurs, call the installed fail handler (if any) otherwise report error and exit immediately
*/
{
if (qa_to_override(__FUNCTION__)) { $args=func_get_args(); return qa_call_override(__FUNCTION__, $args); }
......@@ -111,10 +107,10 @@
}
/**
* Return the current connection to the Q2A database, connecting if necessary and $connect is true.
*/
function qa_db_connection($connect=true)
/*
Return the current connection to the Q2A database, connecting if necessary and $connect is true
*/
{
if (qa_to_override(__FUNCTION__)) { $args=func_get_args(); return qa_call_override(__FUNCTION__, $args); }
......@@ -131,10 +127,10 @@
}
/**
* Disconnect from the Q2A database.
*/
function qa_db_disconnect()
/*
Disconnect from the Q2A database
*/
{
if (qa_to_override(__FUNCTION__)) { $args=func_get_args(); return qa_call_override(__FUNCTION__, $args); }
......@@ -153,11 +149,11 @@
}
/**
* Run the raw $query, call the global failure handler if necessary, otherwise return the result resource.
* If appropriate, also track the resources used by database queries, and the queries themselves, for performance debugging.
*/
function qa_db_query_raw($query)
/*
Run the raw $query, call the global failure handler if necessary, otherwise return the result resource.
If appropriate, also track the resources used by database queries, and the queries themselves, for performance debugging.
*/
{
if (qa_to_override(__FUNCTION__)) { $args=func_get_args(); return qa_call_override(__FUNCTION__, $args); }
......@@ -192,10 +188,10 @@
}
/**
* Lower-level function to execute a query, which automatically retries if there is a MySQL deadlock error.
*/
function qa_db_query_execute($query)
/*
Lower-level function to execute a query, which automatically retries if there is a MySQL deadlock error
*/
{
if (qa_to_override(__FUNCTION__)) { $args=func_get_args(); return qa_call_override(__FUNCTION__, $args); }
......@@ -214,10 +210,10 @@
}
/**
* Return $string escaped for use in queries to the Q2A database (to which a connection must have been made).
*/
function qa_db_escape_string($string)
/*
Return $string escaped for use in queries to the Q2A database (to which a connection must have been made)
*/
{
if (qa_to_override(__FUNCTION__)) { $args=func_get_args(); return qa_call_override(__FUNCTION__, $args); }
......@@ -226,11 +222,11 @@
}
/**
* Return $argument escaped for MySQL. Add quotes around it if $alwaysquote is true or it's not numeric.
* If $argument is an array, return a comma-separated list of escaped elements, with or without $arraybrackets.
*/
function qa_db_argument_to_mysql($argument, $alwaysquote, $arraybrackets=false)
/*
Return $argument escaped for MySQL. Add quotes around it if $alwaysquote is true or it's not numeric.
If $argument is an array, return a comma-separated list of escaped elements, with or without $arraybrackets.
*/
{
if (is_array($argument)) {
$parts=array();
......@@ -257,10 +253,10 @@
}
/**
* Return the full name (with prefix) of database table $rawname, usually if it used after a ^ symbol.
*/
function qa_db_add_table_prefix($rawname)
/*
Return the full name (with prefix) of database table $rawname, usually if it used after a ^ symbol
*/
{
if (qa_to_override(__FUNCTION__)) { $args=func_get_args(); return qa_call_override(__FUNCTION__, $args); }
......@@ -287,23 +283,23 @@
}
/**
* Callback function to add table prefixes, as used in qa_db_apply_sub().
*/
function qa_db_prefix_callback($matches)
/*
Callback function to add table prefixes, as used in qa_db_apply_sub()
*/
{
return qa_db_add_table_prefix($matches[1]);
}
/**
* Substitute ^, $ and # symbols in $query. ^ symbols are replaced with the table prefix set in qa-config.php.
* $ and # symbols are replaced in order by the corresponding element in $arguments (if the element is an array,
* it is converted recursively into comma-separated list). Each element in $arguments is escaped.
* $ is replaced by the argument in quotes (even if it's a number), # only adds quotes if the argument is non-numeric.
* It's important to use $ when matching a textual column since MySQL won't use indexes to compare text against numbers.
*/
function qa_db_apply_sub($query, $arguments)
/*
Substitute ^, $ and # symbols in $query. ^ symbols are replaced with the table prefix set in qa-config.php.
$ and # symbols are replaced in order by the corresponding element in $arguments (if the element is an array,
it is converted recursively into comma-separated list). Each element in $arguments is escaped.
$ is replaced by the argument in quotes (even if it's a number), # only adds quotes if the argument is non-numeric.
It's important to use $ when matching a textual column since MySQL won't use indexes to compare text against numbers.
*/
{
$query = preg_replace_callback('/\^([A-Za-z_0-9]+)/', 'qa_db_prefix_callback', $query);
......@@ -338,10 +334,10 @@
}
/**
* Run $query after substituting ^, # and $ symbols, and return the result resource (or call fail handler).
*/
function qa_db_query_sub($query) // arguments for substitution retrieved using func_get_args()
/*
Run $query after substituting ^, # and $ symbols, and return the result resource (or call fail handler)
*/
{
$funcargs=func_get_args();
......@@ -349,59 +345,59 @@
}
/**
* Return the value of the auto-increment column for the last inserted row.
*/
function qa_db_last_insert_id()
/*
Return the value of the auto-increment column for the last inserted row
*/
{
$db = qa_db_connection();
return $db->insert_id;
}
/**
* Does what it says on the tin.
*/
function qa_db_affected_rows()
/*
Does what it says on the tin
*/
{
$db = qa_db_connection();
return $db->affected_rows;
}
/**
* For the previous INSERT ... ON DUPLICATE KEY UPDATE query, return whether an insert operation took place.
*/
function qa_db_insert_on_duplicate_inserted()
/*
For the previous INSERT ... ON DUPLICATE KEY UPDATE query, return whether an insert operation took place
*/
{
return (qa_db_affected_rows() == 1);
}
/**
* Return a random integer (as a string) for use in a BIGINT column.
* Actual limit is 18,446,744,073,709,551,615 - we aim for 18,446,743,999,999,999,999.
*/
function qa_db_random_bigint()
/*
Return a random integer (as a string) for use in a BIGINT column.
Actual limit is 18,446,744,073,709,551,615 - we aim for 18,446,743,999,999,999,999
*/
{
return sprintf('%d%06d%06d', mt_rand(1,18446743), mt_rand(0,999999), mt_rand(0,999999));
}
/**
* Return an array of the names of all tables in the Q2A database, converted to lower case.
* No longer used by Q2A and shouldn't be needed.
*/
function qa_db_list_tables_lc()
/*
Return an array of the names of all tables in the Q2A database, converted to lower case.
No longer used by Q2A and shouldn't be needed.
*/
{
return array_map('strtolower', qa_db_list_tables());
}
/**
* Return an array of the names of all tables in the Q2A database.
*/
function qa_db_list_tables()
/*
Return an array of the names of all tables in the Q2A database
*/
{
return qa_db_read_all_values(qa_db_query_raw('SHOW TABLES'));
}
......@@ -453,10 +449,10 @@
*/
/**
* Return the data specified by a single $selectspec - see long comment above.
*/
function qa_db_single_select($selectspec)
/*
Return the data specified by a single $selectspec - see long comment above.
*/
{
$query = 'SELECT ';
......@@ -474,11 +470,11 @@
}
/**
* Return the data specified by each element of $selectspecs, where the keys of the
* returned array match the keys of the supplied $selectspecs array. See long comment above.
*/
function qa_db_multi_select($selectspecs)
/*
Return the data specified by each element of $selectspecs, where the keys of the
returned array match the keys of the supplied $selectspecs array. See long comment above.
*/
{
if (!count($selectspecs))
return array();
......@@ -585,10 +581,10 @@
}
/**
* Post-process $outresult according to $selectspec, applying 'sortasc', 'sortdesc', 'arrayvalue' and 'single'.
*/
function qa_db_post_select(&$outresult, $selectspec)
/*
Post-process $outresult according to $selectspec, applying 'sortasc', 'sortdesc', 'arrayvalue' and 'single'
*/
{
// PHP's sorting algorithm is not 'stable', so we use '_order_' element to keep stability.
// By contrast, MySQL's ORDER BY does seem to give the results in a reliable order.
......@@ -628,12 +624,12 @@
}
/**
* Return the full results from the $result resource as an array. The key of each element in the returned array
* is from column $key if specified, otherwise it's integer. The value of each element in the returned array
* is from column $value if specified, otherwise it's a named array of all columns, given an array of arrays.
*/
function qa_db_read_all_assoc($result, $key=null, $value=null)
/*
Return the full results from the $result resource as an array. The key of each element in the returned array
is from column $key if specified, otherwise it's integer. The value of each element in the returned array
is from column $value if specified, otherwise it's a named array of all columns, given an array of arrays.
*/
{
if (!($result instanceof mysqli_result))
qa_fatal_error('Reading all assoc from invalid result');
......@@ -651,11 +647,11 @@
}
/**
* Return the first row from the $result resource as an array of [column name] => [column value].
* If there's no first row, throw a fatal error unless $allowempty is true.
*/
function qa_db_read_one_assoc($result, $allowempty=false)
/*
Return the first row from the $result resource as an array of [column name] => [column value].
If there's no first row, throw a fatal error unless $allowempty is true.
*/
{
if (!($result instanceof mysqli_result))
qa_fatal_error('Reading one assoc from invalid result');
......@@ -672,10 +668,10 @@
}
/**
* Return a numbered array containing the first (and presumably only) column from the $result resource.
*/
function qa_db_read_all_values($result)
/*
Return a numbered array containing the first (and presumably only) column from the $result resource
*/
{
if (!($result instanceof mysqli_result))
qa_fatal_error('Reading column from invalid result');
......@@ -689,11 +685,11 @@
}
/**
* Return the first column of the first row (and presumably only cell) from the $result resource.
* If there's no first row, throw a fatal error unless $allowempty is true.
*/
function qa_db_read_one_value($result, $allowempty=false)
/*
Return the first column of the first row (and presumably only cell) from the $result resource.
If there's no first row, throw a fatal error unless $allowempty is true.
*/
{
if (!($result instanceof mysqli_result))
qa_fatal_error('Reading one value from invalid result');
......@@ -710,11 +706,11 @@
}
/**
* Suspend the updating of counts (of many different types) in the database, to save time when making a lot of changes
* if $suspend is true, otherwise reinstate it. A counter is kept to allow multiple calls.
*/
function qa_suspend_update_counts($suspend=true)
/*
Suspend the updating of counts (of many different types) in the database, to save time when making a lot of changes
if $suspend is true, otherwise reinstate it. A counter is kept to allow multiple calls.
*/
{
global $qa_update_counts_suspended;
......@@ -722,17 +718,12 @@
}
/**
* Returns whether counts should currently be updated (i.e. if count updating has not been suspended).
*/
function qa_should_update_counts()
/*
Returns whether counts should currently be updated (i.e. if count updating has not been suspended)
*/
{
global $qa_update_counts_suspended;
return ($qa_update_counts_suspended <= 0);
}
/*
Omit PHP closing tag to help avoid accidental output
*/
\ No newline at end of file
qa-include/qa-util-debug.php
......@@ -23,7 +23,7 @@ function qa_usage_get()
function qa_usage_delta($oldusage, $newusage)
{
// equivalent function is now private
return null;
return array();
}
function qa_usage_mark($stage)
......@@ -35,7 +35,7 @@ function qa_usage_mark($stage)
function qa_usage_line($stage, $usage, $totalusage)
{
// equivalent function is now private
return null;
return '';
}
function qa_usage_output()
......
Markdown is supported
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