GenericDbList

Name

GenericDbList -- Aggregate class of GenericDb objects supplying operations for database interaction

Synopsis

 require ('GenericDbList.inc'); 

Description

GenericDbList is basically a class that operates with an array of GenericDb objects. It provides operations for loading multiple database objects into instances of GenericDb class. There are also array manipulating operations present.

To determine the name of the database table and the attributes for building SQL queries and the database access container in order to execute select queries, GenericDbList instance is supplied with a sample object of subclass of GenericDb. The sample objects database access container (PHPLibs Db_Sql extended) is used to connect to the DBMS.

Source listing

class GenericDbList
{
	// Array of loaded db objects and cursor into this array
	// used by next().
	var $a_member = false;
	var $cursor = 0;
	
	// Sample DB object, instance of subclass of GenericDb, to determine
	// table name and fieldnames to load.
	var $dbs;
	
	// Loads array of p_db type db objects
	function GenericDbList($db);

	/* get and set the list of db objects */
	function list_get();
	function list_set(& $list );
    

The paramether to the constructor is the sample instance of GenericDb class.

	// Load the list from database, return number of objects loaded.
	// Parameter $p_sql is SQl clause starting with FROM.
	function loadSql($p_sql)

        /* takes sql query and stores the result set, returns
           the number of rows retrieved */
        function ProcessQuery($sql);

	// Return number of elements in list.
	function member_count();

	// Return another reference to the next element in 
	// 				list, false if over the end.
	function & next();

	function ResetCursor ();
    

Before passing through the list of aggregate objects, one should reset the cursor unless this operation returna false where it shouldn't.

	/*
	 * return object ref of member a_member that has ID $itemID
	 * return false if a_member contains no object with such ID.
	 */
	function & ObjectWithID ( $itemID );
	/*
	 * Find out element index with ID $itemID at member a_member
	 * and remove element using it
	 */
	function RemoveWithID ( $itemID );
	/*
	 * return index of element that has ID $itemID
	 * if none matches, -1
	 */
	function IndexOfElementWithID ( $itemID );
    

Example

Example 6-1. RequestDbList

We have two database tables, user and request. User has service requests that can be managed by means of web interface. When user logs on, his service requests are fetched by an instance of RequestDbList.

class RequestDbList extends GenericDbList
{
	function RequestDbList ( $p_db ) 
        {
                $this->GenericDbList ( $p_db );
        }
	function fetchByUserID ( $p_ID ) 
	{
		$s_cl = "FROM request WHERE user_ID = $p_ID";
		return $this->loadSql ( $s_cl );
	}
}
      

The constructor serves the need to propagate the sample database object instance. fetchByUserID is used to create a list of database object instances using the user ID. The class is used as follows.

                // sample Request object for cloning
                $db_r = new RequestDb (new My_DbSql);

                // list of requests; fetch users alerts
                $dbl_r = new RequestDbList ( $db_r );
                $dbl_r->fetchByUserID ( $user->ID );
      

My_DbSql instance takes care of talking to DBMS, RequestDb instance reflects the service request database object. After the fetchByUserID method, $dbl_r contains all service requests for the service user. Now the list object can be traversed as follows.

		$dbl_r->ResetCursor ();
		while ($db_r = & $dbl_r->next ()) { ... }