From 7146581f86ed7e1a346fcc76536794ae97771e05 Mon Sep 17 00:00:00 2001 From: mistic100 Date: Tue, 11 Feb 2014 22:12:57 +0000 Subject: feature 2999: (incomplete) doc of mysqli functions git-svn-id: http://piwigo.org/svn/trunk@27337 68402e56-0260-453c-a942-63ccdbb3a9ee --- include/dblayer/functions_mysqli.inc.php | 202 ++++++++++++++++++------------- 1 file changed, 117 insertions(+), 85 deletions(-) (limited to 'include/dblayer') diff --git a/include/dblayer/functions_mysqli.inc.php b/include/dblayer/functions_mysqli.inc.php index 31bf9abf3..390cf2e06 100644 --- a/include/dblayer/functions_mysqli.inc.php +++ b/include/dblayer/functions_mysqli.inc.php @@ -21,28 +21,34 @@ // | USA. | // +-----------------------------------------------------------------------+ +/** + * @package functions\mysql + */ + define('DB_ENGINE', 'MySQL'); define('REQUIRED_MYSQL_VERSION', '5.0.0'); define('DB_REGEX_OPERATOR', 'REGEXP'); define('DB_RANDOM_FUNCTION', 'RAND'); + /** + * Connect to database and store MySQLi resource in __$mysqli__ global variable. * - * simple functions + * @param string $host + * - localhost + * - 1.2.3.4:3405 + * - /path/to/socket + * @param string $user + * @param string $password + * @param string $database * + * @throws Exception */ - function pwg_db_connect($host, $user, $password, $database) { global $mysqli; - // $host can be: - // - // $host = localhost - // $host = 1.2.3.4:3405 - // $host = /path/to/socket - $port = null; $socket = null; @@ -69,6 +75,9 @@ function pwg_db_connect($host, $user, $password, $database) } } +/** + * Set charset for database connection. + */ function pwg_db_check_charset() { $db_charset = 'utf8'; @@ -79,6 +88,9 @@ function pwg_db_check_charset() pwg_query('SET NAMES "'.$db_charset.'"'); } +/** + * Check MySQL version. Can call fatal_error(). + */ function pwg_db_check_version() { $current_mysql = pwg_get_db_version(); @@ -94,6 +106,11 @@ function pwg_db_check_version() } } +/** + * Get Mysql Version. + * + * @return string + */ function pwg_get_db_version() { global $mysqli; @@ -101,6 +118,12 @@ function pwg_get_db_version() return $mysqli->server_info; } +/** + * Execute a query + * + * @param string $query + * @return mysqli_result|bool + */ function pwg_query($query) { global $mysqli, $conf, $page, $debug, $t2; @@ -149,6 +172,13 @@ function pwg_query($query) return $result; } +/** + * Get max value plus one of a particular column. + * + * @param string $column + * @param string $table + * @param int + */ function pwg_db_nextval($column, $table) { $query = ' @@ -231,36 +261,35 @@ function pwg_db_close() return $mysqli->close(); } -/** - * - * complex functions - * - */ define('MASS_UPDATES_SKIP_EMPTY', 1); + /** - * updates multiple lines in a table + * Updates multiple lines in a table. * - * @param string table_name - * @param array dbfields - * @param array datas - * @param int flags - if MASS_UPDATES_SKIP_EMPTY - empty values do not overwrite existing ones - * @return void + * @param string $tablename + * @param array $dbfields - contains 'primary' and 'update' arrays + * @param array $datas - indexed by column names + * @param int $flags - if MASS_UPDATES_SKIP_EMPTY, empty values do not overwrite existing ones */ function mass_updates($tablename, $dbfields, $datas, $flags=0) { if (count($datas) == 0) + { return; - - // depending on the MySQL version, we use the multi table update or N update queries + } + + // we use the multi table update or N update queries if (count($datas) < 10) { foreach ($datas as $data) { + $is_first = true; + $query = ' UPDATE '.$tablename.' SET '; - $is_first = true; + foreach ($dbfields['update'] as $key) { $separator = $is_first ? '' : ",\n "; @@ -271,24 +300,28 @@ UPDATE '.$tablename.' } else { - if ( $flags & MASS_UPDATES_SKIP_EMPTY ) + if ($flags & MASS_UPDATES_SKIP_EMPTY) + { continue; // next field + } $query.= "$separator$key = NULL"; } $is_first = false; } + if (!$is_first) {// only if one field at least updated + $is_first = true; + $query.= ' WHERE '; - $is_first = true; foreach ($dbfields['primary'] as $key) { if (!$is_first) { $query.= ' AND '; } - if ( isset($data[$key]) ) + if (isset($data[$key])) { $query.= $key.' = \''.$data[$key].'\''; } @@ -298,18 +331,18 @@ UPDATE '.$tablename.' } $is_first = false; } + pwg_query($query); } } // foreach update - } // if mysqli_ver or count $value) + + foreach ($datas as $key => $value) { $separator = $is_first ? '' : ",\n "; @@ -408,24 +442,29 @@ UPDATE '.$tablename.' } else { - if ( $flags & MASS_UPDATES_SKIP_EMPTY ) + if ($flags & MASS_UPDATES_SKIP_EMPTY) + { continue; // next field + } $query.= "$separator$key = NULL"; } $is_first = false; } + if (!$is_first) {// only if one field at least updated + $is_first = true; + $query.= ' WHERE '; - $is_first = true; - foreach ($where_fields as $key => $value) + + foreach ($where as $key => $value) { if (!$is_first) { $query.= ' AND '; } - if ( isset($value) ) + if (isset($value)) { $query.= $key.' = \''.$value.'\''; } @@ -435,18 +474,19 @@ UPDATE '.$tablename.' } $is_first = false; } + pwg_query($query); } } - /** - * inserts multiple lines in a table + * Inserts multiple lines in a table. * - * @param string table_name - * @param array dbfields - * @param array inserts - * @return void + * @param string $table_name + * @param array $dbfields - fields from $datas which will be used + * @param array $datas + * @param array $options + * - boolean ignore - use "INSERT IGNORE" */ function mass_inserts($table_name, $dbfields, $datas, $options=array()) { @@ -506,17 +546,16 @@ INSERT '.$ignore.' INTO '.$table_name.' } $query .= ')'; } + pwg_query($query); } } /** - * inserts one line in a table + * Inserts one line in a table. * - * @param string table_name - * @param array dbfields - * @param array insert - * @return void + * @param string $table_name + * @param array $data */ function single_insert($table_name, $data) { @@ -555,10 +594,9 @@ INSERT INTO '.$table_name.' } } + /** - * Do maintenance on all PWG tables - * - * @return none + * Do maintenance on all Piwigo tables */ function do_maintenance_all_tables() { @@ -631,24 +669,20 @@ function pwg_db_cast_to_text($string) } /** - * returns an array containing the possible values of an enum field + * Returns an array containing the possible values of an enum field. * - * @param string tablename - * @param string fieldname + * @param string $table + * @param string $field + * @return string[] */ function get_enums($table, $field) { - // retrieving the properties of the table. Each line represents a field : - // columns are 'Field', 'Type' - $result = pwg_query('desc '.$table); + $result = pwg_query('DESC '.$table); while ($row = pwg_db_fetch_assoc($result)) { - // we are only interested in the the field given in parameter for the - // function if ($row['Field'] == $field) { - // retrieving possible values of the enum field - // enum('blue','green','black') + // parse enum('blue','green','black') $options = explode(',', substr($row['Type'], 5, -1)); foreach ($options as $i => $option) { @@ -656,14 +690,15 @@ function get_enums($table, $field) } } } + pwg_db_free_result($result); return $options; } /** - * Smartly checks if a variable is equivalent to true or false + * Checks if a variable is equivalent to true or false. * - * @param mixed input + * @param mixed $input * @return bool */ function get_boolean($input) @@ -677,7 +712,8 @@ function get_boolean($input) } /** - * returns boolean string 'true' or 'false' if the given var is boolean + * Returns string 'true' or 'false' if the given var is boolean. + * If the input is another type, it is not changed. * * @param mixed $var * @return mixed @@ -694,12 +730,6 @@ function boolean_to_string($var) } } -/** - * - * interval and date functions - * - */ - function pwg_db_get_recent_period_expression($period, $date='CURRENT_DATE') { if ($date!='CURRENT_DATE') @@ -721,12 +751,12 @@ SELECT '.pwg_db_get_recent_period_expression($period); function pwg_db_get_flood_period_expression($seconds) { - return 'SUBDATE(now(), INTERVAL '.$seconds.' SECOND)'; + return 'SUBDATE(NOW(), INTERVAL '.$seconds.' SECOND)'; } function pwg_db_get_hour($date) { - return 'hour('.$date.')'; + return 'HOUR('.$date.')'; } function pwg_db_get_date_YYYYMM($date) @@ -781,8 +811,10 @@ function pwg_db_date_to_ts($date) return 'UNIX_TIMESTAMP('.$date.')'; } -// my_error returns (or send to standard output) the message concerning the -// error occured for the last mysql query. +/** + * Returns (or send to standard output) the message concerning the + * error occured for the last mysql query. + */ function my_error($header, $die) { global $mysqli; -- cgit v1.2.3