Datalib - a database abstraction layer for PHP


Well, apparently you need a little help in getting everything working! Have no fear as this documentation should get you up and going in no time at all. To the left you will see two panes. The top pane just lists the packages, of which there is only one (Datalib). The bottom pane lists all the library files, as well as all the classes.

The DlDatabase and DlRecordset classes are the base classes of which every other class inherits from. There are some methods (and members) that are defined in these two base classes that are NOT overidden in the child classes. Thus, perusing the documentation on the two base classes might merit a couple minutes of your time.

Supported Database Systems



Currently, only these database systems are supported: Further database support is tentative, depending on the access I can get to the software or to a server running a new database system (that is supported by PHP).

Getting Started



There is not much you need to do to get up and running with Datalib. First things first, Datalib expects all it's library files to be in a directory named "include" off of your webroot. The pathing is relative currently, and it is a requested feature I will add a configuration element to specify a absolute pathname.

In your PHP file, you need to add a statement:

include_once 'include/datalib.php';

near the top of your file. Next, you need to figure out what Database Identifier to use for the database system you will be accessing. Below is a table of the supported database systems, and their associated identifiers.

Database SystemIdentifier
InterbaseIbase
Microsoft SQL ServerMSSQL
MySQLMySQL
ODBCODBC
Oracle 8+Oracle
PostgreSQLPGSQL
SybaseSybase

Next, you will need to create a database connection. This is achieved by calling the NewConnection method of the DlDatabase class. The parameters for this method are: identifier, username, password, databasename, servername. Once the object has been created, you then need to open it via a call to the Open() method. This method will return either true or false, so you may check it for errors.

After that has been completed, you will then be able to create some recordset objects. This is accomplished via a call to the DlRecordset's NewRecordset method. This method takes one argument, which is the connection object. You will then Open the recordset, with the single argument being a SQL query. You can perform operations on it after that. Below are a few examples.

Examples



For our examples, we will query a theoretical table named news with the attributes of id, title, body and date.

Example One
For this example, we will use the ADO-style navigation interface:

		<?PHP
		// include our library
		include_once 'include/datalib.php';
		
		// create our connection
		$conn =& DlDatabase::NewConnection("MySQL", "root", "", "datalib", "localhost");
		if (!$conn->Open()) {
			die('An error occured: ' . $conn->GetError());
		}
		
		// now create our recordset
		$rs =& DlRecordset::NewRecordset($conn);
		if (!$rs->Open("select id, title, body, date from news order by date desc")) {
		    die ('An error occured: ' . $rs->GetError());
		}
		
		// we can now loop through our recordset and display the results
		while (!$rs->Eof()) {
		    echo $rs->Value('title') . '<br />' . $rs->Value('date') . '<br />' . $rs->Value('body') . '<br /><br />';
		    $rs->MoveNext();
		}
		?>
		

In the above example, we don't use the id column as it's not needed. As well, with the ADO-style interface for navigation, you can move backwards as well with a MovePrevious() method call. A MoveLast() will move the row pointer to the end of the result set.

Example Two
This next example will use the more customary PHP-style interface for fetching rows:

		<?PHP
		// include our library
		include_once 'include/datalib.php';

		// create our connection
		$conn =& DlDatabase::NewConnection("MySQL", "root", "", "datalib", "localhost");
		if (!$conn->Open()) {
			die('An error occured: ' . $conn->GetError());
		}

		// now create our recordset
		$rs =& DlRecordset::NewRecordset($conn);
		if (!$rs->Open("select id, title, body, date from news order by date desc")) {
			die ('An error occured: ' . $rs->GetError());
		}

		// we can now loop through our recordset and display the results
		while ($row = $rs->FetchArray()) {
			echo $row['title'] . '<br />' . $row['date'] . '<br />' . $row['body'] . '<br /><br />';
		}
		?>
		

You should note that either method of getting the values (via Value() or FetchArray()) is able to use the column name, OR the column index (zero based). Also of note, some of PHP's drivers are extremely picky regarding capitalization of column names. So when you pass a column name to the array or Value() method, maintain the same capitilization that you used in your SQL query. Some drivers will let you query with any capitalization, but returns the results in all upper case. The Datalib drivers should handle these instances for you, so just stick to the same capitalization used in your query!

Should you need to issue queries that do not return results (ie: Update, Insert, Delete), then you should use the Execute() method of the connection object. Just pass the method a string with the query, and it will execute it, returning false if it encountered any errors.

If you have any questions, stop on by Databound Software and pose your question in the forums! If you have bugs to report, or features to request then head on over to the project pages at Sourceforge.


Happy Coding!