= Common Methods to all class-db extended class =
[[PageOutline(2-3, Table of content, inline)]]


[[BR]][[BR]]
== Instanciation methods ==

=== db::function setDefaultConnectionStr($connectionStr) ===
set the default connection string to be used when calling db::getInsance() with no arguments. 
 - @param string $connectionStr the connection string is a semi colon separated list
                              of connection parameter in the order they appear in the constructor
                              preceeded by !classname://
                              for exemple a mysqldb connection string will look like:
                              "!mysqldb://dbname;dbhost:port;dbuser;dbpass"
                              and a sqlite3db one will look like:
                              "!sqlite3db://dbfile"
example
{{{
#!php
<?php
db::setDefaultConnectionStr('mysqldb://test;localhost;root;');
$db = db::getInstance();
}}}
----
=== db::getInstance($connectionStr=null,$setDefault=false) ===
static method that return a single instance of the database corresponding to the given connection String.[[BR]]
This method '''must''' be copyed in the exended class as php is not able to get the name of the calling class (waiting php >= 5.3 for late static binding to get rid of this).
 - @param string $connectionStr the connection string is a semi colon separated list
                              of connection parameter in the order they appear in the constructor
                              preceeded by !classname://
                              for exemple a mysqldb connection string will look like:
                              "!mysqldb://dbname;dbhost:port;dbuser;dbpass"
                              and a sqlitedb one will look like:
                              "!sqlitedb://dbfile"
 - @param bool $setDefault      if true then this database connection will be the default one
                              returned when no arguments are given.
                              For conveniance the first call to this method
                              will set the corresponding instance the default one
                              if none has been set before
 - @return db instance
example
{{{
#!php
<?php
$db = db::getInstance('mysqldb://test;localhost;root;',true);
}}}
----
=== default __construct() ===
'''''This way of creating an instance is not encourage anymore! '''''
 - @deprecated use @see getInstance instead
constructor stay public even if we have getInstance for 2 reason
 1. backward compatibility with existing scripts
 2. permit getInstance to create any derived class without redefining it in each subclass
'''DON'T RELY ON THIS ANY MORE IT MAY CHANGE IN FUTURE RELEASE'''
----


[[BR]][[BR]]
== Selection methods ==
=== select_rows($tables,$fields = '*', $conds = null,$result_type = 'ASSOC') ===
send a select query to $table on requested $fields (all by default) and conforming to clause defined with $conditions[[BR]]
see process_conds for more info on $conditions parameter
 - @param string|array $Table
 - @param string|array $fields
 - @param string|array $conditions
 - @param string $res_type 'ASSOC', 'NUM' et 'BOTH'
 - @Return  array | false
{{{
#!php 
<?php
$rows = $db->select_rows('myTable','*',array('WHERE myField=?',$myfieldValue);
}}}
----

=== select_row($tables,$fields = '*', $conds = null,$result_type = 'ASSOC') ===
Same as select_rows but return only the first row.
equal to $res = select_rows followed by $res = $res[0];
So most of the time you will use it with a condition clause ending by 'LIMIT 0,1'
 - @see select_rows for details
 - @return array of fields
{{{
#!php 
<?php
$row = $db->select_rows('myTable','*','LIMIT 0,1');
}}}
----

=== select_associative($tables,$fields='*',$conds=null,$index_field='id',$value_fields=null,$keep_index=FALSE) ===
just a quick way to do a select_rows followed by a associative_array_from_q2a_res[[BR]]
see both thoose method for more information about parameters or return values
''(in fact you will certainly rarely use associative_array_from_q2a_res but use select_associative most of the time)''
{{{
#!php 
<?php
#- getting fieldValue indexed by fieldId
$values = $db->select_associative('myTable','fieldId,FieldValue',null,'fieldId','fieldValue');
# will return something like this
array(
  'FieldId' => 'fieldValue',
  'FieldId' => 'fieldValue',
  ...
  'FieldId' => 'fieldValue',
);
#- getting all fields of myTable indexed by fieldValue
$rowsById = $db->select_associative('myTable','fieldId,FieldValue1,fieldValue2',null,'fieldId');
# will return something like this
array(
  'FieldId' => array('fieldValue1','fieldValue2'),
  'FieldId' => array('fieldValue1','fieldValue2'),
  ...
  'FieldId' => array('fieldValue1','fieldValue2'),
);

}}}
----

=== select_value($table,$field,$conds=null) ===
select a single value in database
 - @param string $table
 - @param string $field the field name where to pick-up value
 - @param mixed conds
 - @return mixed or FALSE
{{{
#!php 
<?php
$login = $db->select_value('users','login',array('WHERE userID=?',$id));
}}}
----

=== select_col($table,$field,$conds=null) ===
select a single field in table and return all values
 - @param string $table
 - @param string $field name of the single field to retrieve
 - @param mixed  $conds
 - @return array or FALSE
{{{
#!php 
<?php
$logins = $db->select_col('users','login');
}}}
----

=== select_slice($table,$fields='*',$conds=null,$pageId=1,$pageNbRows=10) === 
This method is an helper to easily create page navigation for large result sets.[[BR]]
You can configure the navigationStr with set_slice_attrs() method
 - @param string|array $table
 - @param string|array $fields
 - @param string|array $conditions
 - @param int          $pageId     the page to query and return (start at 1)
 - @param int          $pageNbRows the max number of results by page.
 - @return array  array((array) results,(str) navigationstring, (int) totalrows) or false on empty results
{{{
#!php 
<?php
$res = $db->select_slice('users','userID,login',null,1,5);
if( $res !== false)
  list($rows,$navigationStr,$totalRows) = $res;
}}}
----

=== query_to_array($Q_str,$result_type='ASSOC') ===
return the result of a query to an array.[[BR]]
Typically you will use this one for more advanced queries.
 - @param string $Q_str SQL query
 - @param string $result_type 'ASSOC', 'NUM' et 'BOTH'
 - @return array | false if no result

{{{
#!php 
<?php
$rows = $db->query_to_array(
  "SELECT * FROM users"
);
}}}
----

=== get_count($table,$conds=null) ===
get the number of row in $table
 - @param string $table table name
 - @param mixed  $conds
 - @return int
{{{
#!php 
<?php
$nbUsers = $db->get_count('users');
}}}
----

=== associative_array_from_q2a_res($index_field='id',$value_fields=null,$res = null,$keep_index=FALSE,$sort_keys=FALSE) ===
return an associative array indexed by $index_field with values $value_fields from a db->select_rows result.[[BR]]
Most of the time you will preferably use db->select_associative in place of this one.
 - @param string $index_field default value is id
 - @param mixed $value_fields (string field name or array of fields name default is null so keep all fields
 - @param array $res the mysqldb->select_rows result
 - @param bool $keep_index if set to true then the index field will be keep in the values associated (unused if $value_fields is string)
 - @param bool $sort_keys will automaticly sort the array by key if set to true @deprecated argument
 - @return array