Merge "Add type hints to dml.php methods"

htdocs/lib/dml.php

@@ -35,7 +35,7 @@ function db_quote_table_placeholders($sql) {
  * A callback function used only in db_quote_table_placeholders
  * @param array $matches
  */
-function _db_quote_table_placeholders_callback($matches) {
+function _db_quote_table_placeholders_callback(array $matches) {
     return db_table_name($matches[1]);
 }
 
@@ -125,7 +125,7 @@ function column_collation_is_default($table, $column) {
  * @return boolean
  * @throws SQLException
  */
-function execute_sql($command, $values=null) {
+function execute_sql($command, array $values=null) {
     global $db;
 
     if (!is_a($db, 'ADOConnection')) {
@@ -186,7 +186,7 @@ function record_exists($table, $field1=null, $value1=null, $field2=null, $value2
  * @return bool true if a matching record exists, else false.
  * @throws SQLException
  */
-function record_exists_select($table, $select='', $values=null) {
+function record_exists_select($table, $select='', array $values=null) {
 
     global $CFG;
 
@@ -207,7 +207,7 @@ function record_exists_select($table, $select='', $values=null) {
  * @return bool true if the SQL executes without errors and returns at least one record.
  * @throws SQLException
  */
-function record_exists_sql($sql, $values=null) {
+function record_exists_sql($sql, array $values=null) {
     $rs = get_recordset_sql($sql, $values, 0, 1);
     return $rs->RecordCount() > 0;
 }
@@ -241,7 +241,7 @@ function count_records($table, $field1=null, $value1=null, $field2=null, $value2
  * @return int The count of records returned from the specified criteria.
  * @throws SQLException
  */
-function count_records_select($table, $select='', $values=null, $countitem='COUNT(*)') {
+function count_records_select($table, $select='', array $values=null, $countitem='COUNT(*)') {
     if ($select) {
         $select = 'WHERE ' . $select;
     }
@@ -262,7 +262,7 @@ function count_records_select($table, $select='', $values=null, $countitem='COUN
  * @return int        The count.
  * @throws SQLException
  */
-function count_records_sql($sql, $values=null) {
+function count_records_sql($sql, array $values=null) {
     $rs = get_recordset_sql($sql, $values);
     return reset($rs->fields);
 }
@@ -299,7 +299,7 @@ function get_record($table, $field1, $value1, $field2=null, $value2=null, $field
  * @return Found record as object. False if not found
  * @throws SQLException
  */
-function get_record_sql($sql, $values=null) {
+function get_record_sql($sql, array $values=null) {
     $limitfrom = 0;
     $limitnum  = 0;
     # regex borrowed from htdocs/lib/adodb/adodb-lib.inc.php
@@ -336,7 +336,7 @@ function get_record_sql($sql, $values=null) {
  * @return object Returns an array of found records (as objects)
  * @throws SQLException
  */
-function get_record_select($table, $select='', $values=null, $fields='*') {
+function get_record_select($table, $select='', array $values=null, $fields='*') {
     if ($select) {
         $select = 'WHERE '. $select;
     }
@@ -375,7 +375,7 @@ function get_record_select($table, $select='', $values=null, $fields='*') {
  * @param string $fields a comma separated list of fields to return (optional, by default all fields are returned).
  * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
  * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
- * @return mixed an ADODB RecordSet object.
+ * @return ADORecordSet an ADODB RecordSet object.
  * @throws SQLException
  */
 function get_recordset($table, $field='', $value='', $sort='', $fields='*', $limitfrom='', $limitnum='') {
@@ -405,10 +405,10 @@ function get_recordset($table, $field='', $value='', $sort='', $fields='*', $lim
  * @param string $fields a comma separated list of fields to return (optional, by default all fields are returned).
  * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
  * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
- * @return mixed an ADODB RecordSet object
+ * @return ADORecordSet an ADODB RecordSet object
  * @throws SQLException
  */
-function get_recordset_select($table, $select='', $values=null, $sort='', $fields='*', $limitfrom='', $limitnum='') {
+function get_recordset_select($table, $select='', array $values=null, $sort='', $fields='*', $limitfrom='', $limitnum='') {
     if ($select) {
         $select = ' WHERE '. $select;
     }
@@ -438,10 +438,10 @@ function get_recordset_select($table, $select='', $values=null, $sort='', $field
  * @param array $values When using prepared statements, this is the value array (optional).
  * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
  * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
- * @return mixed an ADODB RecordSet object
+ * @return ADORecordSet an ADODB RecordSet object
  * @throws SQLException
  */
-function get_recordset_sql($sql, $values=null, $limitfrom=null, $limitnum=null) {
+function get_recordset_sql($sql, array $values=null, $limitfrom=null, $limitnum=null) {
     global $db;
 
     if (!is_a($db, 'ADOConnection')) {
@@ -483,11 +483,11 @@ function get_recordset_sql($sql, $values=null, $limitfrom=null, $limitnum=null)
 /**
  * Utility function to turn a result set into an array of records
  *
- * @param object an ADODB RecordSet object.
+ * @param ADORecordSet an ADODB RecordSet object.
  * @return mixed an array of objects, or false if the RecordSet was empty.
  * @throws SQLException
  */
-function recordset_to_array($rs) {
+function recordset_to_array(ADORecordSet $rs) {
     if ($rs && $rs->RecordCount() > 0) {
         $array = $rs->GetArray();
         foreach ($array as &$a) {
@@ -510,12 +510,12 @@ function recordset_to_array($rs) {
  * This method turns a result set into a hash of records (keyed by the first
  * field in the result set)
  *
- * @param  object $rs An ADODB RecordSet object.
- * @return mixed  An array of objects, or false if the RecordSet was empty.
+ * @param  ADORecordSet $rs An ADODB RecordSet object.
+ * @return mixed An array of objects, or false if the RecordSet was empty.
  * @throws SQLException
  * @access private
  */
-function recordset_to_assoc($rs) {
+function recordset_to_assoc(ADORecordSet $rs) {
     if ($rs && $rs->RecordCount() > 0) {
         // First of all, we are going to get the name of the first column
         // to introduce it back after transforming the recordset to assoc array
@@ -622,7 +622,7 @@ function get_records_select_assoc($table, $select='', $values=null, $sort='', $f
  * @return mixed an array of objects, or false if no records were found.
  * @throws SQLException
  */
-function get_records_select_array($table, $select='', $values=null, $sort='', $fields='*', $limitfrom='', $limitnum='') {
+function get_records_select_array($table, $select='', array $values=null, $sort='', $fields='*', $limitfrom='', $limitnum='') {
     $rs = get_recordset_select($table, $select, $values, $sort, $fields, $limitfrom, $limitnum);
     return recordset_to_array($rs);
 }
@@ -639,7 +639,7 @@ function get_records_select_array($table, $select='', $values=null, $sort='', $f
  * @return mixed an array of objects, or false if no records were found.
  * @throws SQLException
  */
-function get_records_sql_assoc($sql,$values, $limitfrom='', $limitnum='') {
+function get_records_sql_assoc($sql, array $values, $limitfrom='', $limitnum='') {
     $rs = get_recordset_sql($sql, $values, $limitfrom, $limitnum);
     return recordset_to_assoc($rs);
 }
@@ -656,7 +656,7 @@ function get_records_sql_assoc($sql,$values, $limitfrom='', $limitnum='') {
  * @return mixed an array of objects, or false if no records were found.
  * @throws SQLException
  */
-function get_records_sql_array($sql,$values, $limitfrom='', $limitnum='') {
+function get_records_sql_array($sql, array $values, $limitfrom='', $limitnum='') {
     $rs = get_recordset_sql($sql, $values, $limitfrom, $limitnum);
     return recordset_to_array($rs);
 }
@@ -669,11 +669,11 @@ function get_records_sql_array($sql,$values, $limitfrom='', $limitnum='') {
 /**
  * Utility function used by the following 3 methods.
  *
- * @param object $rs an ADODB RecordSet object with two columns.
+ * @param ADORecordSet $rs an ADODB RecordSet object with two columns.
  * @return mixed an associative array, or false if an error occurred or the RecordSet was empty.
  * @access private
  */
-function recordset_to_menu($rs) {
+function recordset_to_menu(ADORecordSet $rs) {
     global $CFG;
 
     if ($rs && $rs->RecordCount() > 0) {
@@ -730,7 +730,7 @@ function get_records_menu($table, $field='', $value='', $sort='', $fields='*') {
  * @param string $fields A comma separated list of fields to be returned from the chosen table.
  * @return mixed an associative array, or false if no records were found or an error occurred.
  */
-function get_records_select_menu($table, $select='', $values=null, $sort='', $fields='*') {
+function get_records_select_menu($table, $select='', array $values=null, $sort='', $fields='*') {
     $rs = get_recordset_select($table, $select, $values, $sort, $fields);
     return recordset_to_menu($rs);
 }
@@ -745,7 +745,7 @@ function get_records_select_menu($table, $select='', $values=null, $sort='', $fi
  * @param array $values When using prepared statements, this is the value array (optional).
  * @return mixed an associative array, or false if no records were found or an error occured.
  */
-function get_records_sql_menu($sql,$values=null) {
+function get_records_sql_menu($sql, array $values=null) {
     $rs = get_recordset_sql($sql,$values);
     return recordset_to_menu($rs);
 }
@@ -784,7 +784,7 @@ function get_field($table, $field, $field1=null, $value1=null, $field2=null, $va
  * @return mixed the specified value.
  * @throws SQLException
  */
-function get_field_sql($sql, $values=null) {
+function get_field_sql($sql, array $values=null) {
     $rs = get_recordset_sql($sql, $values);
     if ($rs && $rs->RecordCount() == 1) {
         return reset($rs->fields);
@@ -827,7 +827,7 @@ function get_column($table, $field, $field1=null, $value1=null, $field2=null, $v
  * @return mixed the specified value.
  * @throws SQLException
  */
-function get_column_sql($sql, $values=null) {
+function get_column_sql($sql, array $values=null) {
     global $db;
 
     $sql = db_quote_table_placeholders($sql);
@@ -863,7 +863,7 @@ function get_column_sql($sql, $values=null) {
  * @param string $value2 the value field2 must have (requred if field2 is given, else optional).
  * @param string $field3 the third field to check (optional).
  * @param string $value3 the value field3 must have (requred if field3 is given, else optional).
- * @return mixed An ADODB RecordSet object with the results from the SQL call or false.
+ * @return ADORecordSet An ADODB RecordSet object with the results from the SQL call or false.
  * @throws SQLException
  */
 function set_field($table, $newfield, $newvalue, $field1=null, $value1=null, $field2=null, $value2=null, $field3=null, $value3=null) {
@@ -875,7 +875,7 @@ function set_field($table, $newfield, $newvalue, $field1=null, $value1=null, $fi
     return set_field_select($table, $newfield, $newvalue, $select, $values);
 }
 
-function set_field_select($table, $newfield, $newvalue, $select, $values) {
+function set_field_select($table, $newfield, $newvalue, $select, array $values) {
     global $db;
 
     // @todo Catalyst IT Ltd
@@ -912,7 +912,7 @@ function set_field_select($table, $newfield, $newvalue, $select, $values) {
  * @param string $value2 the value field2 must have (requred if field2 is given, else optional).
  * @param string $field3 the third field to check (optional).
  * @param string $value3 the value field3 must have (requred if field3 is given, else optional).
- * @return mixed An ADODB RecordSet object with the results from the SQL call or false.
+ * @return ADORecordSet An ADODB RecordSet object with the results from the SQL call or false.
  * @throws SQLException
  */
 function delete_records($table, $field1=null, $value1=null, $field2=null, $value2=null, $field3=null, $value3=null) {
@@ -938,10 +938,10 @@ function delete_records($table, $field1=null, $value1=null, $field2=null, $value
  * @param string $table The database table to be checked against.
  * @param string $select A fragment of SQL to be used in a where clause in the SQL call (used to define the selection criteria).
  * @param array $values When using prepared statements, this is the value array (optional).
- * @return object A PHP standard object with the results from the SQL call.
+ * @return ADORecordSet An ADODB RecordSet object with the results from the SQL call or false.
  * @throws SQLException
  */
-function delete_records_select($table, $select='',$values=null) {
+function delete_records_select($table, $select='', array $values=null) {
     if ($select) {
         $select = 'WHERE '.$select;
     }
@@ -953,7 +953,7 @@ function delete_records_select($table, $select='',$values=null) {
  * it has with the $values parameter should be merged with the execute_sql
  * function
  */
-function delete_records_sql($sql, $values=null) {
+function delete_records_sql($sql, array $values=null) {
     global $db;
 
     $sql = db_quote_table_placeholders($sql);
@@ -1382,7 +1382,7 @@ function column_type($table, $column) {
  */
 // in dml not ddl because we want to keep ddl 'clean upstream' - p
 
-function execute_sql_arr($sqlarr, $continue=true, $feedback=true) {
+function execute_sql_arr(array $sqlarr, $continue=true, $feedback=true) {
 
     if (!is_array($sqlarr)) {
         return false;
@@ -1510,7 +1510,7 @@ function is_mysql() {
  *
  * @param array $array input array
  */
-function db_array_to_ph($array) {
+function db_array_to_ph(array $array) {
     return array_pad(array(), count($array), '?');
 }
 
@@ -1672,7 +1672,7 @@ function db_random() {
  *
  * @param array $replacearray keys = search, values = replacements.
  */
-function db_replace($replacearray) {
+function db_replace(array $replacearray) {
 
     global $db;