Object-Relational Mapping

Classes
class	DataItemException
class	DataNotFoundException
class	ExclusionFilter
	Used to place a filter on the contents of a DataItem-derived object. More...
class	InclusionFilter
	Used to place a filter on the contents of a DataItem-derived object. More...
class	AbstractDataItem
	Abstract base class for all DataItem implementations. More...
class	CompositeDataItem
class	DataItem
	DataItem is the generic base class for database mapped classes. More...
class	DataItemFieldComparator
	Simple field comparator to support sorting arrays of DataItems by the values in a specified field. More...
class	GroupedQuery
class	IndexedQuery
class	DataItemIterator
	DataItemIterator is a memory-efficient iterator class that can be used when rendering large data sets. More...
class	IteratedQuery
	IteratedQuery provides a memory-efficient way to query and return large data sets. More...
class	JoinResult
	JoinResult is an empty placeholder class. More...
class	JoinResultIterator
class	AbstractJoin
	AbstractJoin is the abstract base class from which concrete join classes can be derived in order to provide support for different styles of relational join. More...
class	InnerJoin
	This class is used to programmatically perform inner join queries across multiple objects. More...
class	LeftOuterJoin
class	JSONQuery
class	AbstractPivotQuery
	AbstractPivotQuery provides the common base class for the shaped pivot query classes PivotQuery, IndexexPivotQuery and GroupedPivotQuery. More...
class	PivotQuery
	Standard Pivot Query, with support for paging. More...
class	IndexedPivotQuery
	Run a pivot query and return the results indexed by a selected field. More...
class	GroupedPivotQuery
	Performs a pivot query against the database, returning an array of arrays of PivotItems, grouped by a particular field. More...
class	PivotItem
	PivotItems are dynamically constructed DataItems that map the results of PivotQueries. More...
class	PivotTableHelper
	The PivotTableHelper class provides support for configuring display tables (DataListViews and GroupedDataListViews) dynamically, based upon the structure of a pivot query. More...
class	AbstractQuery
class	Query
	Query provides an object-oriented interface for database queries. More...
class	DataTransaction
	The DataTransaction class wraps the underlying database's transaction model. More...

Functions
	querySingle ($class)
	Performs a query against the database and returns a matching singleton object. More...
	queryValue ($class, $func)
	Query the database to calculate an aggregate value. More...
	reindexList ($list, $field, $autoPromote=true)
	Reindex an indexed or grouped query result by a different field. More...
	regroupList ($list, $field)
	Regroup an indexed or grouped query result by a different field. More...
	removeDuplicates ($list, $field="")
	Remove duplicate DataItems from a list, based on the value of a field. More...
	sortList (&$list, $field)
	Sorts an array of DataItems based on the values in the specified field. More...
	updateSortOrder ($class, $field="sort_order", $params=null)
	Utility method to update sort order for the selected class of objects based on an array that maps primary keys to sort order values. More...
	toXML ($tag, $objects, $header=null)
	toJSON ($items)
	toJSONGrouped ($items)
	toJSONIndexed ($items)
	fromJSON ($class, $json)
	displayFieldAsList ($items, $field, $separator=", ")
	formatItems ($items, $template, $separator="")
	Format a list of DataItems using the specified templated. More...
	extractItems ($items, $indexFormat, $valueFormat)
	extractFieldValues ($items, $field)
	Extract the field values for the specified field from a list of DataItems. More...
	extractIndexedFieldValues ($items, $field)
	Extract the field values for the specified field from a list of DataItems and return them in an array indexed by the primary key values of the source DataItems. More...
	itemExists ($class, $key)
	Utility method to test for the existence of a DataItem record in the database. More...
	findItem ($items, $field, $value)
	Find the first item in the array that matches the supplied value for the specified field. More...
	findItemIndex ($items, $field, $value)
	Find the index of the first item in the array that matches the supplied value for the specified field. More...
	restoreHTML ($text)
	dumpCSV ($class, $items, $filepath, $filter=null, $append=false)
	Dump a raw representation of a list of DataItems to CSV (one column per field, default format only) More...
	groupedQuery ($class)
	Performs a query against the database, returning an array of arrays of DataItem objects of the specified class, grouped by a particular field. More...
	indexedQuery ($class)
	Performs a query against the database, returning an array of DataItem objects of the specified class, indexed by a particular field. More...
	iteratedQuery ($class)
	iteratedQuery() provides a memory-efficient way to query and return large data sets. More...
	extractJoinResults ($class, $results)
	Extracts the specified object from the combined join results, returning an array of the specified objects n the same order they were returned by the join query. More...
	extractGroupedJoinResults ($class, $results)
	query ($class)
	Performs a query against the database, returning an array of DataItem objects of the specified class. More...

