Path

ez components / documentation / api reference / trunk / database


eZ Components trunk

Database: ezcQueryExpression

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

Class: ezcQueryExpression

The ezcQueryExpression class is used to create database independent SQL expression. [source]
The QueryExpression class is usually used through the 'expr' variable in one of the Select, Insert, Update or Delete classes.
Note that the methods for logical or and and are named lOr and lAnd respectively. This is because and and or are reserved names in PHP and can not be used in method names.

Descendents

Child Class Description
ezcQueryExpressionMssql The ezcQueryExpressionMssql class is used to create SQL expression for SQL Server.
ezcQueryExpressionOracle The ezcQueryExpressionOracle class is used to create SQL expression for Oracle.
ezcQueryExpressionSqlite The ezcQueryExpressionSqlite class is used to create SQL expression for SQLite.
ezcQueryExpressionPgsql The ezcQueryExpressionPgsql class is used to create SQL expression for PostgreSQL.

Member Variables

protected PDO $db
A pointer to the database handler to use for this query.
protected array(string=>string) $intervalMap = array(
'SECOND' => 'SECOND',
'MINUTE' => 'MINUTE',
'HOUR' => 'HOUR',
'DAY' => 'DAY',
'MONTH' => 'MONTH',
'YEAR' => 'YEAR',
)

Contains an interval map from generic intervals to MySQL native intervals.
protected boolean $quoteValues = true
The flag that switch quoting mode for values provided by user in miscelaneous SQL functions.

Method Summary

public ezcQueryExpression __construct( $db, [$aliases = array()] )
Constructs an empty ezcQueryExpression
public string add( $... )
Returns the SQL to add values or expressions together.
public string avg( $column )
Returns the average value of a column
public string between( $expression, $value1, $value2 )
Returns SQL that checks if an expression evaluates to a value between two values.
public string bitAnd( $value1, $value2 )
Returns the SQL that performs the bitwise AND on two values.
public string bitOr( $value1, $value2 )
Returns the SQL that performs the bitwise OR on two values.
public string bitXor( $value1, $value2 )
Returns the SQL that performs the bitwise XOR on two values.
public string ceil( $number )
Returns the SQL to calculate the next highest integer value from the number.
public void concat( $... )
Returns a series of strings concatinated
public string count( $column )
Returns the number of rows (without a NULL value) of a column
public string dateAdd( $column, $expr, $type )
Returns the SQL that adds an interval to a timestamp value.
public string dateExtract( $column, $type )
Returns the SQL that extracts parts from a timestamp value.
public string dateSub( $column, $expr, $type )
Returns the SQL that subtracts an interval from a timestamp value.
public string div( $... )
Returns the SQL to divide values or expressions by eachother.
public string eq( $value1, $value2 )
Returns the SQL to check if two values are equal.
public string floor( $number )
Returns the SQL to calculate the next lowest integer value from the number.
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 string gt( $value1, $value2 )
Returns the SQL to check if one value is greater than another value.
public string gte( $value1, $value2 )
Returns the SQL to check if one value is greater than or equal to another value.
public bool hasAliases( )
Returns true if this object has aliases.
public string in( $column, $... )
Returns the SQL to check if a value is one in a set of given values..
public string isNull( $expression )
Returns SQL that checks if a expression is null.
public string lAnd( )
Returns the SQL to bind logical expressions together using a logical and.
public string length( $column )
Returns the length of text field $column
public void like( $expression, $pattern )
Match a partial string in a column.
public string lOr( )
Returns the SQL to bind logical expressions together using a logical or.
public string lower( $value )
Returns the SQL to change all characters to lowercase
public string lt( $value1, $value2 )
Returns the SQL to check if one value is less than another value.
public string lte( $value1, $value2 )
Returns the SQL to check if one value is less than or equal to another value.
public string max( $column )
Returns the highest value of a column
public string md5( $column )
Returns the md5 sum of $column.
public string min( $column )
Returns the lowest value of a column
public string mod( $expression1, $expression2 )
Returns the remainder of the division operation $expression1 / $expression2.
public string mul( $... )
Returns the SQL to multiply values or expressions by eachother.
public string neq( $value1, $value2 )
Returns the SQL to check if two values are unequal.
public string not( $expression )
Returns the SQL for a logical not, negating the $expression.
public string now( )
Returns the current system date and time in the database internal format.
public string position( $substr, $value )
Returns the SQL to locate the position of the first occurrence of a substring
public string round( $column, $decimals )
Rounds a numeric field to the number of decimals specified.
public string searchedCase( )
Returns a searched CASE statement.
public void setAliases( $aliases )
Sets the aliases $aliases for this object.
public void setValuesQuoting( $doQuoting )
Sets the mode of quoting for parameters passed to SQL functions and operators.
public string sub( $... )
Returns the SQL to subtract values or expressions from eachother.
public string subString( $value, $from, [$len = null] )
Returns part of a string.
public string sum( $column )
Returns the total sum of a column
public string unixTimestamp( $column )
Returns the SQL that converts a timestamp value to a unix timestamp.
public string upper( $value )
Returns the SQL to change all characters to uppercase

