Changeset 27337


Ignore:
Timestamp:
02/11/14 23:12:57 (5 years ago)
Author:
mistic100
Message:

feature 2999: (incomplete) doc of mysqli functions

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/include/dblayer/functions_mysqli.inc.php

    r27336 r27337  
    2222// +-----------------------------------------------------------------------+ 
    2323 
     24/** 
     25 * @package functions\mysql 
     26 */ 
     27 
    2428define('DB_ENGINE', 'MySQL'); 
    2529define('REQUIRED_MYSQL_VERSION', '5.0.0'); 
     
    2832define('DB_RANDOM_FUNCTION', 'RAND'); 
    2933 
    30 /** 
    31  * 
    32  * simple functions 
    33  * 
    34  */ 
    35  
     34 
     35/** 
     36 * Connect to database and store MySQLi resource in __$mysqli__ global variable. 
     37 * 
     38 * @param string $host 
     39 *    - localhost 
     40 *    - 1.2.3.4:3405 
     41 *    - /path/to/socket 
     42 * @param string $user 
     43 * @param string $password 
     44 * @param string $database 
     45 * 
     46 * @throws Exception 
     47 */ 
    3648function pwg_db_connect($host, $user, $password, $database) 
    3749{ 
    3850  global $mysqli; 
    39  
    40   // $host can be: 
    41   // 
    42   // $host = localhost 
    43   // $host = 1.2.3.4:3405 
    44   // $host = /path/to/socket 
    4551 
    4652  $port = null; 
     
    7076} 
    7177 
     78/** 
     79 * Set charset for database connection. 
     80 */ 
    7281function pwg_db_check_charset()  
    7382{ 
     
    8089} 
    8190 
     91/** 
     92 * Check MySQL version. Can call fatal_error(). 
     93 */ 
    8294function pwg_db_check_version() 
    8395{ 
     
    95107} 
    96108 
     109/** 
     110 * Get Mysql Version. 
     111 * 
     112 * @return string 
     113 */ 
    97114function pwg_get_db_version()  
    98115{ 
     
    102119} 
    103120 
     121/** 
     122 * Execute a query 
     123 * 
     124 * @param string $query 
     125 * @return mysqli_result|bool 
     126 */ 
    104127function pwg_query($query) 
    105128{ 
     
    150173} 
    151174 
     175/** 
     176 * Get max value plus one of a particular column. 
     177 * 
     178 * @param string $column 
     179 * @param string $table 
     180 * @param int 
     181 */ 
    152182function pwg_db_nextval($column, $table) 
    153183{ 
     
    232262} 
    233263 
    234 /** 
    235  * 
    236  * complex functions 
    237  * 
    238  */ 
    239264 
    240265define('MASS_UPDATES_SKIP_EMPTY', 1); 
    241 /** 
    242  * updates multiple lines in a table 
    243  * 
    244  * @param string table_name 
    245  * @param array dbfields 
    246  * @param array datas 
    247  * @param int flags - if MASS_UPDATES_SKIP_EMPTY - empty values do not overwrite existing ones 
    248  * @return void 
     266 
     267/** 
     268 * Updates multiple lines in a table. 
     269 * 
     270 * @param string $tablename 
     271 * @param array $dbfields - contains 'primary' and 'update' arrays 
     272 * @param array $datas - indexed by column names 
     273 * @param int $flags - if MASS_UPDATES_SKIP_EMPTY, empty values do not overwrite existing ones 
    249274 */ 
    250275function mass_updates($tablename, $dbfields, $datas, $flags=0) 
    251276{ 
    252277  if (count($datas) == 0) 
     278  { 
    253279    return; 
    254    
    255   // depending on the MySQL version, we use the multi table update or N update queries 
     280  } 
     281 
     282  // we use the multi table update or N update queries 
    256283  if (count($datas) < 10) 
    257284  { 
    258285    foreach ($datas as $data) 
    259286    { 
     287      $is_first = true; 
     288 
    260289      $query = ' 
    261290UPDATE '.$tablename.' 
    262291  SET '; 
    263       $is_first = true; 
     292 
    264293      foreach ($dbfields['update'] as $key) 
    265294      { 
     
    272301        else 
    273302        { 
    274           if ( $flags & MASS_UPDATES_SKIP_EMPTY ) 
     303          if ($flags & MASS_UPDATES_SKIP_EMPTY) 
     304          { 
    275305            continue; // next field 
     306          } 
    276307          $query.= "$separator$key = NULL"; 
    277308        } 
    278309        $is_first = false; 
    279310      } 
     311 
    280312      if (!$is_first) 
    281313      {// only if one field at least updated 
     314        $is_first = true; 
     315 
    282316        $query.= ' 
    283317  WHERE '; 
    284         $is_first = true; 
    285318        foreach ($dbfields['primary'] as $key) 
    286319        { 
     
    289322            $query.= ' AND '; 
    290323          } 
    291           if ( isset($data[$key]) ) 
     324          if (isset($data[$key])) 
    292325          { 
    293326            $query.= $key.' = \''.$data[$key].'\''; 
     
    299332          $is_first = false; 
    300333        } 
     334 
    301335        pwg_query($query); 
    302336      } 
    303337    } // foreach update 
    304   } // if mysqli_ver or count<X 
     338  } // if count<X 
    305339  else 
    306340  { 
    307341    // creation of the temporary table 
    308     $query = ' 
    309 SHOW FULL COLUMNS FROM '.$tablename; 
    310     $result = pwg_query($query); 
     342    $result = pwg_query('SHOW FULL COLUMNS FROM '.$tablename); 
    311343    $columns = array(); 
    312344    $all_fields = array_merge($dbfields['primary'], $dbfields['update']); 
     345 
    313346    while ($row = pwg_db_fetch_assoc($result)) 
    314347    { 
     
    351384    pwg_query($query); 
    352385    mass_inserts($temporary_tablename, $all_fields, $datas); 
    353     if ( $flags & MASS_UPDATES_SKIP_EMPTY ) 
     386 
     387    if ($flags & MASS_UPDATES_SKIP_EMPTY) 
    354388      $func_set = create_function('$s', 'return "t1.$s = IFNULL(t2.$s, t1.$s)";'); 
    355389    else 
    356390      $func_set = create_function('$s', 'return "t1.$s = t2.$s";'); 
    357391 
    358     // update of images table by joining with temporary table 
     392    // update of table by joining with temporary table 
    359393    $query = ' 
    360394UPDATE '.$tablename.' AS t1, '.$temporary_tablename.' AS t2 
     
    373407        ); 
    374408    pwg_query($query); 
    375     $query = ' 
    376 DROP TABLE '.$temporary_tablename; 
    377     pwg_query($query); 
    378   } 
    379 } 
    380  
    381 /** 
    382  * updates one line in a table 
    383  * 
    384  * @param string table_name 
    385  * @param array set_fields 
    386  * @param array where_fields 
    387  * @param int flags - if MASS_UPDATES_SKIP_EMPTY - empty values do not overwrite existing ones 
    388  * @return void 
    389  */ 
    390 function single_update($tablename, $set_fields, $where_fields, $flags=0) 
    391 { 
    392   if (count($set_fields) == 0) 
     409 
     410    pwg_query('DROP TABLE '.$temporary_tablename); 
     411  } 
     412} 
     413 
     414/** 
     415 * Updates one line in a table. 
     416 * 
     417 * @param string $tablename 
     418 * @param array $datas 
     419 * @param array $where 
     420 * @param int $flags - if MASS_UPDATES_SKIP_EMPTY, empty values do not overwrite existing ones 
     421 */ 
     422function single_update($tablename, $datas, $where, $flags=0) 
     423{ 
     424  if (count($datas) == 0) 
    393425  { 
    394426    return; 
    395427  } 
     428 
     429  $is_first = true; 
    396430 
    397431  $query = ' 
    398432UPDATE '.$tablename.' 
    399433  SET '; 
    400   $is_first = true; 
    401   foreach ($set_fields as $key => $value) 
     434 
     435  foreach ($datas as $key => $value) 
    402436  { 
    403437    $separator = $is_first ? '' : ",\n    "; 
     
    409443    else 
    410444    { 
    411       if ( $flags & MASS_UPDATES_SKIP_EMPTY ) 
     445      if ($flags & MASS_UPDATES_SKIP_EMPTY) 
     446      { 
    412447        continue; // next field 
     448      } 
    413449      $query.= "$separator$key = NULL"; 
    414450    } 
    415451    $is_first = false; 
    416452  } 
     453 
    417454  if (!$is_first) 
    418455  {// only if one field at least updated 
     456    $is_first = true; 
     457 
    419458    $query.= ' 
    420459  WHERE '; 
    421     $is_first = true; 
    422     foreach ($where_fields as $key => $value) 
     460 
     461    foreach ($where as $key => $value) 
    423462    { 
    424463      if (!$is_first) 
     
    426465        $query.= ' AND '; 
    427466      } 
    428       if ( isset($value) ) 
     467      if (isset($value)) 
    429468      { 
    430469        $query.= $key.' = \''.$value.'\''; 
     
    436475      $is_first = false; 
    437476    } 
     477 
    438478    pwg_query($query); 
    439479  } 
    440480} 
    441481 
    442  
    443 /** 
    444  * inserts multiple lines in a table 
    445  * 
    446  * @param string table_name 
    447  * @param array dbfields 
    448  * @param array inserts 
    449  * @return void 
     482/** 
     483 * Inserts multiple lines in a table. 
     484 * 
     485 * @param string $table_name 
     486 * @param array $dbfields - fields from $datas which will be used 
     487 * @param array $datas 
     488 * @param array $options 
     489 *    - boolean ignore - use "INSERT IGNORE" 
    450490 */ 
    451491function mass_inserts($table_name, $dbfields, $datas, $options=array()) 
     
    507547      $query .= ')'; 
    508548    } 
     549 
    509550    pwg_query($query); 
    510551  } 
     
    512553 
    513554/** 
    514  * inserts one line in a table 
    515  * 
    516  * @param string table_name 
    517  * @param array dbfields 
    518  * @param array insert 
    519  * @return void 
     555 * Inserts one line in a table. 
     556 * 
     557 * @param string $table_name 
     558 * @param array $data 
    520559 */ 
    521560function single_insert($table_name, $data) 
     
    556595} 
    557596 
    558 /** 
    559  * Do maintenance on all PWG tables 
    560  * 
    561  * @return none 
     597 
     598/** 
     599 * Do maintenance on all Piwigo tables 
    562600 */ 
    563601function do_maintenance_all_tables() 
     
    632670 
    633671/** 
    634  * returns an array containing the possible values of an enum field 
    635  * 
    636  * @param string tablename 
    637  * @param string fieldname 
     672 * Returns an array containing the possible values of an enum field. 
     673 * 
     674 * @param string $table 
     675 * @param string $field 
     676 * @return string[] 
    638677 */ 
    639678function get_enums($table, $field) 
    640679{ 
    641   // retrieving the properties of the table. Each line represents a field : 
    642   // columns are 'Field', 'Type' 
    643   $result = pwg_query('desc '.$table); 
     680  $result = pwg_query('DESC '.$table); 
    644681  while ($row = pwg_db_fetch_assoc($result)) 
    645682  { 
    646     // we are only interested in the the field given in parameter for the 
    647     // function 
    648683    if ($row['Field'] == $field) 
    649684    { 
    650       // retrieving possible values of the enum field 
    651       // enum('blue','green','black') 
     685      // parse enum('blue','green','black') 
    652686      $options = explode(',', substr($row['Type'], 5, -1)); 
    653687      foreach ($options as $i => $option) 
     
    657691    } 
    658692  } 
     693 
    659694  pwg_db_free_result($result); 
    660695  return $options; 
     
    662697 
    663698/** 
    664  * Smartly checks if a variable is equivalent to true or false 
    665  * 
    666  * @param mixed input 
     699 * Checks if a variable is equivalent to true or false. 
     700 * 
     701 * @param mixed $input 
    667702 * @return bool 
    668703 */ 
     
    678713 
    679714/** 
    680  * returns boolean string 'true' or 'false' if the given var is boolean 
     715 * Returns string 'true' or 'false' if the given var is boolean. 
     716 * If the input is another type, it is not changed. 
    681717 * 
    682718 * @param mixed $var 
     
    694730  } 
    695731} 
    696  
    697 /** 
    698  * 
    699  * interval and date functions  
    700  * 
    701  */ 
    702732 
    703733function pwg_db_get_recent_period_expression($period, $date='CURRENT_DATE') 
     
    722752function pwg_db_get_flood_period_expression($seconds) 
    723753{ 
    724   return 'SUBDATE(now(), INTERVAL '.$seconds.' SECOND)'; 
     754  return 'SUBDATE(NOW(), INTERVAL '.$seconds.' SECOND)'; 
    725755} 
    726756 
    727757function pwg_db_get_hour($date)  
    728758{ 
    729   return 'hour('.$date.')'; 
     759  return 'HOUR('.$date.')'; 
    730760} 
    731761 
     
    782812} 
    783813 
    784 // my_error returns (or send to standard output) the message concerning the 
    785 // error occured for the last mysql query. 
     814/** 
     815 * Returns (or send to standard output) the message concerning the  
     816 * error occured for the last mysql query. 
     817 */ 
    786818function my_error($header, $die) 
    787819{ 
Note: See TracChangeset for help on using the changeset viewer.