Variables
const	SerializeRelations 1
const	SerializeDirectRelations 2
const	ProtectHTML 4

Detailed Description

Function Documentation

displayFieldAsList()

displayFieldAsList	(		$items,
			$field,
			$separator = ", "
	)

Definition at line 2163 of file data_item.inc.

{
     return formatItems($items, "{".$field."}", $separator);
}    

dumpCSV()

dumpCSV	(		$class,
			$items,
			$filepath,
			$filter = null,
			$append = false
	)

Dump a raw representation of a list of DataItems to CSV (one column per field, default format only)

Parameters

$class	class name of the items to be dumped
$items	the items to dump
$filepath	the output file path

Definition at line 2304 of file data_item.inc.

{
     $obj = new $class;
     $obj->filter = $filter;
 
     $fields = $obj->getFieldArray();
     
     if ($append)
     {
          $fp = fopen($filepath, "a");
     }
     else
     {
          $fp = fopen($filepath, "w");  
          fputcsv($fp, $fields);
     }
     
     foreach($items as $item)
     {
          $vals = array();
          foreach($fields as $field)
          {
               $vals[] = $item->get($field);
          }
          fputcsv($fp, $vals);
     }
     fclose($fp);
}

extractFieldValues()

extractFieldValues	(		$items,
			$field
	)

Extract the field values for the specified field from a list of DataItems.

Parameters

$items	the DataItems on which to perform the extraction
$field	the name of the field to extract

Returns

array an array of the field values in the same order as the presented DataItem list.

Definition at line 2209 of file data_item.inc.

{
     $out = array();
     foreach($items as $item)
     {
          $out[] = $item->get($field);
     }
     return $out;
}

extractGroupedJoinResults()

extractGroupedJoinResults	(		$class,
			$results
	)

Definition at line 1098 of file join.inc.

{
     $arr = array();
     
     if (!$results) return $arr;
     
     foreach(array_keys($results) as $key)
     {
          $arr[$key] = extractJoinResults($class, $results[$key]);
     }
     
     return $arr;
}

extractIndexedFieldValues()

extractIndexedFieldValues	(		$items,
			$field
	)

Extract the field values for the specified field from a list of DataItems and return them in an array indexed by the primary key values of the source DataItems.

Parameters

$items	the DataItems on which to perform the extraction
$field	the name of the field to extract

Returns

array an array of the field values indexed by the primary key values from the DataItem list.

Definition at line 2226 of file data_item.inc.

{
     $out = array();
     foreach($items as $item)
     {
          $out[$item->get($item->getPrimaryKey())] = $item->get($field);
     }
     
     return $out;
}

extractItems()

extractItems	(		$items,
			$indexFormat,
			$valueFormat
	)

Definition at line 2192 of file data_item.inc.

{
     $list = array();
     foreach($items as $item)
     {
          $list[$item->format($indexFormat)] = $item->format($valueFormat);
     }
 
     return $list;
}

extractJoinResults()

extractJoinResults	(		$class,
			$results
	)

Extracts the specified object from the combined join results, returning an array of the specified objects n the same order they were returned by the join query.

Parameters

