Path

ez components / documentation / api reference / 2009.2.1 / database


eZ Components 2009.2.1

Database: ezcQuery

[ Tutorial ] [ Oracle setup ] [ Class tree ] [ Element index ] [ ChangeLog ] [ Credits ]

Class: ezcQuery

The ezcQuery class provides the common API for all Query objects. [source]
ezcQuery has three main purposes:
  • it provides a common API for building queries through the getQuery() method.
  • it provides a common API for binding parameters to queries through bindValue() and bindParam()
  • it provides internal aliasing functionality that allows you to use aliases for table and column names. The substitution is done inside of the query classes before the query itself is built.
Through the bind methods you can bind parameters and values to your query. Finally you can use prepare to get a PDOStatement object from your query object.
Subclasses should provide functionality to build an actual query.

Descendents

Child Class Description
ezcQueryDelete Class to create select database independent DELETE queries.
ezcQueryUpdate Class to create select database independent UPDATE queries.
ezcQueryInsert Class to create select database independent INSERT queries.
ezcQuerySelect Class to create select database independent SELECT queries.

Member Variables

protected PDO $db
A pointer to the database handler to use for this query.
public ezcQueryExpression $expr = null
The expression object for this class.

Method Summary

public ezcQuery __construct( $db, [$aliases = array()] )
Constructs a new ezcQuery that works on the database $db and with the aliases $aliases.
public static array arrayFlatten( $array )
Returns all the elements in $array as one large single dimensional array.
public string bindParam( &$param, [$placeHolder = null], [$type = PDO::PARAM_STR], $param )
Binds the parameter $param to the specified variable name $placeHolder..
public string bindValue( $value, [$placeHolder = null], [$type = PDO::PARAM_STR] )
Binds the value $value to the specified variable name $placeHolder.
public void doBind( $stmt )
Performs binding of variables bound with bindValue and bindParam on the statement $stmt.
protected string getIdentifier( $alias )
Returns the correct identifier for the alias $alias.
protected array(string) getIdentifiers( $aliasList )
Returns the correct identifiers for the aliases found in $aliases.
public abstract string getQuery( )
Returns the query string for this query object.
public bool hasAliases( )
Returns true if this object has aliases.
public PDOStatement prepare( )
Returns a prepared statement from this query which can be used for execution.
protected void resetBinds( )
Resets the bound values and parameters to empty.
public void setAliases( $aliases )
Sets the aliases $aliases for this object.
public ezcQuerySubSelect subSelect( )
Returns the ezcQuerySubSelect query object.
public string __toString( )
Return SQL string for query.

Methods

__construct

ezcQuery __construct( $db, [ $aliases = array()] )
Constructs a new ezcQuery that works on the database $db and with the aliases $aliases.
The aliases can be used to substitute the column and table names with more friendly names. E.g PersistentObject uses it to allow using property and class names instead of column and table names.

Parameters

Name Type Description
$db PDO  
$aliases array(string=>string)  

Redefined in descendants as

Method Description
ezcQueryDelete::__construct() Constructs a new ezcQueryDelete that works on the database $db and with the aliases $aliases.
ezcQueryUpdate::__construct() Constructs a new ezcQueryUpdate that works on the database $db and with the aliases $aliases.
ezcQueryInsert::__construct() Constructs a new ezcQueryInsert that works on the database $db and with the aliases $aliases.
ezcQuerySelect::__construct() Constructs a new ezcQuery object.
ezcQuerySelectSqlite::__construct() Constructs a new ezcQuerySelectSqlite object.
ezcQuerySelectOracle::__construct() Constructs a new ezcQueryOracle object working on the database $db.
ezcQuerySubSelect::__construct() Constructs a new ezcQuerySubSelect object.

arrayFlatten

array arrayFlatten( $array )
Returns all the elements in $array as one large single dimensional array.

Parameters

Name Type Description
$array array  

bindParam

string bindParam( &$param, [string $placeHolder = null], [ $type = PDO::PARAM_STR], &mixed $param )
Binds the parameter $param to the specified variable name $placeHolder..
This method provides a shortcut for PDOStatement::bindParam when using prepared statements.
The parameter $param specifies the variable that you want to bind. If $placeholder is not provided bind() will automatically create a placeholder for you. An automatic placeholder will be of the name 'ezcValue1', 'ezcValue2' etc.
For more information see http://php.net/pdostatement-bindparam
Example:
 1.  $value 2;
 2.  $q->eq'id'$q->bindParam$value ) );
 3.  $stmt $q->prepare()// the parameter $value is bound to the query.
 4.  $value 4;
 5.  $stmt->execute()// executed with 'id = 4'

Parameters

Name Type Description
$param &mixed  
$placeHolder string the name to bind with. The string must start with a colon ':'.
&$param  
$type  

See also:

ezcQuery::doBind().

Redefined in descendants as

Method Description
ezcQuerySubSelect::bindParam() Binds the parameter $param to the specified variable name $placeHolder.

bindValue

string bindValue( mixed $value, [string $placeHolder = null], [ $type = PDO::PARAM_STR] )
Binds the value $value to the specified variable name $placeHolder.
This method provides a shortcut for PDOStatement::bindValue when using prepared statements.
The parameter $value specifies the value that you want to bind. If $placeholder is not provided bindValue() will automatically create a placeholder for you. An automatic placeholder will be of the name 'ezcValue1', 'ezcValue2' etc.
For more information see http://php.net/pdostatement-bindparam
Example:
 1.  $value 2;
 2.  $q->eq'id'$q->bindValue$value ) );
 3.  $stmt $q->prepare()// the value 2 is bound to the query.
 4.  $value 4;
 5.  $stmt->execute()// executed with 'id = 2'

