<?
/*
 * Introducing DBlite!
 *
 * DBlite is a simplified version of PEAR::DB, which seemed to me quite heavy
 * and inflexible.
 *
 * Since version 1.0 DBlite was used as a base for many of different projects and
 * was included in at least 3 major framework api's. I have released version 2.0
 * of DBlite together with AModules3.
 *
 * This set of files introduces to the concepts of working with DBlite. This is
 * a first sample and it introduces general use of DBlite. You don't have to
 * use AModules3 if you want only DBlite, it works quite well as a standalone
 * library
 */

include '../../trunk/lib/DBlite.php';

/*
 * DBlite is a generic class. In the same directory where this file is located,
 * you can find directory called DBlite. It holds a bunch of different stuff.
 * Mostly those are classes named DBlite_extension. There are quite a few,
 * but let's start first with "drivers"
 *
 * Drivers extend DBlite interface to learn it to work with particular database
 * engine. Most common sample would be DBlite_mysql, which can work with
 * mysql3 and mysql4 servers. It does not use mysqli interface, there is
 * separate driver for that.
 *
 * Some drivers might be out of date. If it is so - fix it and send back patches
 * to me.
 */


/*
 * DSN: If you are not familiar with PEAR::DB, DSN is a string holding
 * information necessary to connect with database:
 *  - database type
 *  - db name
 *  - username
 *  - password
 *  - host
 *
 * are usually contained inside DSN. 
 *
 * Pear::DB's syntax
 *
 * $db =& DB::connect($dsn);
 *
 * DBlite's syntax:
 *
 * $db =& DBlite::connect($dsn);
 *
 * However DBlite introduces some improvements. First, you can specify $dsn
 * as array (so you don't have to worry that '@' in your password would screw up
 * or stuff like that). Also DBlite allows it's driver to extend DSN format.
 *
 * Implementation of DBlite should be simplier and faster than PEAR::DB and 
 * theoretically it should deliver better productivity, but I haven't did any
 * tests
 */

/*
 * DBlite 2.0 changes default behavior of connect. Because very often people do not
 * handle errors in mysql connection now 'connect' does it. It will output error
 * and halt if connection cannot be established.
 *
 * Alternatively you can use tryConnect method. It will try to establish connection
 * and will return either a object (if successful) or string (on error)
 */

$db=DBLite::tryConnect('mysql://hide@address.com/mysql');
if(is_string($db))$db=DBlite::connect('mysql://hide@address.com/mysql');
echo "<p>Successfuly connected to database using DBlite version ".$db->version."</p><hr/>";

/*
 * Now that we have connected let's try to do some actions. We'll start with
 * simple stuff.
 *  getOne($query)
 *  getRow($query)
 *  getAll($query)
 *
 * are a simple funcitons combining query inself and fetching of the result.
 * Depending on what kind of result you are expecting, it's easier to use
 * one of those funcitons. Here we are requestin for one row and are instersted
 * in first column only
 */

$users_count = $db->getOne("select count(*) from user");
echo "<p>You have $users_count users in mysql</p><hr/>";

/*
 * You can also perform query and then fetch results. No need to keep
 * cursor variable if you are working with one query at a time:
 */

echo "<p>Structure of 'host' table:";
$db->query("desc host");
echo "<table border=0 cellspacing=0 cellpadding=3 style='border: 1px solid black'>";
while($row = $db->fetchRow()){
    echo "<tr>";
    foreach($row as $field){
        echo "<td>$field</td>";
    }
    echo "</tr>\n";
}
echo "</table></p><hr/>";

/*
 * You can work with Hashes. Those are sometimes refered as associative arrays.
 * Instead of representing each row with array, it's now consists of
 *   'field_name'=>'value'
 * pairs. With those you don't have to worry about number of fields and their order.
 */
echo "<p>Some info from users table:";
$db->query("select * from user");
echo "<table border=0 cellspacing=0 cellpadding=3 style='border: 1px solid black'>";
while($row = $db->fetchHash()){
    echo "<tr>";
    echo "<td>{$row['User']}</td><td>{$row['Host']}</td>";
    echo "</tr>\n";
}
echo "</table></p><hr/>";
/*
 * Unfortunately even if mysql is case insensetive for fields, here you should know
 * exact case of your fields.
 */

/*
 * Error handling
 *
 * DBlite triggers default php errors unless you redefine error handler
 */
echo "<p>";
$db->query("select foo from bar");
echo "</p><hr/>";

/*
 * But you can also re-define error handler on your own. It can be function or method.
 * See manual for function is_callable() 
 */

function my_error_handler($string, $class){
    echo "MySQL error. Please try latter";
    // here we can send actuall error message to owner's email
}
$db->error_handler='my_error_handler';
echo "<p>";
$db->query("select foo from bar");
echo "</p><hr/>";

/*
 * This concludes basics of the DBlite module. See next lession for further information
 */

/*
 * There are actually 3 output modes:
 *  DB_FETCHMODE_ORDERED
 *  DB_FETCHMODE_ASSOC
 *  DB_FETCHMODE_IDROW
 * (constants are made compatible with PEAR::DB)
 *
 * You can pass fetchmode to some functions such as
 *
 * fetchRow (except IDROW)
 * getRow (except IDROW)
 * getAll (supports all 3 modes)
 *
 * You can also specify default mode when initializing (DBlite::connect), however
 * we do not advise you to do so. Those are only for compatibility, but if you
 * are writing your application, do not specify fetchmode when initializing and
 * use custom functions such as getHash, fetchHash and getAssoc
 *
 * getAssoc will return structure 2d array (similar to getAll) with IDKEY and ASSOC modes:
 * array(
 *  first_field_value=>array(2nd_field_name=>2nd_field_value, 3rd_field_name=>3rd_field_value),
 *  first_field_value=>array(2nd_field_name=>2nd_field_value, 3rd_field_name=>3rd_field_value),
 *  );
 *
 * Name of this function is missleading so it's better if you just pass desired
 * fetchmode as a second argument to getAll();
 */