unknown_type	$class	the class of objects to extract
unknown_type	$results	an array containing the results of a join query.

Returns

unknown an array of the specified objects extracted from the join query results array.

Definition at line 1084 of file join.inc.

{
     $arr = array();
     
     if (!$results) return $arr;
     
     foreach($results as $result)
     {
          $arr[] = $result->$class;
     }
     
     return $arr;
}

findItem()

findItem	(		$items,
			$field,
			$value
	)

Find the first item in the array that matches the supplied value for the specified field.

Parameters

array	$items	the items to search
string	$field	the name of the field to match
mixed	$value	the value that must be matched

Returns

DataItem the first matching object, or null if no match is found

Definition at line 2261 of file data_item.inc.

{
     foreach($items as $item)
     {
          if ($item->get($field) == $value) return $item;
     }
     
     return null;
}

findItemIndex()

findItemIndex	(		$items,
			$field,
			$value
	)

Find the index of the first item in the array that matches the supplied value for the specified field.

Parameters

array	$items	the items to search
string	$field	the name of the field to match
mixed	$value	the value that must be matched

Returns

mixed the index of the first matching object, or false if no match was found

Definition at line 2279 of file data_item.inc.

{
     $idx = 0;
     
     foreach($items as $item)
     {
          if ($item->get($field) == $value) return $idx;
          ++$idx;
     }
     
     return false;
}

formatItems()

formatItems	(		$items,
			$template,
			$separator = ""
	)

Format a list of DataItems using the specified templated.

The list is returned as a string with the specifed separator between records.

Parameters

array	$items	the DataItems to format
string	$template	the format template
string	$separator	the separator to use between records

Returns

string

Definition at line 2176 of file data_item.inc.

{
     $list = "";
     $first = true;
     
     foreach($items as $item)
     {
          if (!$item) continue;
          if (!$first) $list .= $separator;
          $list .= $item->format($template);
          $first = false;
     }
     
     return $list;
}

fromJSON()

fromJSON	(		$class,
			$json
	)

Definition at line 2138 of file data_item.inc.

{
     $data = json_decode($json);
     
     if (is_object($data))
     {
          $obj = new $class;
          $obj->copy($data);
          return $obj;
     }
     else if (is_array($data))
     {
          foreach($data as $datum)
          {
               $obj = new $class;
               $obj->copy($datum);
               $out[] = $obj;
          }
          
          return $out;
     }
     
     return null;
}

groupedQuery()

groupedQuery

(

$class

)

Performs a query against the database, returning an array of arrays of DataItem objects of the specified class, grouped by a particular field.

If the indexing field has unique values, indexedQuery() might be more appropriate.

Parameters

string	$class	the name of the class of objects to query
string	$constraints	optional constraint clause to apply to the query in the form "WHERE ... [ORDER BY ...]"
string	$field	optional the name of the field by which to group the results
object	$filter	optional filter used to select subset of the database fields for the result (See InclusionFilter and ExclusionFilter)

Definition at line 175 of file grouped_query.inc.

{
     $field = $prototype->primary_key;
     
     $filter = null;
     
     $query = new GroupedQuery($class);
     
     if (func_num_args() > 1)
     {
          $query->constraints(func_get_arg(1));
          
          if (func_num_args() > 2)
          {
               $query->groupBy(func_get_arg(2));
               
               if (func_num_args() > 3)
               {
                    $query->filter(func_get_arg(3));
               } 
          }
     }
     
     return $query->execute();
}

indexedQuery()

indexedQuery

(

$class

)

Performs a query against the database, returning an array of DataItem objects of the specified class, indexed by a particular field.

If more than one item is found that matches the same value of the indexing field, the results entry is promoted to an array automatically. However, in cases where this is common, using groupedQuery() might simplify your calling code.

Parameters

