A Detailed Look at PEAR
Pages: 1, 2

The PEAR::DB class factory

If you ever tried to open PEAR's DB package to see how it works, you probably got confused at the way that it handles the classes and subclasses of all the database drivers and error routines. I hope that I helped you understand the standard PEAR_Error class and how PEAR libraries call PEAR_Error to create a special object with information about the error. Now we are going to study the "factory" method of PEAR::DB to use the appropriate database driver that is specified at runtime from the caller script.

This "factory" method is quite simple once you get used to the way it works. Example code showing PEAR::DB works follows:

<?php
include_once("DB.php");

$dsn = array(
    'phptype'  => "mysql",
    'hostspec' => "localhost",
    'database' => "test_db",
    'username' => "scott",
    'password' => "tiger"
);
$dbh = DB::connect($dsn);
?>

It works by sending an array with all the specifications of host, type of database (MySQL, PostgreSQL, or whatnot), database name, and other information to the connect() method of the DB class. Once again, we are using static method calls to connect to the appropriate server.

The connect() method of DB is what people call a "factory" method. It includes the appropriate PHP file from the DB subdirectory and instantiates an object from that class definition. It works like this:

<?php
class DB
{
    function connect($dsn)
    {
        $type = $dsn["phptype"];
        @include_once("DB/${type}.php");

        $classname = "DB_${type}";
        @$obj =& new $classname;
        $obj->connect($dsn);

        return $obj;
    }
}
?>

This includes a file and connects to the database server using its own connect() method. It will return a database handler, which is just an object with the methods from the DB_${type} class, which in our case is just the DB_mysql class.

This way of handling the drivers is much cleaner and more professional than by forcing the user know the correct class and functions in order to connect to a database server. In this case, this would be the PHP developer using the PEAR::DB package. It serves as an abstraction library, which generalizes as much as possible the way the database works and how it is accessed.

Hierarchical view of the PEAR::DB structure

The structure and general design of PEAR::DB is why everything works so well and why it is so expandable. Creating a new driver for PEAR::DB is not a hard task -- all one must do is to create the new driver and store it under the DB subdirectory of PEAR. The main DB class should be able to use it correctly by just changing one line of the PHP code, the front-end script that calls the package:

<?php
$dsn = array(
    'phptype'  => "NEW_DATADASE_NAME_HERE",
    'hostspec' => "localhost",
    'database' => "test_db",
    'username' => "scott",
    'password' => "tiger"
);
?>

The library is also very well designed to make the drivers share important functionality, by storing the utility functions in DB/common.php. This file contains the DB_common class, which is inherited by all other database classes from the DB directory, as follows:

<?php
require_once "DB/common.php";

class DB_mysql extends DB_common
{
    // ...
}
?>

This makes it easier to re-use code among the drivers, and most of the functions and methods found on this utility class are standard methods such as getRow(), numRows(), and affectedRows().

I hope this article helped shed some light into some of the advanced coding techniques of PEAR, and made reading the PEAR source code a little bit easier.

Joao Prado Maia is a web developer living in Houston with more than four years of experience developing web-based applications and loves learning new technologies and programming languages.

---

Return to the PHP DevCenter.