Skip to content

Q
question2answer
Commit 6ca33b27 by pupi1985
Options

PHPDoc update in qa-db, util/image, util/sort and util/string

parent a4d750a5
Showing with 83 additions and 77 deletions
qa-include/qa-db.php
......@@ -19,6 +19,8 @@
More about this license: http://www.question2answer.org/license.php
*/
use Q2A\Database\DbResult;
if (!defined('QA_VERSION')) { // don't allow this page to be requested directly from browser
header('Location: ../');
exit;
......@@ -42,8 +44,8 @@ function qa_db_allow_connect()
* 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.
* @deprecated 1.9.0 Use DbConnection->connect() instead.
* @param null $failhandler
* @return mixed|void
* @param string|null $failhandler
* @return mixed
*/
function qa_db_connect($failhandler = null)
{
......@@ -56,7 +58,7 @@ function qa_db_connect($failhandler = null)
/**
* If a DB error occurs, call the installed fail handler (if any) otherwise report error and exit immediately.
* @deprecated 1.9.0 Use DbConnection->failError() instead.
* @param $type
* @param string $type
* @param int $errno
* @param string $error
* @param string $query
......@@ -105,8 +107,8 @@ function qa_db_disconnect()
* 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.
* @deprecated 1.9.0 Use DbConnection->query() instead.
* @param $query
* @return mixed
* @param string $query
* @return DbResult
*/
function qa_db_query_raw($query)
{
......@@ -119,8 +121,8 @@ function qa_db_query_raw($query)
/**
* Lower-level function to execute a query, which automatically retries if there is a MySQL deadlock error.
* @deprecated 1.9.0 Use DbConnection->query() instead.
* @param $query
* @return mixed
* @param string $query
* @return DbResult
*/
function qa_db_query_execute($query)
{
......@@ -133,8 +135,8 @@ function qa_db_query_execute($query)
/**
* Return $string escaped for use in queries to the Q2A database (to which a connection must have been made).
* @deprecated 1.9.0 No longer needed: parameters passed to DbConnection->query() are automatically escaped.
* @param $string
* @return mixed
* @param string $string
* @return string
*/
function qa_db_escape_string($string)
{
......@@ -151,8 +153,8 @@ function qa_db_escape_string($string)
* 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.
* @deprecated 1.9.0
* @param $argument
* @param $alwaysquote
* @param mixed|null $argument
* @param bool $alwaysquote
* @param bool $arraybrackets
* @return mixed|string
*/
......@@ -184,7 +186,7 @@ function qa_db_argument_to_mysql($argument, $alwaysquote, $arraybrackets = false
/**
* Return the full name (with prefix) of database table $rawname, usually if it used after a ^ symbol.
* @deprecated 1.9.0 Use DbConnection->addTablePrefix() instead.
* @param $rawname
* @param string $rawname
* @return string
*/
function qa_db_add_table_prefix($rawname)
......@@ -198,7 +200,7 @@ function qa_db_add_table_prefix($rawname)
/**
* Callback function to add table prefixes, as used in qa_db_apply_sub().
* @deprecated 1.9.0 No longer needed.
* @param $matches
* @param array $matches
* @return string
*/
function qa_db_prefix_callback($matches)
......@@ -214,8 +216,8 @@ function qa_db_prefix_callback($matches)
* $ 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.
* @deprecated 1.9.0 Use DbConnection->applyTableSub() instead.
* @param $query
* @param $arguments
* @param string $query
* @param array $arguments
* @return mixed
*/
function qa_db_apply_sub($query, $arguments)
......@@ -258,7 +260,7 @@ function qa_db_apply_sub($query, $arguments)
* Run $query after substituting ^, # and $ symbols, and return the result resource (or call fail handler).
* @deprecated 1.9.0 Use DbConnection->query() instead.
* @param string $query
* @return mixed
* @return DbResult
*/
function qa_db_query_sub($query) // arguments for substitution retrieved using func_get_args()
{
......@@ -266,13 +268,14 @@ function qa_db_query_sub($query) // arguments for substitution retrieved using f
return qa_service('database')->query($query, $params);
}
/**
* Run $query after substituting ^, # and $ symbols, and return the result resource (or call fail handler).
* Query parameters are passed as an array.
* @deprecated 1.9.0 Use DbConnection->query() instead.
* @param string $query
* @param array $params
* @return mixed
* @return DbResult
*/
function qa_db_query_sub_params($query, $params)
{
......@@ -283,7 +286,7 @@ function qa_db_query_sub_params($query, $params)
/**
* Return the number of rows in $result. (Simple wrapper for mysqli_result::num_rows.)
* @deprecated 1.9.0 Use DbResult->affectedRows() instead.
* @param $result
* @param DbResult|mysqli_result $result
* @return int
*/
function qa_db_num_rows($result)
......@@ -303,6 +306,7 @@ function qa_db_num_rows($result)
/**
* Return the value of the auto-increment column for the last inserted row.
* @deprecated 1.9.0 Use DbConnection->lastInsertId() instead.
* @return string
*/
function qa_db_last_insert_id()
{
......@@ -313,6 +317,7 @@ function qa_db_last_insert_id()
/**
* Return the number of rows affected by the last query.
* @deprecated 1.9.0 Use DbResult->affectedRows() instead.
* @return int
*/
function qa_db_affected_rows()
{
......@@ -324,16 +329,18 @@ function qa_db_affected_rows()
/**
* For the previous INSERT ... ON DUPLICATE KEY UPDATE query, return whether an insert operation took place.
* @deprecated 1.9.0 Use DbResult->affectedRows() instead.
* @return bool
*/
function qa_db_insert_on_duplicate_inserted()
{
return (qa_db_affected_rows() == 1);
return false;
}
/**
* 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 string
*/
function qa_db_random_bigint()
{
......@@ -344,6 +351,7 @@ function qa_db_random_bigint()
/**
* 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
*/
function qa_db_list_tables_lc()
{
......@@ -423,8 +431,8 @@ function qa_db_list_tables($onlyTablesWithPrefix = false)
/**
* Return the data specified by a single $selectspec - see long comment above.
* @deprecated 1.9.0 Use DbConnection->singleSelect() instead.
* @param $selectspec
* @return array|mixed
* @param array $selectspec
* @return mixed
*/
function qa_db_single_select($selectspec)
{
......@@ -496,9 +504,9 @@ function qa_db_post_select(&$outresult, $selectspec)
* 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.
* @deprecated 1.9.0 Use DbResult->fetchAllAssoc() instead.
* @param $result
* @param string $key
* @param mixed $value
* @param DbResult|mysqli_result $result
* @param string|null $key
* @param int|string|null $value
* @return array
*/
function qa_db_read_all_assoc($result, $key = null, $value = null)
......@@ -529,7 +537,7 @@ function qa_db_read_all_assoc($result, $key = null, $value = null)
* 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.
* @deprecated 1.9.0 Use DbResult->fetchNextAssoc() instead.
* @param $result
* @param DbResult|mysqli_result $result
* @param bool $allowempty
* @return array|null
*/
......@@ -539,7 +547,6 @@ function qa_db_read_one_assoc($result, $allowempty = false)
return $allowempty ? $result->fetchNextAssoc() : $result->fetchNextAssocOrFail();
}
// backwards compatibility
if (!($result instanceof mysqli_result))
qa_fatal_error('Reading one assoc from invalid result');
......@@ -559,7 +566,7 @@ function qa_db_read_one_assoc($result, $allowempty = false)
/**
* Return a numbered array containing the first (and presumably only) column from the $result resource.
* @deprecated 1.9.0 Use DbResult->fetchAllValues() instead.
* @param $result
* @param DbResult|mysqli_result $result
* @return array
*/
function qa_db_read_all_values($result)
......@@ -568,7 +575,6 @@ function qa_db_read_all_values($result)
return $result->fetchAllValues(0);
}
// backwards compatibility
if (!($result instanceof mysqli_result))
qa_fatal_error('Reading column from invalid result');
......@@ -586,9 +592,9 @@ function qa_db_read_all_values($result)
* 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.
* @deprecated 1.9.0 Use DbResult->fetchOneValue() instead.
* @param $result
* @param DbResult|mysqli_result $result
* @param bool $allowempty
* @return mixed|null
* @return string|null
*/
function qa_db_read_one_value($result, $allowempty = false)
{
......@@ -596,7 +602,6 @@ function qa_db_read_one_value($result, $allowempty = false)
return $allowempty ? $result->fetchOneValue(0) : $result->fetchOneValueOrFail(0);
}
// backwards compatibility
if (!($result instanceof mysqli_result))
qa_fatal_error('Reading one value from invalid result');
......
qa-include/util/image.php
......@@ -39,8 +39,8 @@ function qa_has_gd_image()
* Check if the image in $imagefile will be too big for PHP/GD to process given memory usage and limits
* Pass the width and height limit beyond which the image will require scaling in $size (if any)
* Returns false if the image will fit fine, otherwise a safe estimate of the factor the image should be sized by
* @param $imagefile
* @param int $size
* @param string $imagefile
* @param int|null $size
* @return bool|float
*/
function qa_image_file_too_big($imagefile, $size = null)
......@@ -82,12 +82,12 @@ function qa_image_file_too_big($imagefile, $size = null)
* Given $imagedata containing JPEG/GIF/PNG data, constrain it proportionally to fit in $maxwidth x $maxheight.
* Return the new image data (will always be a JPEG), and set the $width and $height variables.
* If $maxheight is omitted or set to null, assume it to be the same as $maxwidth.
* @param $imagedata
* @param string $imagedata
* @param int $width
* @param int $height
* @param int $maxwidth
* @param int $maxheight
* @return null|string
* @param int|null $maxheight
* @return string|null
*/
function qa_image_constrain_data($imagedata, &$width, &$height, $maxwidth, $maxheight = null)
{
......@@ -119,7 +119,7 @@ function qa_image_constrain_data($imagedata, &$width, &$height, $maxwidth, $maxh
* @param int $width
* @param int $height
* @param int $maxwidth
* @param int $maxheight
* @param int|null $maxheight
* @return bool
*/
function qa_image_constrain(&$width, &$height, $maxwidth, $maxheight = null)
......@@ -141,9 +141,9 @@ function qa_image_constrain(&$width, &$height, $maxwidth, $maxheight = null)
/**
* Resize the GD $image to $width and $height, setting it to null if the resize failed
* @param $image
* @param $width
* @param $height
* @param resource $image
* @param int $width
* @param int $height
*/
function qa_gd_image_resize(&$image, $width, $height)
{
......@@ -181,6 +181,7 @@ function qa_gd_image_jpeg($image, $output = false)
/**
* Return an array of strings listing the image formats that are supported
* @return array
*/
function qa_gd_image_formats()
{
......
qa-include/util/sort.php
......@@ -27,9 +27,9 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
/**
* Sort the $array of inner arrays by sub-element $by1 of each inner array, and optionally then by sub-element $by2
* @param $array
* @param $by1
* @param null $by2
* @param array $array
* @param string $by1
* @param string|null $by2
*/
function qa_sort_by(&$array, $by1, $by2 = null)
{
......@@ -44,8 +44,8 @@ function qa_sort_by(&$array, $by1, $by2 = null)
/**
* Function used in uasort to implement qa_sort_by()
* @param $a
* @param $b
* @param array $a
* @param array $b
* @return int
*/
function qa_sort_by_fn($a, $b)
......@@ -73,8 +73,8 @@ function qa_sort_by_fn($a, $b)
/**
* General comparison function for two values, textual or numeric
* @deprecated
* @param $a
* @param $b
* @param int|float|string $a
* @param int|float|string $b
* @return int
*/
function qa_sort_cmp($a, $b)
......@@ -89,9 +89,9 @@ function qa_sort_cmp($a, $b)
/**
* Inserts $addelements into $array, preserving their keys, before $beforekey in that array.
* If $beforekey cannot be found, the elements are appended at the end of the array.
* @param $array
* @param $beforekey
* @param $addelements
* @param array $array
* @param string $beforekey
* @param array $addelements
*/
function qa_array_insert(&$array, $beforekey, $addelements)
{
......@@ -130,9 +130,9 @@ define('QA_ARRAY_AT_END', 0.9); // place all the elements at the end of the arra
* element by passing the key of that element in $beforekey (if $beforekey is not found, the elements are moved to the
* end of the array). Any of the QA_ARRAY_* values defined above can also be passed in the $beforekey parameter.
* If $reorderrelative is true, the relative ordering between the elements will also be set by the order in $keys.
* @param $array
* @param $keys
* @param mixed $beforekey
* @param array $array
* @param array $keys
* @param mixed|null $beforekey
* @param bool $reorderrelative
*/
function qa_array_reorder(&$array, $keys, $beforekey = null, $reorderrelative = true)
......
qa-include/util/string.php
......@@ -421,7 +421,7 @@ function qa_string_initialize()
* Return the UTF-8 input string converted into an array of words, changed $tolowercase (or not).
* Set $delimiters to true to keep the delimiters after each word and tweak what we used for word
* splitting with $splitideographs and $splithyphens.
* @param $string
* @param string $string
* @param bool $tolowercase
* @param bool $delimiters
* @param bool $splitideographs
......@@ -521,8 +521,8 @@ function qa_slugify($string, $asciiOnly = true, $maxLength = null)
/**
* Convert an array of tags into a string for storage in the database
* @param $tags
* @return mixed|string
* @param array $tags
* @return string
*/
function qa_tags_to_tagstring($tags)
{
......@@ -534,7 +534,7 @@ function qa_tags_to_tagstring($tags)
/**
* Convert a tag string as stored in the database into an array of tags
* @param $tagstring
* @param string $tagstring
* @return array|mixed
*/
function qa_tagstring_to_tags($tagstring)
......@@ -548,7 +548,6 @@ function qa_tagstring_to_tags($tagstring)
/**
* Converts a string to a single line and removes words from it until it fits in the given length. Words are removed
* from a position around two thirds of the string and are replaced by the given ellipsis string
*
* @param string $string Text that will be turned into a single line and cut, if necessary
* @param int $length Maximum allowed length of the returned string. This value can be overriden by the length of the
* ellipsis if it is higher than the maximum allowed length
......@@ -596,7 +595,7 @@ function qa_shorten_string_line($string, $length, $ellipsis = ' ... ')
/**
* Removes 4-byte Unicode characters (e.g. emoji) from a string due to missing support in MySQL < 5.5.3.
* @param string $string
* @param string $string
* @return string
*/
function qa_remove_utf8mb4($string)
......@@ -611,8 +610,8 @@ function qa_remove_utf8mb4($string)
/**
* Return an array of the words within $wordstring, each of which can contain asterisks
* @param $wordstring
* @return array|mixed
* @param string $wordstring
* @return array
*/
function qa_block_words_explode($wordstring)
{
......@@ -624,7 +623,7 @@ function qa_block_words_explode($wordstring)
/**
* Return a regular expression fragment corresponding to the block words $wordstring
* @param $wordsstring
* @param string $wordsstring
* @return mixed|string
*/
function qa_block_words_to_preg($wordsstring)
......@@ -652,8 +651,8 @@ function qa_block_words_to_preg($wordsstring)
/**
* Return an array of matches of the regular expression fragment $wordspreg in $string, [offset] => [length]
* @param $string
* @param $wordspreg
* @param string $string
* @param string $wordspreg
* @return array
*/
function qa_block_words_match_all($string, $wordspreg)
......@@ -693,7 +692,7 @@ function qa_block_words_match_all($string, $wordspreg)
* @param string $string
* @param string $wordspreg
* @param string $character
* @return mixed
* @return string
*/
function qa_block_words_replace($string, $wordspreg, $character = '*')
{
......@@ -713,7 +712,7 @@ function qa_block_words_replace($string, $wordspreg, $character = '*')
/**
* Return a random alphanumeric string (base 36) of $length
* @param $length
* @param int $length
* @return string
*/
function qa_random_alphanum($length)
......@@ -729,8 +728,8 @@ function qa_random_alphanum($length)
/**
* Return true or false to indicate whether $email is a valid email (this is pretty flexible compared to most real emails out there)
* @param $email
* @return bool|mixed
* @param string $email
* @return bool
*/
function qa_email_validate($email)
{
......@@ -742,8 +741,8 @@ function qa_email_validate($email)
/**
* Return the number of characters in $string, preferably using PHP's multibyte string functions
* @param $string
* @return int|mixed
* @param string $string
* @return int
*/
function qa_strlen($string)
{
......@@ -755,8 +754,8 @@ function qa_strlen($string)
/**
* Return a lower case version of $string, preferably using PHP's multibyte string functions
* @param $string
* @return mixed|string
* @param string $string
* @return string
*/
function qa_strtolower($string)
{
......@@ -768,10 +767,10 @@ function qa_strtolower($string)
/**
* Return $length characters from $string, starting from $start, preferably using PHP's multibyte string functions
* @param $string
* @param $start
* @param string $string
* @param int $start
* @param int $length
* @return mixed|string
* @return string
*/
function qa_substr($string, $start, $length = 2147483647)
{
......@@ -783,6 +782,7 @@ function qa_substr($string, $start, $length = 2147483647)
/**
* Return whether this version of PHP has been compiled with multibyte string support
* @return bool
*/
function qa_has_multibyte()
{
......@@ -792,8 +792,8 @@ function qa_has_multibyte()
/**
* Return true if at least one of the values in array $matches is a substring of $string. Otherwise, return false.
* @param $string
* @param $matches
* @param string $string
* @param array $matches
* @return bool
*/
function qa_string_matches_one($string, $matches)
......
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