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

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)