Previous Section  < Day Day Up >  Next Section

7.2 Connecting to a Database Program

To use PEAR DB in a PHP program, first you have to load the DB module. Use the require construct, as shown in Example 7-1.

Example 7-1. Loading an external file with require
require 'DB.php';

Example 7-1 tells the PHP interpreter to execute all of the code in the file DB.php. DB.php is the main file of the PEAR DB package. It defines the functions that you use to talk to your database.

Similar to require is include. These constructs differ in how they handle errors. If you try to include or require a file that doesn't exist, require considers that a fatal error and your PHP program ends. The include construct is more forgiving and just reports a warning, allowing your program to continue running.

After the DB module is loaded, you need to establish a connection to the database with the DB::connect( ) function. You pass DB::connect( ) a string that describes the database you are connecting to, and it returns an object that you use in the rest of your program to exchange information with the database program.

An object is a new data type. It's a bundle of some data and functions that operate on that data. PEAR DB uses objects to provide you with a connection to the database. The double colons in the DB::connect( ) function call are a way of telling the PHP interpreter that you're calling a special function based on an object.

Example 7-2 shows a call to DB::connect( ) that connects to MySQL.

Example 7-2. Connecting with DB::connect( )
require 'DB.php';

$db = DB::connect('mysql://penguin:top^');

The string passed to DB::connect( ) is called a Data Source Name (DSN). Its general form is:


In Example 7-2, the DSN tells PEAR DB to connect to MySQL running on the database server as user penguin with the password top^hat, and to access the restaurant database on that server.

PEAR DB supports 13 options for the db_program part of the DSN. These are listed in Table 7-1.

Table 7-1. PEAR DB db_program options


Database program










Mini SQL


Microsoft SQL Server


MySQL (versions <= 4.0)


MySQL (versions >= 4.1.2)


Oracle (Versions 7, 8, and 9)









When your database program is running on the same computer as your web server, specify localhost as the hostname part of the DSN, as shown in Example 7-3.

Example 7-3. Connecting to localhost
$db = DB::connect('mysql://penguin:top^hat@localhost/restaurant');

If all goes well with DB::connect( ), it returns an object that you use to interact with the database. If there is a problem connecting, it returns a different kind of object that contains information about what went wrong. The DB::isError( ) function checks whether the object contains error information. Use it to make sure that the connection was made before going forward in your program. Example 7-4 uses DB::isError( ) to verify that DB::connect( ) succeeded.

Example 7-4. Checking for connection errors
require 'DB.php';

$db = DB::connect('mysql://penguin:top^');

if (DB::isError($db)) { die("Can't connect: " . $db->getMessage( )); }

The DB::isError( ) function returns true if the object passed to it contains error information. The die( ) function prints out a message and then causes the script to quit. In this case, the message is the string Can't connect: followed by the results of the $db->getMessage( ) call. The getMessage( ) function returns more information about the error.

Earlier, I said that an object is a bundle of data and functions that operate on that data. A -> after an object tells the PHP interpreter that you want to call one of those functions in the object. Once you have called DB::connect, you use the functions in the object to interact with the database. The code $db->getMessage( ) means "call the getMessage( ) function inside the $db object." In this case, the $db object holds error information and the getMessage( ) function prints out some of that information.

For example, if top^hat is the wrong password for user penguin, Example 7-4 prints:

Can't connect: DB Error: connect failed

    Previous Section  < Day Day Up >  Next Section