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...

Inheritance diagram for AbstractJoin:

Public Member Functions
	add ($class)
	Adds a class to the join definition. More...

	setFilter ($class, $filter)
	Sets an InclusionFilter or ExclusionFilter on the specified class. More...

	constrain ($class, $constraint)
	Sets a query constraint on the given class. More...

	excludeKeyFromJoin ($class, $key)
	By default joins are generated following the "most restrictive search" principle. More...

	xref ($xref, $xrefFieldMaps=null)
	Adds a cross-reference class to the join definition. More...

	pseudo ($class, $items, $indexField)
	Registers a class and indexed array as a pseudo-join item. More...

	generateQuery ($constraint="", $count=false)

	count ($constraints="", $countExpr=true)

	query ($constraints="", $page=-1, $size=-1)
	Performs a query against the database returning an array of JoinResult objects. More...

	iteratedQuery ($constraints="")
	Performs a query against the database returning an iterator of JoinResult objects. More...

	indexedQuery ($constraints="", $indexBy="")
	Performs a query against the database, returning an array of DataItem objects of the specified class, indexed by a particular field. More...

	groupedQuery ($constraints="", $indexBy="")
	Performs a query against the database, returning an array of arrays of DataItem objects of the specified class, grouped by a particular field. More...

Public Attributes
	$classes = array()
	The names of the DataItem classes being joined. More...

	$protos = array()
	Prototype instances of the DataItem classes being joined. More...

	$xrefs = array()
	Cross-reference classes (i.e. classes that are part of the join, but not the result) More...

	$xrefFieldMaps = array()
	Cross-reference field map (to support cross-referencing through fields with differing names) More...

	$aliases = array()
	Field aliases for output. More...

	$xrefAliases = array()
	Cross-reference table aliases. More...

	$constraints = array()
	Class-specific constraints add via the constrain() method. More...

	$unique = false
	true to output distinct rows only More...

	$tag = "join"
	XML tag name. More...

	$excludedKeys = array()

	$pseudos = array()
	Pseudo-join lookup tables. More...

Detailed Description

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.

Author: andy

Definition at line 232 of file join.inc.

Member Function Documentation

◆ add()

AbstractJoin::add ( $class )

Adds a class to the join definition.

Classes added using this method are included in the eventual result set.

Parameters

string	$class	the name of the class to add to the join
Filter	$filter	(optional) InclusionFilter or ExclusionFilter object defining the sub-set of fields to include

Definition at line 256 of file join.inc.

      {
           $this->classes[] = $class;
           
           $this->protos[$class] = new $class;
           
           if (func_num_args() > 1)
           {
                $filter = new InclusionFilter();
  
                if (func_get_arg(1) !== false)
                {
                     for($i = 1; $i < func_num_args(); ++$i)
                     {
                          $filter->add(func_get_arg($i));
                     }
                }
                          
                $this->protos[$class]->filter = $filter;
           }
           
           return $this;
      }

◆ constrain()

AbstractJoin::constrain	(	$class,
		$constraint
	)

Sets a query constraint on the given class.

Parameters

string	$class	the class to be constrained
string	$constraint	the SQL constraint to be applied

Definition at line 296 of file join.inc.

      {
           $this->constraints[$class] = $constraint;
      }

◆ count()

AbstractJoin::count	(	$constraints = `""`,
		$countExpr = `true`
	)

Definition at line 356 of file join.inc.

      {
           $query = $this->generateQuery($constraints, $countExpr);
           try
           {
                $db = ConnectionManager::getConnection();
                     
                $result = $db->prepare($query);
                $result->execute($this->params);
                     
                if ($row = $result->fetch())
                {
                     $value = $row['result'];
                }
           
                unset($result);
           }
           catch(PDOException $e)
           {
                throw FakoliException($e->getMessage());
           }
           
           return $value;      
      }

◆ excludeKeyFromJoin()

AbstractJoin::excludeKeyFromJoin	(	$class,
		$key
	)

By default joins are generated following the "most restrictive search" principle.

This means that all matching foreign key/primary key pairs are used in the join constraint. You can use this method to override this behavior for a member of the join, specifying that a given key should not be used as part of the join constraint.

Parameters

string	$class
string	$key

Definition at line 311 of file join.inc.

      {
           if (!isset($this->excludedKeys[$class]))
           {
                $this->excludedKeys[$class] = array();
           }
           
           $this->excludedKeys[$class][$key] = true;
           
           trace("*** Excluding $key on $class", 3);
           return $this;
      }

◆ generateQuery()

AbstractJoin::generateQuery	(	$constraint = `""`,
		$count = `false`
	)

abstract

Reimplemented in LeftOuterJoin, and InnerJoin.

◆ groupedQuery()

AbstractJoin::groupedQuery	(	$constraints = `""`,
		$indexBy = `""`
	)

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	$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

