Introduction

Introduction --  What DB_DataObject can do

Introduction

Warning

Zend Optimizer: due to a bug in the optimizer, you will have to either reduce the optimization level, or define the constant DB_DATAOBJECT_NO_OVERLOAD = 0 otherwise PHP may segfault

Pass by Reference, due to a unfixable bug in PHP4, you can not use overload with pass-by-reference arguments (It works OK in PHP5), If you need pass-by-reference, define the constant DB_DATAOBJECT_NO_OVERLOAD = 0

DB_DataObject is a SQL Builder and Data Modeling Layer built on top of PEAR::DB. Its main purpose is to

So what does that mean in english? Well, if you look around at some of the better written PHP applications and frameworks out there, you will notice a common approach to using classes to wrap access to database tables or groups. The prime example of this is the person object, which would frequently look something like this.

The key benifit of this approach is that you are grouping similar actions on a single table in one place, and are more likely to spot duplicated code (eg. two methods that do similar things). You will also notice the global $db variable used here - the fact is that most of the time you will use a common database connection for all your classes, so how should this be dealt with?

The next step on this road is to use the objects variables as a storage mechanism.

As you can see, the current row of data is now stored in the Data Container, and additional methods can be added to manipulate the data in the object or even call other related objects (eg. tables relationships in databases)

As a next step, why not utilize the member variables to perform searches or gets on the database.

As you can see, by assigning values to the object before the find method is called, you can set conditions for the query. DB_DataObjects behaves in a similar way to this, however, you can also add more conditions with the whereAdd() method, or restrict the selection using the selectAdd() method.

Obviously you can carry on down this road and create lots of little containers for each table in your database, and all the code will nicely relate to each table. However, you can see from the examples above that all classes are likely to end up with a common set of methods.

So to improve on this, DB_DataObject was born, it started life as an common answer to the issues above, however as most problems grow in complexity as the problem is examined in finer detail, so has DataObjects. It has grown to include

So what do my classes look like?

Example 33-4. At last some real DataObject Code..

// this is the common configuration code - place in a general site wide include file.
  
    // this  the code used to load and store DataObjects Configuration. 
    $options = &PEAR::getStaticProperty('DB_DataObject','options');
    
    // the simple examples use parse_ini_file, which is fast and efficient.
    // however you could as easily use wddx, xml or your own configuration array.
    $config = parse_ini_file('example.ini',TRUE);
    
    // because PEAR::getstaticProperty was called with and & (get by reference)
    // this will actually set the variable inside that method (a quasi static variable)
    $options = $config['DB_DataObject'];




     // this is normally contained in your DataObjects file (autogenerated by the generator)

    require_once 'DB/DataObject.php';
    
    
    // by extending the base class DB_DataObject - you inherit all the common methods defined in it.
    
    class DataObjects_Person extends  DB_DataObject {
        
        var $id; // this is a primary id (it's specified in a config file - explained later)
        var $name;
        var $friend;
        
        // this is a simple function to get the persons friends..?
        
        function getFriends()
        {
            
            $personObject = $this->factory('person');
            
            // look for all people with their friend number matching this persons id.
            $personObject->friend = $this->id;
            
            // do the select query.
            $personObject->find();
            $array = array();
            
            // fetch the results into the object.
            while ($personObject->fetch()) {
                // use the clone to copy - not really needed but get used to it for PHP5

                $array[] = clone($personObject);
            }
            // return the results.
            return $array;
            
        }
    }
    
    
    
    // and this goes on your display code 
    
    // create a new person class..
    $person = DB_DataObject::Factory('person');
    
    // get the person using the primary key.
    $person->get(12);
    // get the friends.
    $friends = $person->getFriends();
    
    //  DB_DataObjects is designed to make print_r useable to debug your applications.
    print_r($friends);

The above example illustrates the components of the DB_DataObject, by setting the options, all the core objects will be able to auto load the data definitions from a generated ini file, and know how to access the database. (multiple databases are supported - see section on configuration)

The class definition illustrates how you only need to define the data specific code in your class, ignoring all the common methods, along with showing one of the methods for retrieveing multiple rows of data.

The later half illustrates how to query and get the result for a single row. The $person->get() would connect to the database, perform the query, fetch the result and assign the objects variables to the data returned from the query.

As a general rule of thumb method names are usually the same as the SQL statement they relate to.