eDFramework is the toolbox of eDreamers since October 2001.
It's gathering in one module all the concepts and components shared by most of the other eDreamers containers, modules and components.
The first components integrated to eDFramework were the database abstraction ones eDQuery (Automated Query Builder) and eDMySQLMS (Database Schema Builder). It's now neing extended to include the key block of most of the eDreamers Universe: eDObject.
- eDUtilities is a utility component containing useful functions mainly targetted at easing the development and debugging of your PHP class. It is inspired from an equivalent component from the PHPDoc application.
- eDQuery is multi-functional component able to build and run SQL statement against your MySQL database. It's used within the eDreamers universe to externalise and automate all that is related to database access in order to simplify the development of the components. Once executed, the results of the query are available in an associative array (or hashtable) very easy to use and manipulate in your code. A search function is also provided in order to quickly find some data within the query's results.
- eDMySQLMS build a complete or partial physical description of the databases, tables, fields on your MySQL database server. This description is provided using two associative arrays, a first one linking the database with their tables and another one the tables with their fields.
A search function is also available to check a database, a table or a field is existing on the server and in which database and/or table. eDMySQLMS uses the services of eDQuery.
- eDGetters build dynamically queries to retrieve a list of records from a master table and from its child tables linked with foreign keys. With it, nor a line of PHP-MySQL or SQL code neither eDQuery is needed when writing a PHP component. The counterpart is that its use is based on assumptions on fields and tables names that might require your database model to be changed. eDGetters uses the services of eDQuery and eDMySQLMS.
- eDObject is the first brick of advanced logical abstraction layer to be implemented on top of your MySQL databases where eDGetters is only a limited physical abstraction layer. From eDObject, generic scripts can generate automatically HTML forms to create and edit objects (complex records), and, also automatically, tables to list objects. For more information, about the underlying principles of eDObject you can read the "Logical DB Layer" article on the eDreamers website (http://www.edreamers.org).
The eDFramework module can be found, as all the eDreamers resources, on the eDreamers website at http://www.edreamers.org (all audiences).
All the eDreamers developments are managed using the services of the SourceForge.net where more information can be found (targetted to more technical audience).
If you don't already have available a webserver with PHP and MySQL, the implementation of this environment requires some time and additional documentations.
Fortunately, very good tools such as EasyPHP (on Windows) are installing this environment through an Installation Wizard in just few mouse clicks.
Although eDFramework has never been tested or yet reported as working on Linux and Mac systems, there's no reason why it would not function properly on those operating systems.
The following components are required (between brackets the one used during the eDFramework developments):
- A web server (APACHE 1.3.24)
- PHP installed and configured against the webserver (PHP 4.0)
- A MySQL database, not required unless you truly want to use the eDFramework components (MySQL 3.23)
- A MySQL Management Tool such as PHPMyAdmin, not required but very useful : ) (PHPMyAdmin 2.2.6)
Links to eDFramework download can be found on the http://www.edreamers.org website or directly on the Sourceforge.net eDreamers project page (http://www.sourceforge.net/projects/edscontacts/).
eDFramework is available as an archive of few ko in either tar.gz or zip format. Download it and save it under any location on your local drive(s).
Extract the eDFramework archive under any path under the root of your webserver. The following file structure will be created:
eDFramework\
eDFramework\api\ (All API documentation files)
eDFramework\_config.inc
eDFramework\documentation.html
eDFramework\eDFormBuilder.php
eDFramework\eDGetters.php
eDFramework\eDMySQLMS.php
eDFramework\eDObject.php
eDFramework\eDObject_save.php
eDFramework\eDObjectSave.php
eDFramework\eDQuery.php
eDFramework\eDUtilities.php
eDFramework\index.php
eDFramework\index.sql
eDFramework\xedobject.sql
If you obtain anything different please contact help@edreamers.org so that we either correct the archive or this documentation.
After this point, it is assumed that you have setup your webserver properly and that PHP and a MySQL database are available. Some of the following examples might require some data samples to be loaded in your database. All instructions and code samples, including SQL, are included within the sample description.
Before going further you will also need to edit the eDFramework\eDFramework\config.inc file to set the default parameters to the values that fits your environment. Help can be found directly in the file.
Each component of the eDFramework is specific and so requires specific documentation. You might found similarities as they are all built following the same model but each is addressing different needs. You'll find in this document one chapter per components of the eDFramework module. Chapters will be published one per one on a regular basis.
Chapters still to be published are (publishing of chapters between brackets is still to be confirmed)
7.(Retrieving complex database records with eDGetters)
8.(Automating the creation/update of records with eDObject_Save)
9.Creating a logical db object with eDObject
10.Generating an eDObject HTML form with eDFormBuilder
11.Creating, updating an eDObject with eDObjectSave
eD: "This part is quite technical and on top of a basic knowledge might require a basic understanding of the object paradigm. eDUtilities is a PHP class that you can inherit from when creating your own class. It will provide you with 3 main functions: setDebug(), out() and introspection() ones. Those functions are meant to ease your life of developer by helping you to debug your PHP classes. You'll find the detailed API specifications for this component in the eDFramework/doc/api/ folder. To demonstrate the use of eDUtilities, you'll need to create a sample class and make it inherit from eDUtilities. This requires that you have first included eDUtilities (here assumed to be in the same folder):"
<?php
require_once('eDUtilities.php');
class eDUtilitiesTest extends eDUtilities {
}
?>
eD: "This class should declare a constructor as most classes. We'll use this constructor to provide the class with the $debug boolean parameter to indicate if you wish to activate debug mode or not. The setDebug() methods of eDUtilities is called to set the debug mode. By default, this mode is always to false:"
<?php
require_once('eDUtilities.php');
class eDUtilitiesTest extends eDUtilities {
/** Constructor */
function eDUtilitiesTest($debug) {
$this->setDebug($debug);
}
}
?>
eD: "From now on you can use the out() function to print message on the default output (most probably the user's browser).
The mode is set to 'para' so that a line will be jumped before and after the message. The format is HTML so that the function knows that it can output HTML and use the <br> tag to a jump a line. I usually put a message in the constructor to show that it has being called:"
<?php
require_once('eDUtilities.php');
class eDUtilitiesTest extends eDUtilities {
/** Constructor */
function eDUtilitiesTest($debug) {
$this->setDebug($debug);
$this->out('eDUtilitiesTest::Constructor', 'para', 'html');
}
}
?>
eD: "It's now time to try it. You'll need to create a new instance of the eDUtilitiesTest class. You can do that in the same file. Call the constructor with a debug mode to true or else you won't see a thing:"
<?php
require_once('eDUtilities.php');
class eDUtilitiesTest extends eDUtilities {
/** Constructor */
function eDUtilitiesTest($debug) {
$this->setDebug($debug);
$this->out('eDUtilitiesTest::Constructor', 'para', 'html');
}
}
$myTest = new eDUtilitiesTest(true);
?>
eD: "Let's continue to the introspection() function. Let's call it from the instance $myTest. The introspection function will list all the variables manipulated by our class and its parent class (here eDUtilities) with the type and the value of those variables. Executing will only return three variables inherited from eDUtilities, $CR_html, $CR_text and $debug:"
<?php
require_once('eDUtilities.php');
class eDUtilitiesTest extends eDUtilities {
/** Constructor */
function eDUtilitiesTest($debug) {
$this->setDebug($debug);
$this->out('eDUtilitiesTest::Constructor', 'para', 'html');
}
}
$myTest = new eDUtilitiesTest(true);
$myTest->introspection();
?>
eD: "Let's try to add an array as class variable and see the results of introspection(). The array will be fully decomposed and all contained values will be shown with their type."
<?php
require_once('eDUtilities.php');
class eDUtilitiesTest extends eDUtilities {
var $anArray = array('Monday', 'Friday', 'Sunday');
/** Constructor */
function eDUtilitiesTest($debug) {
$this->setDebug($debug);
$this->out('eDUtilitiesTest::Constructor', 'para', 'html');
}
}
$myTest = new eDUtilitiesTest(true);
$myTest->introspection();
?>
eD: "You know everything about eDUtilities now. Enjoy!"
eD: "Welcome to this new chapter of the eDFramework documentation. As for the eDutilities related chapter, this part is quite technical and on top of a basic knowledge of PHP might require a basic understanding of the object paradigm and SQL."
eD:"eDQuery is a PHP class that is dedicated to moving all that is related to database queries out of your source code.
eDQuery can build all kind of queries but assumes that the most encoutered one are build on the following model: SELECT field1 [, field2] FROM database1.table1 [, database1.table2] WHERE field3 = 'value'.
In order to demonstrate the features of eDQuery, you will need to use one of your db or, safer, to create a new one with the following SQL statements. We'll take the example of a simple Human Resources db with a team, function and employee table. I do recommend downloading, installing and using PHPMyAdmin in order to manage and use your MySQL databases:"
CREATE DATABASE 'hr'
# Employee Table
CREATE TABLE employee (
employeeid mediumint(9) NOT NULL auto_increment,
eeteamid mediumint(9) NOT NULL default '0',
eefunctionid mediumint(9) NOT NULL default '0',
eefirstname char(30) NOT NULL default '',
eelastname char(30) NOT NULL default '',
PRIMARY KEY (employeeid)
) TYPE=MyISAM;
INSERT INTO employee (employeeid, eeteamid, eefunctionid, eefirstname, eelastname, ) VALUES (1, 1, 1, 'John', 'Smith');
INSERT INTO employee (employeeid, eeteamid, eefunctionid, eefirstname, eelastname, ) VALUES (2, 2, 2, 'Alain', 'Dupont');
# Function Table
CREATE TABLE function (
functionid int(10) NOT NULL auto_increment,
fnname char(50) NOT NULL default '',
PRIMARY KEY (functionid)
) TYPE=MyISAM;
INSERT INTO function (functionid, fnname) VALUES (1, 'Developer');
INSERT INTO function (functionid, fnname) VALUES (2, 'System Administrator');
# Team Table
CREATE TABLE team (
teamid int(11) NOT NULL auto_increment,
tmname char(100) NOT NULL default '',
PRIMARY KEY (teamid),
) TYPE=MyISAM;
INSERT INTO team (teamid, tmname) VALUES (1, 'Team A');
INSERT INTO team (teamid, tmname) VALUES (2, 'Team B');
eD: "Let's move on to PHP coding now. To be able to create a new eDQuery instance, you require the eDQuery.php file into your script. Assuming that eDQuery is located in the eDFramework sub-folder of the folder where your script is located this would give:"
<?php
require('eDFramework/eDQuery.php');
?>
eD: "You can build your first eDQuery. The current version of eDQuery assumes that you have a connection opended by default which is true in most environment. In a later version, eDQuery will make sure a connection is open (SFFR591985).
Let's take the example of a simple SELECT statement. It's not the best example to show the power of eDQuery but we have to start somewhere. eDQuery takes arrays as parameters for the SELECT, WHERE and FROM clause of your statement. I do recommend to declare and initialise those arrays before calling the eDQuery constructor for readibility.
The FROM array must use the following terminology database.table in order for eDQuery to work properly. This will be improve in a next version (SFFR591993).
Mode is a parameter that be set to either 'normal' or 'extended'. In 'normal' mode the SQL query is built but not executed, you can later get the query to do whatever you want with it. In 'extended' mode, the query is built and executed. Debug mode is disable to avoid filling your screen with traces:"
<?php
require('eDFramework/eDQuery.php');
$database = 'hr';
$arr_select = array('eefirstname', 'eelastname');
$arr_from = array('hr.employee');
$arr_where = null;
$orderBy = 'eefirstname';
$mode = 'extended'; // normal | extended
$debug = false; // true | false
$myQuery = new eDQuery($database, $arr_from, $arr_select, $arr_where, $orderBy, $mode, $debug );
?>
eD: "We just created a new instance of eDQuery named $myQuery. The query has been built and executed, it's just about time to get the results and display them. eDQuery returns the result to your query in an array of associative arrays. One associative array is created for each record found. In this array the field name are linked to the value found in the db. If you read the previous chapter of this document related to eDUtilities then its time to put things into practice again, else it's time to read this chapter! eDQuery is inheriting from eDUtilities and can so be used with the introspection() function. Introspection() will make the array of results visible (visual check). You can now call the getRecords() function to retrieve the array of results in your source code. I usually name the array of results with the name of the objects I'm retrieving, in our case, 'employees':"
<?php
require('eDFramework/eDQuery.php');
$database = 'hr';
$arr_select = array('eefirstname', 'eelastname');
$arr_from = array('hr.employee');
$arr_where = null;
$orderBy = 'eefirstname';
$mode = 'extended'; // normal | extended
$debug = false; // true | false
$myQuery = new eDQuery($database, $arr_from, $arr_select, $arr_where, $orderBy, $mode, $debug );
$myQuery->introspection();
$arr_employees = $myQuery->getRecords();
?>
You: "Good, but now what should I do with those results? How do I use them in my code?"
eD: "Well, associative arrays are very powerful. You need to use a foreach() loop in order to retrieve the list of records that have been found. Let's comment the line with the introspection(à function to only display the results. Let's display them as an unordered HTML list:"
<?php
require('eDFramework/eDQuery.php');
$database = 'hr';
$arr_select = array('eefirstname', 'eelastname');
$arr_from = array('hr.employee');
$arr_where = null;
$orderBy = 'eefirstname';
$mode = 'extended'; // normal | extended
$debug = false; // true | false
$myQuery = new eDQuery($database, $arr_from, $arr_select, $arr_where, $orderBy, $mode, $debug );
// $myQuery->introspection();
$arr_employees = $myQuery->getRecords();
print ('<ul>');
foreach ($arr_employees as $key => $arr_employee) {
print ('<li>'.$arr_employee['eefirstname'].' '.$arr_employee['eelastname'].'</li>');
}
print ('</ul>');
?>
eD: "The foreach() loop breaks the array of employees into an employee array that contains a value for each of the field from the SELECT statement. To display the corresponding value, you just have to get the element of the array that have the field name as key. You did it, you have your list of values without having to care about any PHP MySQL and SQL code."
You: "Ok, but if I just want to output one specific value from this array, how do I do?"
eD: "Well, eDQuery is also coming with a basic search function named getValue(). It returns the value of a target key based on the key value pair that you specify. Let's take an example: you would like to see if a 'Smith' is existing in your list and return his firstname. Instead of the foreach() loop we'll use the getValue() function as follows:"
<?php
require('eDFramework/eDQuery.php');
$database = 'hr';
$arr_select = array('eefirstname', 'eelastname');
$arr_from = array('hr.employee');
$arr_where = null;
$orderBy = 'eefirstname';
$mode = 'extended'; // normal | extended
$debug = false; // true | false
$myQuery = new eDQuery($database, $arr_from, $arr_select, $arr_where, $orderBy, $mode, $debug );
// $myQuery->introspection();
$arr_employees = $myQuery->getRecords();
print('<ul>');
print('<li>'.$myQuery->getValue('eelastname', 'Smith', 'eefirstname').'</li>');
print('</ul>');
?>
You: "Ok but what if I want to return more than one field value?"
eD: "It's a basic search function and for moment, if wanting to retrieve more than one value you would have to call the function several times. This will be improved in a next version of eDQuery (SFFR592005)."
eD: "To conclude with this topic, remember we talked about two modes 'normal' and 'extended'? In 'normal' mode the query is not executed and you can retrieve the generated SQL statement by calling the getQuery() function. You can also trigger the execution of the query by calling yourself the runQuery() function:"
<?php
require('eDFramework/eDQuery.php');
$database = 'hr';
$arr_select = array('eefirstname', 'eelastname');
$arr_from = array('hr.employee');
$arr_where = null;
$orderBy = 'eefirstname';
$mode = 'normal'; // normal | extended
$debug = false; // true | false
$myQuery = new eDQuery($database, $arr_from, $arr_select, $arr_where, $orderBy, $mode, $debug );
// $myQuery->introspection();
$arr_employees = $myQuery->getRecords();
// Display the generated SQL statement
print($myQuery->getQuery().'<br>');
print('<ul>');
foreach ($arr_employees as $key => $arr_employee) {
print('<li>'.$arr_employee['eefirstname'].' '.$arr_employee['eelastname'].'</li>');
}
print('</ul>');
?>
eD: "Welcome back to our eDQuery class. As for the first eDQuery chapter, this part is quite technical and on top of a basic knowledge of PHP might require a basic understanding of the object paradigm and SQL."
eD: "We will now use eDQuery to build more complex queries. First, let's add a WHERE clause to our previous example. We would like to only retrieve the employee that is called 'Dupont'. The WHERE array is built as an associative array assuming that the most frequent cases are field = value. 'Value' can be a direct value or the content of a variable:"
<?php
require('eDFramework/eDQuery.php');
$database = 'hr';
$arr_select = array('eefirstname', 'eelastname');
$arr_from = array('hr.employee');
$arr_where = array('eelastname' => "'Dupont'");
$orderBy = 'eefirstname';
$mode = 'extended'; // normal | extended
$debug = false; // true | false
$myQuery = new eDQuery($database, $arr_from, $arr_select, $arr_where, $orderBy, $mode, $debug );
$myQuery->introspection();
$arr_employees = $myQuery->getRecords();
print ('<ul>');
foreach ($arr_employees as $key => $arr_employee) {
print ('<li>'.$arr_employee['eefirstname'].' '.$arr_employee['eelastname'].'</li>');
}
print ('</ul>');
?>
eD: "I removed the comments on introspection() so that you can see that the query generated is now containing a where clause. Only 'Alain Dupont' will be returned as a result."
You: "I would like to do the contrary, meaning retrieve all the records that are not 'Dupont', how do I do?"
eD: "eDQuery is building a field = value WHERE clause only if the value is not empty. If empty, eDQuery will use the left part only to build the WHERE clause:"
<?php
require('eDFramework/eDQuery.php');
$database = 'hr';
$arr_select = array('eefirstname', 'eelastname');
$arr_from = array('hr.employee');
$arr_where = array("eelastname <> 'Dupont'" => '');
$orderBy = 'eefirstname';
$mode = 'extended'; // normal | extended
$debug = false; // true | false
$myQuery = new eDQuery($database, $arr_from, $arr_select, $arr_where, $orderBy, $mode, $debug );
$myQuery->introspection();
$arr_employees = $myQuery->getRecords();
print ('<ul>');
foreach ($arr_employees as $key => $arr_employee) {
print ('<li>'.$arr_employee['eefirstname'].' '.$arr_employee['eelastname'].'</li>');
}
print ('</ul>');
?>
eD: "Let's finish with our last example retrieving all the possible information from our HR db with the team, function and employee tables. This only requires to put more value within the SELECT and FROM arrays, set the WHERE clause to link the master and child tables keys and to update the content of our foreach () loop to also display the new values retrieved:"
<?php
require('eDFramework/eDQuery.php');
$database = 'hr';
$arr_select = array('eefirstname', 'eelastname', 'fnname', 'tmname');
$arr_from = array('hr.employee', 'hr.function', 'hr.team');
$arr_where = array('functionid' => 'eefunctionid', 'teamid' => 'eeteamid');
$orderBy = 'eefirstname';
$mode = 'extended'; // normal | extended
$debug = false; // true | false
$myQuery = new eDQuery($database, $arr_from, $arr_select, $arr_where, $orderBy, $mode, $debug );
// $myQuery->introspection();
$arr_employees = $myQuery->getRecords();
print ('<ul>');
foreach ($arr_employees as $key => $arr_employee) {
print ('<li>'.$arr_employee['eefirstname'].' '.$arr_employee['eelastname'].', '.$arr_employee['fnname'].' in the team "'.$arr_employee['tmname'].'"</li>');
}
print ('</ul>');
?>
eD: "You know almost everything about eDQuery now. Just a last advice: I'm usually not using eDQuery directly in my source code but I'm writing 'getters' function instead. If you want to know more about 'getters', a new article will soon be published on the eDreamers.org website. Enjoy!"
eD: "Welcome to our eDMySQLMS class. This chapter has some quite technical content and on top of a basic knowledge of PHP might require a basic understanding of the object paradigm and SQL."
You: "Why have you created eDMySQLMS?"
eD: "In my constant quest for more genericity and efficiency, I've started to centralise more and more all the functions related to database access while trying to make them more and more generic. I've finally been blocked at a stage where, to be even more generic, my functions and classes would have to dynamically retrieve information about the data model and the properties of a database, table and fields. That day, I started writing the source code for eDMySQLMS."
You: "So, what is eDMySQLMS providing me?"
eD: "eDMySQLMS automatically build the datamodel of a database from table down to fields properties. It delivers the results of this database introspection in easy to handle associative arrays and also provide a search function to easily find fields and tables inside a db."
You: "How is that working?"
eD: "By mixing functions offered by either PHP, MySQL or SQL in order to obtain all the information eDMySQLMS needs, but let's see that with a concrete example.
You should have read the chapter about eDQuery. If no, it's not too late because you'll find there the needed SQL code to create a new db and some tables, fields and records that we will also use here.
So let's come back to our HR database and the famous John Smith and Alain Dupont. As the other components of the eDFramework, to be able to create a new eDMySQLMS instance, you require the eDMySQLMS.php file into your script. Assuming that eDQuery is located in the eDFramework sub-folder of the folder where your script is located this would give:"
<?php
require('eDFramework/eDMySQLMS.php');
?>
eD: "Let's create a new instance. You'll need to specify 4 parameters: the mode, a target db (optional), a target table (optional) and the debug mode. The mode is, as for eDQuery, 'normal' just create the instance and do nothing. It's up to you to call the functions that you need. The 'extended' mode launches the buildSchema() function which build your data model. If no db no table names are provided, the schema of all the databases and tables available on the server will be build. If you provide the name of a specific db without a table name, the schema of this db is built etc. The only combination that is not accepted is a table name without a db name.
The HR database is not too big so our first example will be building the full schema of the HR DB. Attention: depending on the size of your datamodel and the number of db to be analysed running eDMySQLMS can take up to several seconds.
eDMySQLMS inherits from the eDUtilities utility class and the introspection() function can be used to see the results of the building of a new eDMySQLMS instance:"
<?php
require('eDFramework/eDMySQLMS.php');
$mySchema = new eDMySQLMS('extended', 'hr', null, 'false');
$mySchema->introspection();
?>
eD: "Three tables are created: $arr_dbTables, $arr_tablesFields and $arr_fieldsProperties, respectively containing the list of db with their tables, the list of tables with their fields and the list of fields with their properties. In 'extended' mode, the fields properties are retrieved automatically. In 'normal' mode, the buildFieldList() method can be called with the $getProperties parameter to false. In both 'normal' and 'extended' mode, you will have to call the getters methods getDBTables(), getTablesFields(), getFieldsProperties() in order to retrieve the related arrays. Let's illustrate it by calling the constructor in 'normal' mode, turning off the introspection() method, getting the arrays and displaying them using a foreach () loop:"
<?php
require('eDFramework/eDMySQLMS.php');
$mySchema = new eDMySQLMS('normal', 'hr', null, 'false');
// $mySchema->introspection();
$arr_DBTables = $mySchema->getDBTables();
$arr_TablesFields = $mySchema->getTableFields();
$arr_FieldsProperties = $mySchema->getFieldsProperties();
echo '<ul>';
foreach ($arr_DBTables as $db => $table) {
echo '<li>n'.$db.' - '.$table;
}
echo '</ul>';
?>
eD: "We can conclude with the search() function of eDMySQLMS. This function will allow to search for the presence of a database, table or field. The function returns an array containing the database, table and field name if the searched object has been found. If you search a db, the array will be empty if not found or containing the name of the db on index 0 if found. If you look for a field, if found the array will contain the field name, the name of the table in which the field has been found and the name of the db in which lies this table. The search() function relies on the in_array() PHP function, refer to the PHP documentation for more information about this function. Let's try to use the search function to look for a field name 'eelastname':"
<?php
require('eDFramework/eDMySQLMS.php');
$mySchema = new eDMySQLMS('extended', 'hr', null, 'false');
$arr_ = $mySchema->search('field', 'eelastname');
if (sizeof($arr_) ) {
echo 'The field '.$arr_[2].' has been found in the table '.$arr_[1].'.<br>';
}
?>
eD: "You know everything about the use of eDMySQLMS! It's now up to you and your imagination to find ways of using it. In the eDreamers universe, eDMySQLMS is used by the eDGetters and eDObject components."
1. The preferred way of getting help and support related to eDFramework is via the SourceForge.net website where informations and forums can be found.
2. You can also submit "Support Requests" via the same website if you don't find an answer in the documents and forums mentionned above.
3. Last resort is the help@edreamers.org email address that you can use to request some help. All messages sent to this address will be translated into support request on the SourceForge.net website so if you have access to the internet prefer the option 2 to not unnecessarily delay the process.