Parameters

Name Type Description
$value mixed  
$placeHolder string the name to bind with. The string must start with a colon ':'.
$type  

See also:

ezcQuery::doBind().

Redefined in descendants as

Method Description
ezcQuerySubSelect::bindValue() Binds the value $value to the specified variable name $placeHolder.

doBind

void doBind( $stmt )
Performs binding of variables bound with bindValue and bindParam on the statement $stmt.
This method must be called if you have used the bind methods in your query and you build the method yourself using build.

Parameters

Name Type Description
$stmt PDOStatement  

getIdentifier

string getIdentifier( string $alias )
Returns the correct identifier for the alias $alias.
If the alias does not exists in the list of aliases it is returned unchanged.
This can method handles composite identifiers separated by a dot ('.').

Parameters

Name Type Description
$alias string  

getIdentifiers

array(string) getIdentifiers( $aliasList )
Returns the correct identifiers for the aliases found in $aliases.
This method is similar to getIdentifier except that it works on an array.

Parameters

Name Type Description
$aliasList array(string)  

getQuery

string getQuery( )
Returns the query string for this query object.

Throws

ClassDescription
ezcQueryInvalidException if it was not possible to build a valid query.

Redefined in descendants as

Method Description
ezcQueryDelete::getQuery() Returns the query string for this query object.
ezcQueryUpdate::getQuery() Returns the query string for this query object.
ezcQueryInsert::getQuery() Returns the query string for this query object.
ezcQuerySelect::getQuery() Returns the complete select query string.
ezcQuerySelectMssql::getQuery() Transforms the query from the parent to provide LIMIT functionality.
ezcQuerySelectOracle::getQuery() Transforms the query from the parent to provide LIMIT functionality.
ezcQuerySubSelect::getQuery() Returns the SQL string for the subselect.

hasAliases

bool hasAliases( )
Returns true if this object has aliases.

prepare

PDOStatement prepare( )
Returns a prepared statement from this query which can be used for execution.
The returned object is a PDOStatement for which you can find extensive documentation in the PHP manual: http://php.net/pdostatement-bindcolumn
prepare() automatically calls doBind() on the statement.

Redefined in descendants as

Method Description
ezcQuerySelectOracle::prepare() Handles preparing query.

resetBinds

void resetBinds( )
Resets the bound values and parameters to empty.
This is useful if your query can be reset and used multiple times.

setAliases

void setAliases( $aliases )
Sets the aliases $aliases for this object.
The aliases should be in the form array( "aliasName" => "databaseName" ) Each alias defines a relation between a user-defined name and a name in the database. This is supported for table names as column names.
The aliases can be used to substitute the column and table names with more friendly names. The substitution is done when the query is built, not using AS statements in the database itself.
Example of a select query with aliases:
 1.  <?php
 2.  $q->setAliasesarray'Identifier' => 'id''Company' => 'company' ) );
 3.  $q->select'Company' )
 4.    ->from'table' )
 5.    ->where$q->expr->eq'Identifier') );
 6.  echo $q->getQuery();
 7.  ?>
This example will output SQL similar to:
 1.  SELECT company FROM table WHERE id 5
Aliasses also take effect for composite names in the form tablename.columnname as the following example shows:
 1.  <?php
 2.  $q->setAliasesarray'Order' => 'orders''Recipient' => 'company' ) );
 3.  $q->select'Order.Recipient' )
 4.    ->from'Order' );
 5.  echo $q->getQuery();
 6.  ?>
This example will output SQL similar to:
 1.  SELECT orders.company FROM orders;
It is even possible to have an alias point to a table name/column name combination. This will only work for alias names without a . (dot):
 1.  <?php
 2.  $q->setAliasesarray'Order' => 'orders''Recipient' => 'orders.company' ) );
 3.  $q->select'Recipient' )
 4.    ->from'Order' );
 5.  echo $q->getQuery();
 6.  ?>
This example will output SQL similar to:
 1.  SELECT orders.company FROM orders;
In the following example, the Recipient alias will not be used, as it is points to a fully qualified name - the Order alias however is used:
 1.  <?php
 2.  $q->setAliasesarray'Order' => 'orders''Recipient' => 'orders.company' ) );
 3.  $q->select'Order.Recipient' )
 4.    ->from'Order' );
 5.  echo $q->getQuery();
 6.  ?>
This example will output SQL similar to:
 1.  SELECT orders.Recipient FROM orders;

Parameters

Name Type Description
$aliases array(string=>string)  

subSelect

ezcQuerySubSelect subSelect( )
Returns the ezcQuerySubSelect query object.
This method creates new ezcQuerySubSelect object that could be used for building correct subselect inside query.

Redefined in descendants as

Method Description
ezcQuerySubSelect::subSelect() Returns ezcQuerySubSelect of deeper level.

__toString

string __toString( )
Return SQL string for query.
Typecasting to (string) should be used to make __toString() to be called with PHP 5.1. This will not be needed in PHP 5.2 and higher when this object is used in a string context.
Example:
 1.  $q->select('*')
 2.    ->from'table1' )
 3.    ->where $q->expr->eq'name'$q->bindValue"Beeblebrox" ) ) );
 4.  echo $q"\n";

Redefined in descendants as

Method Description
ezcQuerySubSelect::__toString() Returns the SQL string for the subselect.

Last updated: Tue, 23 Mar 2010