Fakoli Framework
Query Class Reference

Query provides an object-oriented interface for database queries. More...

+ Inheritance diagram for Query:
+ Collaboration diagram for Query:

Public Member Functions

 __construct ($class, $constraints="")
 Creates a new Query object. More...
 
 page ($page, $size)
 Sets the page number and size for constraining the result set by page. More...
 
 tableAlias ($alias)
 Sometimes when you are creating abonimable SQL constraints you might need to refer back to the main object table by a specific alias. More...
 
 exists ()
 Return true if the query matches one or more rows in the database. More...
 
 execute ()
 Executes the query and returns an array of DataItems containing the results (the class of items returned is as specified in the Query constructor). More...
 
 executeSingle ()
 Executes the query and returns a singleton result row. More...
 
 executeValue ($func)
 Query the database to calculate an aggregate value. More...
 
 count ()
 Return the count of matching results. More...
 
- Public Member Functions inherited from AbstractQuery
 __construct ($class, $constraints="")
 
 constraints ($constraints)
 Sets the constraint clause for the Query. More...
 
 filter ($filter)
 Sets a filter to constrain the fields retrieved when the query is executed. More...
 
 params ($params)
 Sets the bound parameters array. More...
 
 bind ()
 Binds placeholders to parameter values. More...
 
 execute ()
 

Static Public Member Functions

static create ($class, $constraints="")
 Static factory method to create a new Query. More...
 

Public Attributes

 $page
 
 $size
 
 $tableAlias
 
- Public Attributes inherited from AbstractQuery
 $class
 
 $constraints
 
 $filter
 
 $params
 

Detailed Description

Query provides an object-oriented interface for database queries.

By instantiating Query objects you can specify a full or partial set of criteria and parameters, and then subsequently execute the query to retrieve the results. You can pass around the constructed Query object and execute it multiple times, allowing for lazy evaluation and other performance enhancing tricks.

Author
andy

Definition at line 112 of file query.inc.

Constructor & Destructor Documentation

◆ __construct()

Query::__construct (   $class,
  $constraints = "" 
)

Creates a new Query object.

Parameters
string$classthe DataItem class to be queried
string$constraints[optional] constraint clause for the query
Returns
a new Query object

Definition at line 124 of file query.inc.

125  {
126  parent::__construct($class, $constraints);
127 
128  $this->page = -1;
129  $this->size = -1;
130 
131  $this->tableAlias = "";
132  }
page($page, $size)
Sets the page number and size for constraining the result set by page.
Definition: query.inc:142
tableAlias($alias)
Sometimes when you are creating abonimable SQL constraints you might need to refer back to the main o...
Definition: query.inc:158

Member Function Documentation

◆ count()

Query::count ( )

Return the count of matching results.

Definition at line 334 of file query.inc.

335  {
336  return $this->executeValue("COUNT(1)");
337  }
executeValue($func)
Query the database to calculate an aggregate value.
Definition: query.inc:296

◆ create()

static Query::create (   $class,
  $constraints = "" 
)
static

Static factory method to create a new Query.

Parameters
string$classthe DataItem class to be queried
string$constraints[optional] constraint clause for the query
Returns
a new Query object

Definition at line 345 of file query.inc.

346  {
347  return new Query($class, $constraints);
348  }
Query provides an object-oriented interface for database queries.
Definition: query.inc:112

◆ execute()

Query::execute ( )

Executes the query and returns an array of DataItems containing the results (the class of items returned is as specified in the Query constructor).

Returns
array an array of DataItems containing the results.

Definition at line 201 of file query.inc.

202  {
203  $prototype = new $this->class;
204  $prototype->filter = $this->filter;
205 
206  $order_by_idx = strpos(strtoupper($this->constraints), "ORDER BY");
207  $orderBy = "";
208 
209  if ($order_by_idx !== false)
210  {
211  $orderBy = substr($this->constraints, $order_by_idx);
212 
213  $this->constraints = substr($this->constraints, 0, $order_by_idx);
214  }
215 
216  if ($this->constraints == "") $this->constraints = "WHERE 1=1"; //TODO - tidy this up some day
217  $this->constraints .= " ".$prototype->getIdentityConstraint();
218 
219  $query = "SELECT ".$prototype->getFieldList()." FROM {$prototype->table} {$this->tableAlias} {$this->constraints} $orderBy";
220 
221  trace("$query", 3);
222  trace("Page: $this->page Size: $this->size", 3);
223  $items = array();
224 
225  $size = $this->size;
226 
227  try
228  {
230 
231  $result = $db->prepare($query);
232  $result->execute($this->params);
233 
234  if ($this->page > 0)
235  {
236  $count = ($this->page - 1) * $this->size;
237  while($count--)
238  {
239  $result->fetch();
240  }
241  }
242 
243  while($line = $result->fetch())
244  {
245  $item = new $this->class;
246  $item->filter = $this->filter;
247  $item->populate($line);
248  $items[] = $item;
249 
250  --$size;
251  if ($size == 0) break;
252  }
253 
254  unset($result);
255  }
256  catch(PDOException $e)
257  {
258  $err = "query() failed - " . $e->getMessage();
259  trace($err, 2);
260  throw new DataItemException($err);
261  }
262 
263  trace(count($items)." items found", 3);
264  return $items;
265  }
page($page, $size)
Sets the page number and size for constraining the result set by page.
Definition: query.inc:142
params($params)
Sets the bound parameters array.
Definition: query.inc:78
trace($msg, $lvl, $callStack=null)
Send output to the trace log.
Definition: functions.inc:959
constraints($constraints)
Sets the constraint clause for the Query.
Definition: query.inc:55
$size
Definition: query.inc:115
static getConnection()
Retrieves a reference to the global database connection.
count()
Return the count of matching results.
Definition: query.inc:334