string	$class	the name of the class of objects to query
string	$constraints	optional constraint clause to apply to the query in the form "WHERE ... [ORDER BY ...]"
string	$field	optional the name of the field by which to index the results
object	$filter	optional filter used to select subset of the database fields for the result (See InclusionFilter and ExclusionFilter)

Definition at line 145 of file indexed_query.inc.

{
     $field = $prototype->primary_key;
     $filter = null;
     
     $query = new IndexedQuery($class);
     
     if (func_num_args() > 1)
     {
          $query->constraints(func_get_arg(1));
          
          if (func_num_args() > 2)
          {
               $query->indexBy(func_get_arg(2));
               
               if (func_num_args() > 3)
               {
                    $query->filter(func_get_arg(3));
               } 
          }         
     }
 
     return $query->execute();
}

itemExists()

itemExists	(		$class,
			$key
	)

Utility method to test for the existence of a DataItem record in the database.

Parameters

string	$class	the class of the DataItem
integer	$key	the primary key value for the DataItem

Returns

boolean true if a record for the object exists in the database, false otherwise

Definition at line 2243 of file data_item.inc.

{
     $obj = new $class;
     if (!$obj instanceof DataItem)
     {
          return false;       
     }
     $obj->set($obj->getPrimaryKey(), $key);
     return $obj->exists();
}

iteratedQuery()

iteratedQuery

(

$class

)

iteratedQuery() provides a memory-efficient way to query and return large data sets.

Whereas the default query() function and the indexedQuery() and groupedQuery() functions all pull the full result set into memory when the query is executed, iteratedQuery() leaves the connection to the database open and retrieves the results one row at a time. The results are returned wrapped in a DataItemIterator, allowing them to be used in foreach(...) statements, etc.

One limitation of the returned resultset is that count() will not return an accurate count of the number of items, since this cannot be determined reliably until all items have been read. In general it is recommend that iteratedQuery() only be used in situations where the result would take up too much memory to be processed using a standard Query object.

Parameters

string	$class	the name of the class of objects to query
string	$constraints	optional constraint clause to apply to the query in the form "WHERE ... [ORDER BY ...]"
object	$filter	optional filter used to select subset of the database fields for the result (See InclusionFilter and ExclusionFilter)

Definition at line 239 of file iterated_query.inc.

{
     $query = new IteratedQuery($class);
     
     if (func_num_args() > 1)
     {
          $query->constraints(func_get_arg(1));
          
          if (func_num_args() > 2)
          {
               $query->filter(func_get_arg(3));
          }         
     }
 
     return $query->execute();
}

query()

query

(

$class

)

Performs a query against the database, returning an array of DataItem objects of the specified class.

Parameters

string	$class	the name of the class of objects to query
	$constraints	optional constraint clause to apply to the query in the form "WHERE ... [ORDER BY ...]"
	$filter	optional filter to apply to the query
	$page	optional page number to retrieve
	$size	optional size of pages

Definition at line 373 of file query.inc.

{
     $query = new Query($class);
 
     if (func_num_args() > 1)
     {
          $idx = 1;
          
          if (is_object(func_get_arg(1)))
          {
               $query->filter($filter);
               ++$idx;
          }
          
          if (is_array(func_get_arg($idx)))
          {
               $query->params(func_get_arg($idx++));
          }
          
          if (func_num_args() > $idx)
          {
               $query->constraints(func_get_arg($idx));
               
               if (func_num_args() == $idx + 3)
               {
                    $query->page(func_get_arg($idx + 1), func_get_arg($idx + 2));
               }
          }
     }
     
     return $query->execute();
}

querySingle()

querySingle

(

$class

)

Performs a query against the database and returns a matching singleton object.

If the query returns more than one object, an error is thrown.

Parameters

string	$class	the class name of the object to query
string	$constraints	optional constraint clause to apply to the query in the form "WHERE ... [ORDER BY ...]"

Definition at line 1810 of file data_item.inc.

