Loading a database module

When loading a database module with FSO::load_module() or the like, the first argument to the __init() method of the database driver is an array of connection parameters, and therefore the line to load a database might look something like this:

<?php
FSO::load_module('db_mysql',
    array(
        array('db' => 'mydb', 'user' => 'someuser', 'pass' => 'mypass')
    ),
    'thedb');
?>

Note the nesting of the array() parts - the 2nd argument for load_module() is an array of arguments to the __init() of the module. The above will create a MySQL database object using the specified parameters at $fso->thedb. Because of the aliasing possible with FSO, you can easily load multiple database connections by using different aliases for them.

Using the database module

The database modules are really just a wrapper around PHP Data Objects, and therefore can be used in the exact same way (mostly, see below) - the PDO docs describe how to use the database modules.

I have however made some additions of my own. The most important is the way the query() method works. Because the overheads of preparing single statements are negligible compared to the advantage of not worrying about quoting, I have replaced the original query() method with one that lets you use placeholders and pass parameters after the query.

<?php
//  Old method
$stmt = $db->query("SELECT * FROM table WHERE field1=".$db->quote($_POST['field1'])
    ." AND field2=".$db->quote($_POST['field2']);
//  New method
$stmt = db->query("SELECT * FROM table WHERE field1=? AND field2=?", $_POST['field1'], $_POST['field2']);
//  Using the results as normal
while ( $row = $stmt->fetch() )
{
    // ...
}
?>

Another advantage is that because the Statement object returned is a prepared statement, you can use it again:

<?php
$rowset1 = $stmt->fetchAll();
$stmt->execute(array($foo, $bar));
$rowset2 = $stmt->fetchAll();
?>

Another addition is fetchAllRows() on the statement object. This method will return an array that has 2 elements - a 'data' element which contains the entire result set as associative arrays, and a 'rowcount' element which contains the number of rows in the result set. This is especially useful for database types that do not say how many rows were fetched usually (like MySQL).

Extending the database class

Its understandable that occasionally it might be desirable to add functionality to the database modules. If, for example, you want to extend the DB_mysql module, use the following format:

<?php
if ( !class_exists('FSO') )
    die('Framework SuperObject base class must be loaded to use its modules!');

FSO::load_class('db_mysql');

class My_DB_Module extends DB_mysql
{
    //  Overload the constructor if necessary
    function __construct()
    {
        //  Remember to to call the parent constructor if overloading
        parent::__construct($conf);
    }

    //  Other stuff
}
?>