◆ executeSingle()

Query::executeSingle ( )

Executes the query and returns a singleton result row.

If no results match then a DataNotFoundException is thrown. If more than one row matches, then a DataItemException is thrown.

Returns
DataItem the matching DataItem from the database

Definition at line 273 of file query.inc.

274  {
275  $results = $this->execute();
276  if (count($results) == 1)
277  {
278  return $results[0];
279  }
280 
281  if (count($results) == 0)
282  {
283  throw new DataNotFoundException();
284  }
285  else
286  {
287  throw new DataItemException("Ambiguous singleton query");
288  }
289  }
execute()
Executes the query and returns an array of DataItems containing the results (the class of items retur...
Definition: query.inc:201
count()
Return the count of matching results.
Definition: query.inc:334

◆ executeValue()

Query::executeValue (   $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$functhe value or function to retrieve

Definition at line 296 of file query.inc.

297  {
298  $prototype = new $this->class;
299 
300  if ($this->constraints == "") $this->constraints = "WHERE 1=1"; //TODO - tidy this up some day
301  $this->constraints .= " ".$prototype->getIdentityConstraint();
302 
303  $query = "SELECT $func as result FROM {$prototype->table} {$this->tableAlias} {$this->constraints}";
304 
305  trace($query, 3);
306 
307  try
308  {
310 
311  $result = $db->prepare($query);
312  $result->execute($this->params);
313 
314  if ($row = $result->fetch())
315  {
316  $value = $row['result'];
317  }
318 
319  unset($result);
320  }
321  catch(PDOException $e)
322  {
323  $err = "Query::executeValue() failed - " . $e->getMessage();
324  trace($err, 2);
325  throw new DataItemException($err);
326  }
327 
328  return $value;
329  }
params($params)
Sets the bound parameters array.
Definition: query.inc:78
trace($msg, $lvl, $callStack=null)
Send output to the trace log.
Definition: functions.inc:959
constraints($constraints)
Sets the constraint clause for the Query.
Definition: query.inc:55
static getConnection()
Retrieves a reference to the global database connection.

◆ exists()

Query::exists ( )

Return true if the query matches one or more rows in the database.

Definition at line 167 of file query.inc.

168  {
169  $prototype = new $this->class;
170  $pk = $prototype->getPrimaryKey();
171 
172  $query = "SELECT $pk FROM {$prototype->table} {$this->tableAlias} {$this->constraints} LIMIT 1";
173 
174  $exists = false;
175 
176  try
177  {
179 
180  $result = $db->prepare($query);
181  $result->execute($this->params);
182 
183  if ($result->fetch()) $exists = true;
184 
185  unset($result);
186  }
187  catch(PDOException $e)
188  {
189  throw new DataItemException($e->getMessage());
190  }
191 
192  return $exists;
193 
194  }
params($params)
Sets the bound parameters array.
Definition: query.inc:78
static getConnection()
Retrieves a reference to the global database connection.

◆ page()

Query::page (   $page,
  $size 
)

Sets the page number and size for constraining the result set by page.

By default results are not paged.

Parameters
$pageinteger the page number
$sizeinteger the number of items per page
Returns
Query reference to the Query object, to allow for call chaining.

Definition at line 142 of file query.inc.

143  {
144  $this->page = $page;
145  $this->size = $size;
146  return $this;
147  }
page($page, $size)
Sets the page number and size for constraining the result set by page.
Definition: query.inc:142
$size
Definition: query.inc:115
$page
Definition: query.inc:114

◆ tableAlias()

Query::tableAlias (   $alias)

Sometimes when you are creating abonimable SQL constraints you might need to refer back to the main object table by a specific alias.

In those cases, set the table alias for the main object using this message.

Parameters
$aliasString the table alias name
Returns
Query reference to the Query object, to allow for call chaining.

Definition at line 158 of file query.inc.

159  {
160  $this->tableAlias = $alias;
161  return $this;
162  }
tableAlias($alias)
Sometimes when you are creating abonimable SQL constraints you might need to refer back to the main o...
Definition: query.inc:158

Member Data Documentation

◆ $page

Query::$page

Definition at line 114 of file query.inc.

◆ $size

Query::$size

Definition at line 115 of file query.inc.

◆ $tableAlias

Query::$tableAlias

Definition at line 116 of file query.inc.


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