Modules
Description
MDB2 follows a modular concept to provide functionality beyond the basic ability to send queries to the database and fetch result sets. Currently the following modules are available:
- Datatype module (API) - handles datatype abstraction via the MDB2_Datatype_Common class
- Extended module (API) - provides numerous high-level methods via the MDB2_Extended class
- Function module (API) - handles SQL function abstraction via the MDB2_Function_Common class
- Manager module (API) - handles data definition language (DDL) abstraction and schema listing via the MDB2_Manager_Common class
- Native module (API) - handles RDBMS specific functions via the MDB2_Native_Common class
- Reverse module (API) - handles schema reverse engineering abstraction via the MDB2_Reverse_Common class
A module is loaded using the loadModule() method. This method returns the module instance, but also stores the instance in a property. The name of the property is either the lowercased name of the module passed in as the first parameter, or optionally the non null value of the second parameter. The optional third parameter is used to differentiate modules that depend on a specific RDBMS (like the Datatype module) and those that do not (like the Extended module). The method can also be used to load custom modules that are installed.
The third parameter is automatically detected if it is not set. On hosts that have 'safe_mode' enabled automatic detection does however require silenced falls to fopen(). Error handling and error handlers should be configured accordingly.
Loading a module
<?php
require_once 'MDB2.php';
$dsn = 'pgsql://someuser:apasswd@localhost/thedb';
$options = array(
'debug' => 2,
'result_buffering' => false,
);
$mdb2 =& MDB2::connect($dsn, $options);
if (PEAR::isError($mdb2)) {
die($mdb2->getMessage());
}
// ...
$mdb2->loadModule('Manager');
// specifically stating that the module that is being loaded is RDBMS independent
// this works around some needless internal calls
$mdb2->loadModule('Extended', null, false);
?>
Loading a custom module that is RDBMS independent
<?php
// ...
// file must reside in [peardir]/MDB2/MyModule.php
class MDB2_MyModule extends MDB2_Module_Common
{
function myMethod()
{
$db =& $this->getDBInstance();
if (PEAR::isError($db)) {
return $db;
}
...
}
}
?>
<?php
// ...
// file must reside in [peardir]/MDB2/MyModule.php
$mdb2->loadModule('MyModule');
?>
Loading a custom module that is RDBMS dependent
<?php
// ...
// file must reside in [peardir]/MDB2/Driver/MyRDBMSModule/pgsql.php
// this is the class that would get loaded for an MDB2 PostgreSQL instance
// equivalent classes for other backends would need to implemented,
// potentially making use of a common base class
class MDB2_Driver_MyRDBMSModule_pgsql extends MDB2_Module_Common
{
function myRDBMSMethod()
{
$db =& $this->getDBInstance();
if (PEAR::isError($db)) {
return $db;
}
...
}
}
?>
<?php
// ...
// file must reside in [peardir]/MDB2/Driver/MyRDBMSModule/[phptype].php
$mdb2->loadModule('MyRDBMSModule');
?>
Using a loaded module
<?php
// ...
// loading into default name
$mdb2->loadModule('Manager');
$tables = $mdb2->manager->listTables();
// loading into non standard property $foo
$mdb2->loadModule('Function', 'foo');
$tables = $mdb2->foo->concat($str1, $str2);
?>
On PHP5 users can also rely on overloading to load and call modules.
Using the 'modules' option with PHP5 overloading
<?php
require_once 'MDB2.php';
$dsn = 'pgsql://someuser:apasswd@localhost/thedb';
$options = array(
'debug' => 2,
'result_buffering' => false,
);
$mdb2 =& MDB2::connect($dsn, $options);
if (PEAR::isError($mdb2)) {
die($mdb2->getMessage());
}
// ...
$module_shorthands = $mdb2->getOptions('modules');
// use the shorthand key for the given module as a prefix for the method name
// where the first letter of the original method name is uppercased
$tables = $mdb2->mgListTables();
?>
Calling a method on a loaded module with PHP5 overloading
<?php
require_once 'MDB2.php';
$dsn = 'pgsql://someuser:apasswd@localhost/thedb';
$options = array(
'debug' => 2,
'result_buffering' => false,
);
$mdb2 =& MDB2::connect($dsn, $options);
if (PEAR::isError($mdb2)) {
die($mdb2->getMessage());
}
// ...
$mdb2->loadModule('Manager');
// since the manager module is already loaded we can call the listTable() method
$tables = $mdb2->manager->listTables();
// NB: on PHP5, where __autoload() is available,
// the above line can be rewritten as:
$tables = $mdb2->listTables();
?>