{
     $constraints = "";
     
     if (func_num_args() > 1)
     {
          $constraints = func_get_arg(1);
     }
     
     $result = query($class, $constraints);
     
     if (count($result) > 1)
     {
          throw new DataItemException("Ambiguous singleton query");
     }
     
     if (count($result) == 1)
     {
          return $result[0];
     }
     
     return null;   
}

queryValue()

queryValue	(		$class,
			$func
	)

Query the database to calculate an aggregate value.

The database table associated with the specified class is used as the source for the data.

Parameters

string	$class	the class name of the object to query
string	$func	the value or function to retrieve
string	$constraints	optional constraint clause to apply to the query

Definition at line 1842 of file data_item.inc.

{
     $constraints = "";
     $value = null;
     
     if (func_num_args() > 2)
     {
          $constraints = func_get_arg(2);
          
          if (func_num_args() > 3)
          {
               $value = func_get_arg(3);
          }
     }
 
     $prototype = new $class;
     
     if ($constraints == "") $constraints = "WHERE 1=1"; //TODO - tidy this up some day
     $constraints .= " ".$prototype->getIdentityConstraint();
     
     $query = "SELECT $func as result FROM {$prototype->table} $constraints";
     
     trace($query, 3);
     
     try
     {
          $db = ConnectionManager::getConnection();
          
          $result = $db->prepare($query);
          $result->execute();
          
          if ($row = $result->fetch())
          {
               $value = $row['result'];
          }
 
          unset($result);
     }
     catch(PDOException $e)
     {
          $err = "queryValue() failed - " . $e->getMessage();
          trace($err, 2);
          throw new DataItemException($err);
     }
     
     return $value;
}

regroupList()

regroupList	(		$list,
			$field
	)

Regroup an indexed or grouped query result by a different field.

Parameters

array	$list	an array of DataItem-derived objects, as returned by query(), indexedQuery() or groupedQuery()
string	$field	the field by which to regroup the list

Definition at line 1948 of file data_item.inc.

{
     $result = array();
     
     foreach($list as $elt)
     {
          if (is_array($elt))
          {
               foreach ($elt as $e)
               {
                    $result[$e->$field][] = $e;
               }
          }
          else
          {
               $result[$elt->$field][] = $elt;
          }
     }
     
     return $result;
}

reindexList()

reindexList	(		$list,
			$field,
			$autoPromote = true
	)

Reindex an indexed or grouped query result by a different field.

Parameters

array	$list	an array of DataItem-derived objects, as returned by query(), indexedQuery() or groupedQuery()
string	$field	the field by which to reindex the list

Definition at line 1898 of file data_item.inc.

{
     $result = array();
     
     foreach($list as $elt)
     {
          if (is_array($elt))
          {
               foreach($elt as $e)
               {
                    if (array_key_exists($e->$field, $result))
                    {
                         if (!is_array($result[$e->$field]))
                         {
                              $result[$e->$field] = array($result[$e->$field]);
                         }
                         $result[$e->$field][] = $e;
                    }
                    else
                    {
                         $result[$e->$field] = $e;
                    }
               }
          }
          else
          {
               if (array_key_exists($elt->$field, $result) && $autoPromote)
               {
                    if (!is_array($result[$elt->$field]))
                    {
                         $result[$elt->$field] = array($result[$elt->$field]);
                    }
                    $result[$elt->$field][] = $elt;
               }
               else
               {
                    $result[$elt->$field] = $elt;
               }
          }
     }
     
     return $result;
}

removeDuplicates()

removeDuplicates	(		$list,
			$field = ""
	)

Remove duplicate DataItems from a list, based on the value of a field.

If no field is specified, the items' primary key is used. It is assumed that all the objects in the list are of the same class. A filtered copy of the list is returned. The original list is left unchanged.

Parameters

array	$list	the list of DataItems from which duplicates are to be removed
string	$field	the name of the field to use to determine duplicity.

Returns

a filtered list containing no duplicates.

Definition at line 1981 of file data_item.inc.