Definition at line 560 of file join.inc.

      {
           $field = "";
           $idxClass = "";
           
           if ($indexBy != "")
           {
                list($idxClass, $field) = explode(".", $indexBy); 
           }
           else
           {
                $idxClass = $this->class[0];
                $obj = new $class;
                $field = $obj->primary_key;
           }
           
           trace("groupedQuery(): Group by $idxClass $field", 3);
                
           $query = $this->generateQuery($constraints);      
                
           try
           {
                $db = ConnectionManager::getConnection();
                $result = $db->prepare($query);
                $result->execute();
                               
                $items = array();
                
                while($line = $result->fetch())
                {
                     $item = new JoinResult($this->tag);
                     
                     for($i = 0; $i < count($this->classes); ++$i)
                     {
                          $class = $this->classes[$i];
                          $item->$class = new $class;   
                          $item->$class->populate($line, $this->aliases[$item->$class->table]);
  
                          foreach($this->pseudos as $class => $lookup)
                          {
                               foreach($this->aliases as $table => $prefix)
                               {
                                    $keyAlias = "{$prefix}.{$lookup['index']}";
                          
                                    $key = $line[$keyAlias];
                          
                                    if (array_key_exists($key, $lookup['items']))
                                    {
                                         $item->$class = $lookup['items'][$key];
                                         break;
                                    }
                               }
                          }
                     }
      
                     $idx = $item->$idxClass->$field;
                     $items[$idx][] = $item;
                }
                
                unset($result);     
           
                return $items;
           }
           catch(PDOException $e)
           {
                throw new FakoliException($e->getMessage());
           }
      }

◆ indexedQuery()

AbstractJoin::indexedQuery	(	$constraints = `""`,
		$indexBy = `""`
	)

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	$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 (See InclusionFilter and ExclusionFilter)

Definition at line 475 of file join.inc.

      {
           $field = "";
           $idxClass = "";
           
           if ($indexBy != "")
           {
                list($idxClass, $field) = explode(".", $indexBy); 
           }
           else
           {
                $idxClass = $this->class[0];
                $obj = new $class;
                $field = $obj->primary_key;
           }
                
           $query = $this->generateQuery($constraints);      
           
           try
           {
                $db = ConnectionManager::getConnection();
                $result = $db->prepare($query);
                $result->execute();
                
                $items = array();
                
                while($line = $result->fetch())
                {
                     $item = new JoinResult($this->tag);
                     
                     for($i = 0; $i < count($this->classes); ++$i)
                     {
                          $class = $this->classes[$i];
                          $item->$class = new $class;   
                          $item->$class->populate($line, $this->aliases[$item->$class->table]);
  
                          foreach($this->pseudos as $class => $lookup)
                          {
                               foreach($this->aliases as $table => $prefix)
                               {
                                    $keyAlias = "{$prefix}.{$lookup['index']}";
                          
                                    $key = $line[$keyAlias];
                          
                                    if (array_key_exists($key, $lookup['items']))
                                    {
                                         $item->$class = $lookup['items'][$key];
                                         break;
                                    }
                               }
                          }
                     }
      
                     $idx = $item->$idxClass->$field;
                     if (array_key_exists($idx, $items))
                     {
                          // Implicitly promote to array if there is a collision
                          if (!is_array($items[$idx]))
                          {
                               $items[$idx] = array($items[$idx]);
                          }
                          $items[$idx][] = $item;
                     }
                     else
                     {
                          $items[$idx] = $item;
                     }              
                }
                
                unset($result);     
                
                return $items;
           }
           catch(PDOException $e)
           {
                throw new FakoliException($e->getMessage());
           }
      }

◆ iteratedQuery()

AbstractJoin::iteratedQuery ( $constraints = "" )

Performs a query against the database returning an iterator of JoinResult objects.

Parameters

string $constraints

Definition at line 461 of file join.inc.

      {
           return new JoinResultIterator($this, $constraints);
      }

◆ pseudo()

AbstractJoin::pseudo	(	$class,
		$items,
		$indexField
	)

Registers a class and indexed array as a pseudo-join item.

Pseudo-joins are joined into the result set based on the supplied index field.

Parameters

string	$class	Class name for the items being joined
array	$items	array of DataItems indexed by the joining key (usually the primary key)
string	$indexField	the field to be joined on

Definition at line 349 of file join.inc.

      {
           $this->pseudos[$class] = array("index" => $indexField, "items" => $items);
      }

◆ query()

AbstractJoin::query	(	$constraints = `""`,
		$page = `-1`,
		$size = `-1`
	)

Performs a query against the database returning an array of JoinResult objects.

Parameters

string	$constraints
integer	$page
integer	$size