Methods

__construct

ezcQueryExpression __construct( $db, [ $aliases = array()] )
Constructs an empty ezcQueryExpression

Parameters

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

Redefined in descendants as

Method Description
ezcQueryExpressionOracle::__construct() Constructs an empty ezcQueryExpression
ezcQueryExpressionPgsql::__construct() Constructs an pgsql expression object using the db $db.

add

string add( string|array(string) $... )
Returns the SQL to add values or expressions together.
add() accepts an arbitrary number of parameters. Each parameter must contain a value or an expression or an array with values or expressions.
Example:
 1.  $q ezcDbInstance::get()->createSelectQuery();
 2.  $q->select'*' )->from'table' )
 3.                   ->where$q->expr->add'id')  );

Parameters

Name Type Description
$... string|array(string)  

Throws

ClassDescription
ezcDbAbstractionException if called with no parameters.

avg

string avg( string $column )
Returns the average value of a column

Parameters

Name Type Description
$column string the column to use

between

string between( string $expression, string $value1, string $value2 )
Returns SQL that checks if an expression evaluates to a value between two values.
The parameter $expression is checked if it is between $value1 and $value2.
Note: There is a slight difference in the way BETWEEN works on some databases. http://www.w3schools.com/sql/sql_between.asp. If you want complete database independence you should avoid using between().
Example:
 1.  $q ezcDbInstance::get()->createSelectQuery();
 2.  $q->select'*' )->from'table' )
 3.                   ->where$q->expr->between'id'$q->bindValue)$q->bindValue) ) );

Parameters

Name Type Description
$expression string the value to compare to
$value1 string the lower value to compare with
$value2 string the higher value to compare with

bitAnd

string bitAnd( string $value1, string $value2 )
Returns the SQL that performs the bitwise AND on two values.

Parameters

Name Type Description
$value1 string  
$value2 string  

Redefined in descendants as

Method Description
ezcQueryExpressionOracle::bitAnd() Returns the SQL that performs the bitwise AND on two values.

bitOr

string bitOr( string $value1, string $value2 )
Returns the SQL that performs the bitwise OR on two values.

Parameters

Name Type Description
$value1 string  
$value2 string  

Redefined in descendants as

Method Description
ezcQueryExpressionOracle::bitOr() Returns the SQL that performs the bitwise OR on two values.

bitXor

string bitXor( string $value1, string $value2 )
Returns the SQL that performs the bitwise XOR on two values.

Parameters

Name Type Description
$value1 string  
$value2 string  

Redefined in descendants as

Method Description
ezcQueryExpressionOracle::bitXor() Returns the SQL that performs the bitwise XOR on two values.
ezcQueryExpressionSqlite::bitXor() Returns the SQL that performs the bitwise XOR on two values.
ezcQueryExpressionPgsql::bitXor() Returns the SQL that performs the bitwise XOR on two values.