{
     if (count($list) == 0) return $list;
     
     if ($field == "")
     {
          $field = $list[0]->primary_key;
     }
     
     $found = array();
     $filtered = array();
     foreach($list as $item)
     {
          if (!array_key_exists($item->$field, $found))
          {
               $filtered[] = $item;
          }
          
          $found[$item->$field] = true;
     }
     
     return $filtered;
}

restoreHTML()

restoreHTML

(

$text

)

Definition at line 2292 of file data_item.inc.

{
     $v = str_replace( array("[_[OPENTAG]_]", "[_[CLOSETAG]_]", "[_[AMPERSAND]_]"), array("<", ">", "&"),  $text);
     return $v;
}

sortList()

sortList	(	&	$list,
			$field
	)

Sorts an array of DataItems based on the values in the specified field.

Parameters

array	$list	an array of DataItems
string	$field	the field to sort by

Returns

the sorted list

Definition at line 2030 of file data_item.inc.

{
     $cmp = new DataItemFieldComparator($field);
     
     usort($list, array($cmp, "compare"));
     
     return $list;
}

toJSON()

toJSON

(

$items

)

Definition at line 2102 of file data_item.inc.

{
     $out = array();
     
     foreach($items as $item)
     {
          $out[] = $item->toJSON();
     }
     
     return "[".implode(", ", $out)."]";
}

toJSONGrouped()

toJSONGrouped

(

$items

)

Definition at line 2114 of file data_item.inc.

{
     $out = array();
 
     foreach($items as $key => $group)
     {
          $out[] = "\"$key\": ".toJSON($group);
     }
     
     return "{".implode(", ", $out)."}";
}

toJSONIndexed()

toJSONIndexed

(

$items

)

Definition at line 2126 of file data_item.inc.

{
     $out = array();
     
     foreach($items as $key => $item)
     {
          $out[] = "\"$key\": ".$item->toJSON();
     }
     
     return "{".implode(", ", $out)."}";
}

toXML()

toXML	(		$tag,
			$objects,
			$header = null
	)

Definition at line 2080 of file data_item.inc.

{
     global $config;
     
     if ($header === null)
     {
          $default_charset = $config["default_charset"];
          if (!$default_charset) $default_charset = "iso-8859-1";
          $header = "<?xml version=\"1.0\" encoding=\"{$default_charset}\"?>";
     }
     
     $xml = "$header\n<$tag>\n";
     
     foreach($objects as $obj)
     {
          $xml .= $obj->toXML(1);
     }
     $xml .= "</$tag>\n";
     
     return $xml;
}

updateSortOrder()

updateSortOrder	(		$class,
			$field = "sort_order",
			$params = null
	)

Utility method to update sort order for the selected class of objects based on an array that maps primary keys to sort order values.

This method is designed to make drag and drop sorting easier to implement.

Parameters

string	$class	the class of DataItem that is being resorted
string	$field	the field that contains the sort order value

Definition at line 2046 of file data_item.inc.

{
     if (!$params) $params = $_GET;
     $obj = new $class;
     $pk = $obj->getPrimaryKey();
     
     $tx = new DataTransaction();
     
     try
     {
          foreach($params[$pk] as $id => $sort_order)
          {
               checkNumeric($id);
               checkNumeric($sort_order);
     
               $item = new $class();
               $item->joinTransaction($tx);
     
               $item->filter = new InclusionFilter($pk, $field);
     
               $item->load($id);
               $item->set($field, $sort_order);
               $item->save();
          }
     
          $tx->commit();
     }
     catch(Exception $e)
     {
          $tx->rollback();
          throw $e;
     }
}

Variable Documentation

ProtectHTML

const ProtectHTML 4

Definition at line 153 of file abstract_data_item.inc.

SerializeDirectRelations

const SerializeDirectRelations 2

Definition at line 152 of file abstract_data_item.inc.

SerializeRelations

const SerializeRelations 1

Definition at line 151 of file abstract_data_item.inc.