Changeset 27337


Ignore:
Timestamp:
Feb 11, 2014, 11:12:57 PM (7 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.