ceil

string ceil( string $number )
Returns the SQL to calculate the next highest integer value from the number.

Parameters

Name Type Description
$number string  

Redefined in descendants as

Method Description
ezcQueryExpressionMssql::ceil() Returns the SQL to calculate the next highest integer value from the number.

concat

void concat( string|array(string) $... )
Returns a series of strings concatinated
concat() accepts an arbitrary number of parameters. Each parameter must contain an expression or an array with expressions.

Parameters

Name Type Description
$... string|array(string) strings that will be concatinated.

Redefined in descendants as

Method Description
ezcQueryExpressionMssql::concat() Returns a series of strings concatinated
ezcQueryExpressionOracle::concat() Returns a series of strings concatinated
ezcQueryExpressionPgsql::concat() Returns a series of strings concatinated

count

string count( string $column )
Returns the number of rows (without a NULL value) of a column
If a '*' is used instead of a column the number of selected rows is returned.

Parameters

Name Type Description
$column string the column to use

dateAdd

string dateAdd( string $column, numeric $expr, string $type )
Returns the SQL that adds an interval to a timestamp value.

Parameters

Name Type Description
$column string  
$expr numeric  
$type string one of SECOND, MINUTE, HOUR, DAY, MONTH, or YEAR

Redefined in descendants as

Method Description
ezcQueryExpressionMssql::dateAdd() Returns the SQL that adds an interval to a timestamp value.
ezcQueryExpressionOracle::dateAdd() Returns the SQL that adds an interval to a timestamp value.
ezcQueryExpressionSqlite::dateAdd() Returns the SQL that adds an interval to a timestamp value.
ezcQueryExpressionPgsql::dateAdd() Returns the SQL that adds an interval to a timestamp value.

dateExtract

string dateExtract( string $column, string $type )
Returns the SQL that extracts parts from a timestamp value.

Parameters

Name Type Description
$column string The column to operate on
$type string one of SECOND, MINUTE, HOUR, DAY, MONTH, or YEAR

Redefined in descendants as

Method Description
ezcQueryExpressionMssql::dateExtract() Returns the SQL that extracts parts from a timestamp value from a column.
ezcQueryExpressionOracle::dateExtract() Returns the SQL that extracts parts from a timestamp value.
ezcQueryExpressionSqlite::dateExtract() Returns the SQL that extracts parts from a timestamp value.
ezcQueryExpressionPgsql::dateExtract() Returns the SQL that extracts parts from a timestamp value.

dateSub

string dateSub( string $column, numeric $expr, string $type )
Returns the SQL that subtracts an interval from a timestamp value.

Parameters

Name Type Description
$column string  
$expr numeric  
$type string one of SECOND, MINUTE, HOUR, DAY, MONTH, or YEAR

Redefined in descendants as

Method Description
ezcQueryExpressionMssql::dateSub() Returns the SQL that subtracts an interval from a timestamp value.
ezcQueryExpressionOracle::dateSub() Returns the SQL that subtracts an interval from a timestamp value.
ezcQueryExpressionSqlite::dateSub() Returns the SQL that subtracts an interval from a timestamp value.
ezcQueryExpressionPgsql::dateSub() Returns the SQL that subtracts an interval from a timestamp value.

div

string div( string|array(string) $... )
Returns the SQL to divide values or expressions by eachother.
divide() accepts an arbitrary number of parameters. Each parameter must contain a value or an expression or an array with values or expressions.
Example:
 1.  $q ezcDbInstance::get()->createSelectQuery();
 2.  $q->select'*' )->from'table' )
 3.                   ->where$q->expr->divide'id')  );

Parameters

Name Type Description
$... string|array(string)  

Throws

ClassDescription
ezcDbAbstractionException if called with no parameters.

eq

string eq( string $value1, string $value2 )
Returns the SQL to check if two values are equal.
Example:
 1.  $q ezcDbInstance::get()->createSelectQuery();
 2.  $q->select'*' )->from'table' )
 3.                   ->where$q->expr->eq'id'$q->bindValue) ) );

