xpdo/om/xpdoquery.class.php
- package
- xpdo
- subpackage
- om
- Classes
- xPDOQuery
- xPDOQueryCondition
Description
A class for constructing complex SQL statements using a model-aware API.
\xPDOQuery
- Extends from
- \xPDOCriteria
- abstract
- package
- xpdo
- subpackage
- om
- Constants
- SQL_AND
- SQL_JOIN_CROSS
- SQL_JOIN_LEFT
- SQL_JOIN_NATURAL_LEFT
- SQL_JOIN_NATURAL_RIGHT
- SQL_JOIN_RIGHT
- SQL_JOIN_STRAIGHT
- SQL_OR
- Properties
- $_alias
- $_class
- $_operators
- $_quotable
- $_tableClass
- $graph
- $query
- Methods
- __construct
- andCondition
- bindGraph
- bindGraphNode
- buildConditionalClause
- command
- condition
- construct
- from
- getAlias
- getClass
- getTableClass
- groupby
- having
- hydrateGraph
- hydrateGraphNode
- hydrateGraphParent
- innerJoin
- isConditionalClause
- join
- leftJoin
- limit
- orCondition
- parseConditions
- prepare
- rightJoin
- select
- setClassAlias
- sortby
- where
- wrap
Description
An xPDOCriteria derivative with methods for constructing complex statements.
Constants
SQL_AND
SQL_AND = 'AND'
Details
- value
- AND
SQL_OR
SQL_OR = 'OR'
Details
- value
- OR
SQL_JOIN_CROSS
SQL_JOIN_CROSS = 'JOIN'
Details
- value
- JOIN
SQL_JOIN_LEFT
SQL_JOIN_LEFT = 'LEFT JOIN'
Details
- value
- LEFT JOIN
SQL_JOIN_RIGHT
SQL_JOIN_RIGHT = 'RIGHT JOIN'
Details
- value
- RIGHT JOIN
SQL_JOIN_NATURAL_LEFT
SQL_JOIN_NATURAL_LEFT = 'NATURAL LEFT JOIN'
Details
- value
- NATURAL LEFT JOIN
SQL_JOIN_NATURAL_RIGHT
SQL_JOIN_NATURAL_RIGHT = 'NATURAL RIGHT JOIN'
Details
- value
- NATURAL RIGHT JOIN
SQL_JOIN_STRAIGHT
SQL_JOIN_STRAIGHT = 'STRAIGHT_JOIN'
Details
- value
- STRAIGHT_JOIN
Properties
$_alias
$_alias = 'null'
Details
- visibility
- protected
- default
- null
- final
- false
- static
- false
$_class
$_class = 'null'
Details
- visibility
- protected
- default
- null
- final
- false
- static
- false
$_operators
array $_operators = 'array'
An array of symbols and keywords indicative of SQL operators.
Details
- array
- visibility
- protected
- default
- array
- final
- false
- static
- false
- todo
- Refactor this to separate xPDOQuery operators from db-specific conditional statement identifiers.
$_quotable
$_quotable = 'array'
Details
- visibility
- protected
- default
- array
- final
- false
- static
- false
$_tableClass
$_tableClass = 'null'
Details
- visibility
- protected
- default
- null
- final
- false
- static
- false
$graph
$graph = 'array'
Details
- visibility
- public
- default
- array
- final
- false
- static
- false
$query
$query = 'array'
Details
- visibility
- public
- default
- array
- final
- false
- static
- false
Methods
__construct
__construct(
\xPDO $xpdo, $class, $criteria
=
null
)
:
\xPDOCriteria
The constructor for a new xPDOCriteria instance.
The constructor optionally prepares provided SQL and/or parameter bindings. Setting the bindings via the constructor or with the {@link xPDOCriteria::bind()} function allows you to make use of the data object caching layer.
The statement will not be prepared immediately if the cacheFlag value is true or a positive integer, in order to allow the result to be found in the cache before being queried from an actual database connection.
Arguments
- $xpdo
- \xPDO
&$xpdo An xPDO instance that will control this criteria. - $class
- $criteria
Output
Details
- visibility
- public
- final
- false
- static
- false
andCondition
andCondition(
$conditions, $binding
=
null, $group
=
0
)
:
Arguments
- $conditions
- $binding
- $group
Details
- visibility
- public
- final
- false
- static
- false
bindGraph
bindGraph(
mixed $graph
)
:
\xPDOQuery
Bind an object graph to the query.
Arguments
- $graph
- mixed
An array or JSON graph of related objects.
Output
- \xPDOQuery
- Returns the instance.
Details
- visibility
- public
- final
- false
- static
- false
bindGraphNode
bindGraphNode(
string $parentClass, string $parentAlias, string $classAlias, array $relations
)
:
Bind the node of an object graph to the query.
Arguments
- $parentClass
- string
The class representing the relation parent. - $parentAlias
- string
The alias the class is assuming. - $classAlias
- string
The class representing the related graph node. - $relations
- array
Child relations of the current graph node.
Details
- visibility
- public
- final
- false
- static
- false
buildConditionalClause
buildConditionalClause(
array|\xPDOQueryCondition $conditions, string $conjunction
=
xPDOQuery, boolean $isFirst
=
true
)
:
string
Builds conditional clauses from xPDO condition expressions.
Arguments
- $conditions
- array\xPDOQueryCondition
An array of conditions or an xPDOQueryCondition instance. - $conjunction
- string
Either xPDOQuery:SQL_AND or xPDOQuery::SQL_OR - $isFirst
- boolean
Indicates if this is the first condition in an array.
Output
- string
- The generated SQL clause.
Details
- visibility
- public
- final
- false
- static
- false
command
command(
string $command
=
SELECT
)
:
\xPDOQuery
Set the type of SQL command you want to build.
The default is SELECT, though it also supports DELETE.
Arguments
- $command
- string
The type of SQL statement represented by this object. Default is 'SELECT'.
Output
- \xPDOQuery
- Returns the current object for convenience.
Details
- visibility
- public
- final
- false
- static
- false
- todo
- Implement support for other standard SQL statements such as UPDATE.
condition
condition(
string $target, mixed $conditions
=
1, string $conjunction
=
xPDOQuery, mixed $binding
=
null, integer $condGroup
=
0
)
:
\xPDOQuery
Add a condition to the query.
Arguments
- $target
- string
The target clause for the condition. - $conditions
- mixed
A valid xPDO criteria expression. - $conjunction
- string
The conjunction to use when appending this condition, i.e., AND or OR. - $binding
- mixed
A value or PDO binding representation of a value for the condition. - $condGroup
- integer
A numeric identifier for associating conditions into groups.
Output
- \xPDOQuery
- Returns the instance.
Details
- visibility
- public
- final
- false
- static
- false
construct
construct(
)
:
boolean
Constructs the SQL query from the xPDOQuery definition.
Output
- boolean
- Returns true if a SQL statement was successfully constructed.
Details
- visibility
- public
- final
- false
- static
- false
from
from(
string $class, string $alias
)
:
\xPDOQuery
Add a FROM clause to the query.
Arguments
- $class
- string
The class representing the table to add. - $alias
- string
An optional alias for the class.
Output
- \xPDOQuery
- Returns the instance.
Details
- visibility
- public
- final
- false
- static
- false
getAlias
getAlias(
)
:
Details
- visibility
- public
- final
- false
- static
- false
getClass
getClass(
)
:
Details
- visibility
- public
- final
- false
- static
- false
getTableClass
getTableClass(
)
:
Details
- visibility
- public
- final
- false
- static
- false
groupby
groupby(
string $column, string $direction
)
:
\xPDOQuery
Add an GROUP BY clause to the query.
Arguments
- $column
- string
Column identifier to group by. - $direction
- string
The direction to sort by, ASC or DESC.
Output
- \xPDOQuery
- Returns the instance.
Details
- visibility
- public
- final
- false
- static
- false
having
having(
$conditions
)
:
Arguments
- $conditions
Details
- visibility
- public
- final
- false
- static
- false
hydrateGraph
hydrateGraph(
array $rows, $cacheFlag
=
true
)
:
array
Hydrates a graph of related objects from a single result set.
Arguments
- $rows
- array
A collection of result set rows for hydrating the graph. - $cacheFlag
Output
- array
- A collection of objects with all related objects from the graph pre-populated.
Details
- visibility
- public
- final
- false
- static
- false
hydrateGraphNode
hydrateGraphNode(
array $row, \xPDOObject $instance, string $alias, array $relations
)
:
Hydrates a node of the object graph.
Arguments
- $row
- array
The result set representing the current node. - $instance
- \xPDOObject
The xPDOObject instance to be hydrated from the node. - $alias
- string
The alias identifying the object in the parent relationship. - $relations
- array
Child relations of the current node.
Details
- visibility
- public
- final
- false
- static
- false
hydrateGraphParent
hydrateGraphParent(
$instances, $row
)
:
Arguments
- $instances
- $row
Details
- visibility
- public
- final
- false
- static
- false
innerJoin
innerJoin(
$class, $alias, $conditions
=
array, $conjunction
=
xPDOQuery, $binding
=
null, $condGroup
=
0
)
:
Arguments
- $class
- $alias
- $conditions
- $conjunction
- $binding
- $condGroup
Details
- visibility
- public
- final
- false
- static
- false
isConditionalClause
isConditionalClause(
string $string
)
:
boolean
Determines if a string contains a conditional operator.
Arguments
- $string
- string
The string to evaluate.
Output
- boolean
- True if the string is a complete conditional SQL clause.
Details
- visibility
- public
- final
- false
- static
- false
join
join(
string $class, string $alias, string $type
=
xPDOQuery, mixed $conditions
=
array, string $conjunction
=
xPDOQuery, array $binding
=
null, int $condGroup
=
0
)
:
\xPDOQuery
Join a table represented by the specified class.
Arguments
- $class
- string
The classname (or relation alias for aggregates and composites) of representing the table to be joined. - $alias
- string
An optional alias to represent the joined table in the constructed query. - $type
- string
The type of join to perform. See the xPDOQuery::SQL_JOIN constants. - $conditions
- mixed
Conditions of the join specified in any xPDO compatible criteria object or expression. - $conjunction
- string
A conjunction to be applied to the condition or conditions supplied. - $binding
- array
Optional bindings to accompany the conditions. - $condGroup
- int
An optional identifier for adding the conditions to a specific set of conjoined expressions.
Output
- \xPDOQuery
- Returns the current object for convenience.
Details
- visibility
- public
- final
- false
- static
- false
leftJoin
leftJoin(
$class, $alias, $conditions
=
array, $conjunction
=
xPDOQuery, $binding
=
null, $condGroup
=
0
)
:
Arguments
- $class
- $alias
- $conditions
- $conjunction
- $binding
- $condGroup
Details
- visibility
- public
- final
- false
- static
- false
limit
limit(
integer $limit, integer $offset
=
0
)
:
\xPDOQuery
Add a LIMIT/OFFSET clause to the query.
Arguments
- $limit
- integer
The number of records to return. - $offset
- integer
The location in the result set to start from.
Output
- \xPDOQuery
- Returns the instance.
Details
- visibility
- public
- final
- false
- static
- false
orCondition
orCondition(
$conditions, $binding
=
null, $group
=
0
)
:
Arguments
- $conditions
- $binding
- $group
Details
- visibility
- public
- final
- false
- static
- false
parseConditions
parseConditions(
mixed $conditions, string $conjunction
=
xPDOQuery
)
:
Parses an xPDO condition expression.
Arguments
- $conditions
- mixed
A valid xPDO condition expression. - $conjunction
- string
The optional conjunction for the condition( s ).
Details
- visibility
- public
- final
- false
- static
- false
prepare
prepare(
array $bindings
=
array, boolean $byValue
=
true, boolean|integer $cacheFlag
=
null
)
:
\PDOStatement
Prepares the xPDOQuery for execution.
The {@link xPDOCriteria::$sql} attribute must be set in order to prepare the statement. You can also pass bindings directly to this function and they will be run through {@link xPDOCriteria::bind()} if the statement is successfully prepared.
If the {@link xPDOCriteria::$stmt} already exists, it is simply returned.
Arguments
- $bindings
- array
Bindings to merge with any existing bindings defined for this xPDOCriteria instance. Bindings can be simple associative array of key-value pairs or the value for each key can contain elements titled value, type, and length corresponding to the appropriate parameters in the PDOStatement::bindValue() and PDOStatement::bindParam() functions. - $byValue
- boolean
Determines if the $bindings are to be bound as parameters (by variable reference, the default behavior) or by direct value (if true). - $cacheFlag
- booleaninteger
The cacheFlag indicates the cache state of the xPDOCriteria object and can be absolutely off (false), absolutely on (true), or an integer indicating the number of seconds the result will live in the cache.
Output
- \PDOStatement
- The PDOStatement representing the prepared query.
Details
- visibility
- public
- final
- false
- static
- false
rightJoin
rightJoin(
$class, $alias, $conditions
=
array, $conjunction
=
xPDOQuery, $binding
=
null, $condGroup
=
0
)
:
Arguments
- $class
- $alias
- $conditions
- $conjunction
- $binding
- $condGroup
Details
- visibility
- public
- final
- false
- static
- false
select
select(
string $columns
=
*
)
:
\xPDOQuery
Specify columns to return from the SQL query.
Arguments
- $columns
- string
Columns to return from the query.
Output
- \xPDOQuery
- Returns the current object for convenience.
Details
- visibility
- public
- final
- false
- static
- false
setClassAlias
setClassAlias(
string $alias
)
:
\xPDOQuery
Sets a SQL alias for the table represented by the main class.
Arguments
- $alias
- string
An alias for the main table for the SQL statement.
Output
- \xPDOQuery
- Returns the current object for convenience.
Details
- visibility
- public
- final
- false
- static
- false
sortby
sortby(
string $column, string $direction
=
ASC
)
:
\xPDOQuery
Add an ORDER BY clause to the query.
Arguments
- $column
- string
Column identifier to sort by. - $direction
- string
The direction to sort by, ASC or DESC.
Output
- \xPDOQuery
- Returns the instance.
Details
- visibility
- public
- final
- false
- static
- false
where
where(
mixed $conditions, string $conjunction
=
xPDOQuery, mixed $binding
=
null, integer $condGroup
=
0
)
:
\xPDOQuery
Add a WHERE condition to the query.
Arguments
- $conditions
- mixed
A valid xPDO criteria expression. - $conjunction
- string
The conjunction to use when appending this condition, i.e., AND or OR. - $binding
- mixed
A value or PDO binding representation of a value for the condition. - $condGroup
- integer
A numeric identifier for associating conditions into groups.
Output
- \xPDOQuery
- Returns the instance.
Details
- visibility
- public
- final
- false
- static
- false
wrap
wrap(
\xPDOCriteria $criteria
)
:
Wrap an existing xPDOCriteria into this xPDOQuery instance.
Arguments
- $criteria
- \xPDOCriteria
Details
- visibility
- public
- final
- false
- static
- false
\xPDOQueryCondition
- package
- xpdo
- subpackage
- om
- Properties
- $binding
- $conjunction
- $sql
- Methods
- __construct
Description
Abstracts individual query conditions used in xPDOQuery instances.
Properties
$binding
array $binding = 'array'
Details
- array
An array of value/parameter bindings for the condition. - visibility
- public
- default
- array
- final
- false
- static
- false
$conjunction
string $conjunction = 'xPDOQuery'
Details
- string
The conjunction identifying how the condition is related to the previous condition(s). - visibility
- public
- default
- xPDOQuery
- final
- false
- static
- false
$sql
string $sql = ''
Details
- string
The SQL string for the condition. - visibility
- public
- default
- final
- false
- static
- false