I trust by now you should have downloaded the zip file containing the files for the Cross Database Engine. The installation for CDE requires a working Apache or ISS webserver with PHP5 installed and configured for your favourite database engine. If you are just beginning to use PHP and are unfamiliar with how these things might work, I suggest taking a look at a WAMP installation if you're on Windows or MAMP if you're on a Mac. For the Linux users out there it should be easy to install Apache and PHP5 from your package manager.
The most important thing is to find out where your document root is and if you make use of an includes folder. I recommend using the includes folder as it keeps all your include files in one place, next time you upgrade the CDE library it will be updated to all your working projects.
If you have located your document root folder for Apache then create a test.php file with the following code it it:
<?php phpinfo(); ?>
You will find out pretty much all you need to know about your current installation. Please note that some web providers may disable this functionality intentionally for security reasons.
Your first application will always give you a feel for how a library or engine works and it can be frustrating at first to get started. Sometimes it is merely a configuration problem that prevents you from continuing. In CDE we have attempted to provide the user with extensive and unobtrusive debugging features relevant to how the library is used and to which file you are working with. Most programmers struggle with the database connection and often this will be the first stumbling block in getting your first application working. Also make sure you have the correct username and password configured on your database engine. I would recommend creating your first database with SQLite seeing as it should be by default supported and there are no username and password implications.
Remember that whilst you may be working in SQLite the database principals remain the same across all database engines if you use CDE for all your PHP database projects. Enough with the lecturing already! Lets have a look at some code:
<?php //Put error reporting on so you know if you make a mistake error_reporting (E_ALL); ini_set ("display_errors", 1); //Include the cdesimple.php library require_once ( "cdesimple.php" ); //Create a brand new SQLite database $CDE = new CDESimple ( $dbpath="mydatabase.db", //this will create a database in the root of your webserver $username="", $password="", $dbtype="sqlite"); //sqlite3 is preferable however your ISP may still be in the stone ages echo "<pre>"; print_r ($CDE); //have a look under the hood! echo "</pre>"; ?>
And that is the “hello world” example of CDE for PHP.
It is important that you have a good understanding of how the CDE engine works under the hood, with this knowledge you will be able to supplement any CDE functionality with PHP functions for the specific database engine you are using. Of course this will not make you application truly cross database compliant but this will give you the freedom to add to the functionality of the library. The database handle is probably the most important property of the CDESimple class and can be used with the PHP functions the class encapsulates.
Below is a break down of the properties of the CDESimple class and then the methods used in CDESimple as well as concise examples. Using these examples will accelerate how fast you get to know the library and how you start to do things. We have tried to site real world examples in each section so as to bring home the understanding of CDESimple.
var $dbh; // the database handle can be used with any PHP functions of the same database engine var $error; // any errors that may occur during an operation var $dbtype="sqlite3"; // the default database type var $dbpath=""; // path to the database format is ipaddress:databasepath / for sqlite we just use the path var $tmppath="/tmp/"; // default path to temp space (only for sqlite) var $lastsql=""; // the last SQL statement that ran var $lasterror = Array(); // the last error before the current one var $debug=false; // set debug on or off var $affectedrows=0; // affected rows or rows returned by a query var $nooffields=0; // the no of columns or fields returned var $fieldinfo; // layout in an array of each field with its type and information var $version="1.4"; // current version of CDE var $dbdateformat="YYYY-mm-dd h:i:s"; //functionality for date time conversion to the database for a database var $outputdateformat="dd/mm/YYYY"; //all dates retrieved out of the database will be in this format var $updatefieldinfo=true; //this is turned off when doing computed field calculations, internal and expert use only
This function is used by CDESimple internally and should not be called at all, it is merely documented here so you can see how it works if you should want to use it to create your own errors inside the library.
The $dbpath variable is always specified in the format [server name:databasepath], there are some exceptions such as SQLite which merely takes the path and ODBC which will take the DSN name. The most recent change is the ability to specify the manner in which you want date fields to be formatted when they are returned as part of a result set, the format for $outputdateformat can be specified in any way as long as the variables YYYY, MM & DD are used. The time is not formatted as yet and is formatted in 24 hour format as hours then minutes.