Parameters

Name Type Description
$value1 string logical expression to compare
$value2 string logical expression to compare with

floor

string floor( string $number )
Returns the SQL to calculate the next lowest integer value from the number.

Parameters

Name Type Description
$number string  

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.

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)  

gt

string gt( string $value1, string $value2 )
Returns the SQL to check if one value is greater than another value.
Example:
 1.  $q ezcDbInstance::get()->createSelectQuery();
 2.  $q->select'*' )->from'table' )
 3.                   ->where$q->expr->gt'id'$q->bindValue) ) );

Parameters

Name Type Description
$value1 string logical expression to compare
$value2 string logical expression to compare with

gte

string gte( string $value1, string $value2 )
Returns the SQL to check if one value is greater than or equal to another value.
Example:
 1.  $q ezcDbInstance::get()->createSelectQuery();
 2.  $q->select'*' )->from'table' )
 3.                   ->where$q->expr->gte'id'$q->bindValue) ) );

Parameters

Name Type Description
$value1 string logical expression to compare
$value2 string logical expression to compare with

hasAliases

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

in

string in( string $column, string|array(string) $... )
Returns the SQL to check if a value is one in a set of given values..
in() accepts an arbitrary number of parameters. The first parameter must always specify the value that should be matched against. Successive parameters must contain a logical expression or an array with logical expressions. These expressions will be matched against the first parameter.
Example:
 1.  $q->select'*' )->from'table' )
 2.                   ->where$q->expr->in'id'12) );
Optimization note: Call setQuotingValues( false ) before using in() with big lists of numeric parameters. This avoid redundant quoting of numbers in resulting SQL query and saves time of converting strings to numbers inside RDBMS.

Parameters

Name Type Description
$column string the value that should be matched against
$... string|array(string) values that will be matched against $column

Throws

ClassDescription
ezcQueryInvalidParameterException if the 2nd parameter is an empty array.
ezcQueryVariableParameterException if called with less than two parameters.

Redefined in descendants as

Method Description
ezcQueryExpressionOracle::in() Returns the SQL to check if a value is one in a set of given values.

isNull

string isNull( string $expression )
Returns SQL that checks if a expression is null.
Example:
 1.  $q ezcDbInstance::get()->createSelectQuery();
 2.  $q->select'*' )->from'table' )
 3.                   ->where$q->expr->isNull'id' ) );

Parameters

Name Type Description
$expression string the expression that should be compared to null

lAnd

string lAnd( )
Returns the SQL to bind logical expressions together using a logical and.
lAnd() accepts an arbitrary number of parameters. Each parameter must contain a logical expression or an array with logical expressions.
Example:
 1.  $q ezcDbInstance::get()->createSelectQuery();
 2.  $e $q->expr;
 3.  $q->select'*' )->from'table' )
 4.                   ->where$e->lAnd$e->eq'id'$q->bindValue) ),
 5.                                      $e->eq'id'$q->bindValue) ) ) );

Throws

ClassDescription
ezcDbAbstractionException if called with no parameters.

length

string length( string $column )
Returns the length of text field $column

Parameters

Name Type Description
$column string  

Redefined in descendants as

Method Description
ezcQueryExpressionMssql::length() Returns the length of a text field.

like

void like( string $expression, string $pattern )
Match a partial string in a column.
Like will look for the pattern in the column given. Like accepts the wildcards '_' matching a single character and '%' matching any number of characters.

Parameters

Name Type Description
$expression string the name of the expression to match on
$pattern string the pattern to match with.

lOr

string lOr( )
Returns the SQL to bind logical expressions together using a logical or.
lOr() accepts an arbitrary number of parameters. Each parameter must contain a logical expression or an array with logical expressions.
Example:
 1.  $q ezcDbInstance::get()->createSelectQuery();
 2.  $e $q->expr;
 3.  $q->select'*' )->from'table' )
 4.                   ->where$e->lOr$e->eq'id'$q->bindValue) ),
 5.                                     $e->eq'id'$q->bindValue) ) ) );