Definition at line 387 of file join.inc.

      {
           $query = $this->generateQuery($constraints);      
           
           try
           {
                $db = ConnectionManager::getConnection();
                $result = $db->prepare($query);
                $result->execute(); 
                
                if ($page > 0)
                {
                     $count = ($page - 1) * $size;
                     while($count--)
                     {
                          $result->fetch();
                     }
                }
                     
                $items = array();
                
                while($line = $result->fetch())
                {
                     $item = new JoinResult($this->tag);
                     
                     for($i = 0; $i < count($this->classes); ++$i)
                     {
                          $class = $this->classes[$i];
                          $item->$class = new $class;   
                          $item->$class->populate($line, $this->aliases[$item->$class->table]);
                     
                          foreach($this->pseudos as $class => $lookup)
                          {
                               foreach($this->aliases as $table => $prefix)
                               {
                                    $keyAlias = "{$prefix}.{$lookup['index']}";
                          
                                    if (!array_key_exists($keyAlias, $line)) continue;
                                    
                                    $key = $line[$keyAlias];
                                    
                                    //trace("$keyAlias = {$key}", 3);
                                    //trace(print_r(array_keys($line), true), 3);
                                    
                                    if (array_key_exists($key, $lookup['items']))
                                    {
                                         //trace("Pseudo Match found for $keyAlias = $key",3);
                                         $item->$class = $lookup['items'][$key];
                                         break;
                                    }
                               }
                          }
                          
                          --$size;
                          if ($size == 0) break;
                     }
      
                     $items[] = $item;
                }
                
                unset($result);     
                
                return $items; 
           }
           catch(PDOException $e)
           {
                throw new FakoliException($e->getMessage());
           }
      }

◆ setFilter()

AbstractJoin::setFilter	(	$class,
		$filter
	)

Sets an InclusionFilter or ExclusionFilter on the specified class.

Parameters

$class	the class to be filtered
$filter	InclusionFilter or ExclusionFilter object defining the sub-set of fields to include

Definition at line 285 of file join.inc.

      {
           $this->protos[$class]->filter = $filter;
           return $this;
      }

◆ xref()

AbstractJoin::xref	(	$xref,
		$xrefFieldMaps = `null`
	)

Adds a cross-reference class to the join definition.

Classes added using this method are NOT included in the eventual result set.

Parameters

$xref
$xrefFieldMaps

Definition at line 330 of file join.inc.

      {
           $x = new $xref;
           
           $this->xrefs[] = $x;
           
           if ($xrefFieldMaps)
           {
                $this->xrefFieldMaps[$x->table] = $xrefFieldMaps;
           }
      }

Member Data Documentation

◆ $aliases

AbstractJoin::$aliases = array()

Field aliases for output.

Definition at line 240 of file join.inc.

◆ $classes

AbstractJoin::$classes = array()

The names of the DataItem classes being joined.

Definition at line 234 of file join.inc.

◆ $constraints

AbstractJoin::$constraints = array()

Class-specific constraints add via the constrain() method.

Definition at line 242 of file join.inc.

◆ $excludedKeys

AbstractJoin::$excludedKeys = array()

Definition at line 247 of file join.inc.

◆ $protos

AbstractJoin::$protos = array()

Prototype instances of the DataItem classes being joined.

Definition at line 235 of file join.inc.

◆ $pseudos

AbstractJoin::$pseudos = array()

Pseudo-join lookup tables.

Definition at line 248 of file join.inc.

◆ $tag

AbstractJoin::$tag = "join"

XML tag name.

Definition at line 245 of file join.inc.

◆ $unique

AbstractJoin::$unique = false

true to output distinct rows only

Definition at line 244 of file join.inc.

◆ $xrefAliases

AbstractJoin::$xrefAliases = array()

Cross-reference table aliases.

Definition at line 241 of file join.inc.

◆ $xrefFieldMaps

AbstractJoin::$xrefFieldMaps = array()

Cross-reference field map (to support cross-referencing through fields with differing names)

Definition at line 238 of file join.inc.

◆ $xrefs

AbstractJoin::$xrefs = array()

Cross-reference classes (i.e. classes that are part of the join, but not the result)

Definition at line 236 of file join.inc.

The documentation for this class was generated from the following file:

C:/code/cms.sonjara.com/framework/join.inc

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

◆ add()

◆ constrain()

◆ count()

◆ excludeKeyFromJoin()

◆ generateQuery()

◆ groupedQuery()

◆ indexedQuery()

◆ iteratedQuery()

◆ pseudo()

◆ query()

◆ setFilter()

◆ xref()

Member Data Documentation

◆ $aliases

◆ $classes

◆ $constraints

◆ $excludedKeys

◆ $protos

◆ $pseudos

◆ $tag

◆ $unique

◆ $xrefAliases

◆ $xrefFieldMaps

◆ $xrefs