Throws

ClassDescription
ezcDbAbstractionException if called with no parameters.

lower

string lower( string $value )
Returns the SQL to change all characters to lowercase

Parameters

Name Type Description
$value string  

lt

string lt( string $value1, string $value2 )
Returns the SQL to check if one value is less than another value.
Example:
 1.  $q ezcDbInstance::get()->createSelectQuery();
 2.  $q->select'*' )->from'table' )
 3.                   ->where$q->expr->lt'id'$q->bindValue) ) );

Parameters

Name Type Description
$value1 string logical expression to compare
$value2 string logical expression to compare with

lte

string lte( string $value1, string $value2 )
Returns the SQL to check if one value is less than or equal to another value.
Example:
 1.  $q ezcDbInstance::get()->createSelectQuery();
 2.  $q->select'*' )->from'table' )
 3.                   ->where$q->expr->lte'id'$q->bindValue) ) );

Parameters

Name Type Description
$value1 string logical expression to compare
$value2 string logical expression to compare with

max

string max( string $column )
Returns the highest value of a column

Parameters

Name Type Description
$column string the column to use

md5

string md5( string $column )
Returns the md5 sum of $column.
Note: Not SQL92, but common functionality

Parameters

Name Type Description
$column string  

Redefined in descendants as

Method Description
ezcQueryExpressionMssql::md5() Returns the md5 sum of a field.
ezcQueryExpressionPgsql::md5() Returns the md5 sum of the field $column.

min

string min( string $column )
Returns the lowest value of a column

Parameters

Name Type Description
$column string the column to use

mod

string mod( string $expression1, string $expression2 )
Returns the remainder of the division operation $expression1 / $expression2.

Parameters

Name Type Description
$expression1 string  
$expression2 string  

Redefined in descendants as

Method Description
ezcQueryExpressionMssql::mod() Returns the remainder of the division operation $expression1 / $expression2.

mul

string mul( string|array(string) $... )
Returns the SQL to multiply values or expressions by eachother.
multiply() accepts an arbitrary number of parameters. Each parameter must contain a value or an expression or an array with values or expressions.
Example:
 1.  $q ezcDbInstance::get()->createSelectQuery();
 2.  $q->select'*' )->from'table' )
 3.                   ->where$q->expr->multiply'id')  );

Parameters

Name Type Description
$... string|array(string)  

Throws

ClassDescription
ezcDbAbstractionException if called with no parameters.

neq

string neq( string $value1, string $value2 )
Returns the SQL to check if two values are unequal.
Example:
 1.  $q ezcDbInstance::get()->createSelectQuery();
 2.  $q->select'*' )->from'table' )
 3.                   ->where$q->expr->neq'id'$q->bindValue) ) );

Parameters

Name Type Description
$value1 string logical expression to compare
$value2 string logical expression to compare with

not

string not( string $expression )
Returns the SQL for a logical not, negating the $expression.
Example:
 1.  $q ezcDbInstance::get()->createSelectQuery();
 2.  $e $q->expr;
 3.  $q->select'*' )->from'table' )
 4.                   ->where$e->eq'id'$e->not'null' ) ) );

Parameters

Name Type Description
$expression string  

now

string now( )
Returns the current system date and time in the database internal format.

Redefined in descendants as

Method Description
ezcQueryExpressionMssql::now() Returns the current system date and time in the database internal format.
ezcQueryExpressionOracle::now() Returns the current system date and time in the database internal format.
ezcQueryExpressionSqlite::now() Returns the current system date and time in the database internal format.
ezcQueryExpressionPgsql::now() Returns the current system date and time in the database internal format.

position

string position( string $substr, string $value )
Returns the SQL to locate the position of the first occurrence of a substring

Parameters

Name Type Description
$substr string  
$value string  

Redefined in descendants as

Method Description
ezcQueryExpressionMssql::position() Returns the SQL to locate the position of the first occurrence of a substring
ezcQueryExpressionOracle::position() Returns the SQL to locate the position of the first occurrence of a substring
ezcQueryExpressionPgsql::position() Returns the SQL to locate the position of the first occurrence of a substring

round

string round( string $column, int $decimals )
Rounds a numeric field to the number of decimals specified.

Parameters

Name Type Description
$column string  
$decimals int  

searchedCase

string searchedCase( )
Returns a searched CASE statement.
Accepts an arbitrary number of parameters. The first parameter (array) must always be specified, the last parameter (string) specifies the ELSE result.
Example:
 1.  $q ezcDbInstance::get()->createSelectQuery();
 2.  $q->select(
 3.       $q->expr->searchedCase(
 4.             array$q->expr->gte'column1'20 )'column1' )
 5.           array$q->expr->gte'column2'50 )'column2' )
 6.           'column3'
 7.       )
 8.   )
 9.      ->from'table' );

Throws

ClassDescription
ezcQueryVariableParameterException

setAliases

void setAliases( $aliases )
Sets the aliases $aliases for this object.
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
$aliases array(string=>string)  

setValuesQuoting

void setValuesQuoting( boolean $doQuoting )
Sets the mode of quoting for parameters passed to SQL functions and operators.
Quoting mode is set to ON by default. $q->expr->in( 'column1', 'Hello', 'world' ) will produce SQL "column1 IN ( 'Hello', 'world' )" ( note quotes in SQL ).
User must execute setValuesQuoting( false ) before call to function where quoting of parameters is not desirable. Example:
 1.  $q->expr->setValuesQuotingfalse );
 2.  $q->expr->in'column1''SELECT * FROM table' )
This will produce SQL "column1 IN ( SELECT * FROM table )".
Quoting mode will remain unchanged until next call to setValuesQuoting().

Parameters

Name Type Description
$doQuoting boolean - flag that switch quoting.

sub

string sub( string|array(string) $... )
Returns the SQL to subtract values or expressions from eachother.
subtract() accepts an arbitrary number of parameters. Each parameter must contain a value or an expression or an array with values or expressions.
Example:
 1.  $q ezcDbInstance::get()->createSelectQuery();
 2.  $q->select'*' )->from'table' )
 3.                   ->where$q->expr->subtract'id')  );

Parameters

Name Type Description
$... string|array(string)  

Throws

ClassDescription
ezcDbAbstractionException if called with no parameters.

subString

string subString( string $value, int $from, [int $len = null] )
Returns part of a string.
Note: Not SQL92, but common functionality.

Parameters

Name Type Description
$value string the target $value the string or the string column.
$from int extract from this characeter.
$len int extract this amount of characters.

Redefined in descendants as

Method Description
ezcQueryExpressionMssql::subString() Returns part of a string.
ezcQueryExpressionOracle::subString() Returns part of a string.
ezcQueryExpressionSqlite::subString() Returns part of a string.
ezcQueryExpressionPgsql::subString() Returns part of a string.

sum

string sum( string $column )
Returns the total sum of a column

Parameters

Name Type Description
$column string the column to use

unixTimestamp

string unixTimestamp( string $column )
Returns the SQL that converts a timestamp value to a unix timestamp.

Parameters

Name Type Description
$column string  

Redefined in descendants as

Method Description
ezcQueryExpressionMssql::unixTimestamp() Returns the SQL that converts a timestamp value to number of seconds since 1970-01-01 00:00:00-00.
ezcQueryExpressionOracle::unixTimestamp() Returns the SQL that converts a timestamp value to a unix timestamp.
ezcQueryExpressionSqlite::unixTimestamp() Returns the SQL that converts a timestamp value to a unix timestamp.
ezcQueryExpressionPgsql::unixTimestamp() Returns the SQL that converts a timestamp value to a unix timestamp.

upper

string upper( string $value )
Returns the SQL to change all characters to uppercase

Parameters

Name Type Description
$value string  

Last updated: Mon, 21 Dec 2009