corpus_parole: comparison cms/drupal/includes/database/select.inc

equal deleted inserted replaced

-:07239de796bb
+:e756a8c72c3d
+<?php
+/**
+* @addtogroup database
+* @{
+*/
+require_once dirname(__FILE__) . '/query.inc';
+/**
+* Interface for extendable query objects.
+*
+* "Extenders" follow the "Decorator" OOP design pattern.  That is, they wrap
+* and "decorate" another object.  In our case, they implement the same interface
+* as select queries and wrap a select query, to which they delegate almost all
+* operations.  Subclasses of this class may implement additional methods or
+* override existing methods as appropriate.  Extenders may also wrap other
+* extender objects, allowing for arbitrarily complex "enhanced" queries.
+*/
+interface QueryExtendableInterface {
+/**
+* Enhance this object by wrapping it in an extender object.
+*
+* @param $extender_name
+*   The base name of the extending class.  The base name will be checked
+*   against the current database connection to allow driver-specific subclasses
+*   as well, using the same logic as the query objects themselves.  For example,
+*   PagerDefault_mysql is the MySQL-specific override for PagerDefault.
+* @return QueryExtendableInterface
+*   The extender object, which now contains a reference to this object.
+*/
+public function extend($extender_name);
+}
+/**
+* Interface definition for a Select Query object.
+*/
+interface SelectQueryInterface extends QueryConditionInterface, QueryAlterableInterface, QueryExtendableInterface, QueryPlaceholderInterface {
+/* Alter accessors to expose the query data to alter hooks. */
+/**
+* Returns a reference to the fields array for this query.
+*
+* Because this method returns by reference, alter hooks may edit the fields
+* array directly to make their changes. If just adding fields, however, the
+* use of addField() is preferred.
+*
+* Note that this method must be called by reference as well:
+*
+* @code
+* $fields =& $query->getFields();
+* @endcode
+*
+* @return
+*   A reference to the fields array structure.
+*/
+public function &getFields();
+/**
+* Returns a reference to the expressions array for this query.
+*
+* Because this method returns by reference, alter hooks may edit the expressions
+* array directly to make their changes. If just adding expressions, however, the
+* use of addExpression() is preferred.
+*
+* Note that this method must be called by reference as well:
+*
+* @code
+* $fields =& $query->getExpressions();
+* @endcode
+*
+* @return
+*   A reference to the expression array structure.
+*/
+public function &getExpressions();
+/**
+* Returns a reference to the order by array for this query.
+*
+* Because this method returns by reference, alter hooks may edit the order-by
+* array directly to make their changes. If just adding additional ordering
+* fields, however, the use of orderBy() is preferred.
+*
+* Note that this method must be called by reference as well:
+*
+* @code
+* $fields =& $query->getOrderBy();
+* @endcode
+*
+* @return
+*   A reference to the expression array structure.
+*/
+public function &getOrderBy();
+/**
+* Returns a reference to the group-by array for this query.
+*
+* Because this method returns by reference, alter hooks may edit the group-by
+* array directly to make their changes. If just adding additional grouping
+* fields, however, the use of groupBy() is preferred.
+*
+* Note that this method must be called by reference as well:
+*
+* @code
+* $fields =& $query->getGroupBy();
+* @endcode
+*
+* @return
+*   A reference to the group-by array structure.
+*/
+public function &getGroupBy();
+/**
+* Returns a reference to the tables array for this query.
+*
+* Because this method returns by reference, alter hooks may edit the tables
+* array directly to make their changes. If just adding tables, however, the
+* use of the join() methods is preferred.
+*
+* Note that this method must be called by reference as well:
+*
+* @code
+* $fields =& $query->getTables();
+* @endcode
+*
+* @return
+*   A reference to the tables array structure.
+*/
+public function &getTables();
+/**
+* Returns a reference to the union queries for this query. This include
+* queries for UNION, UNION ALL, and UNION DISTINCT.
+*
+* Because this method returns by reference, alter hooks may edit the tables
+* array directly to make their changes. If just adding union queries,
+* however, the use of the union() method is preferred.
+*
+* Note that this method must be called by reference as well:
+*
+* @code
+* $fields =& $query->getUnion();
+* @endcode
+*
+* @return
+*   A reference to the union query array structure.
+*/
+public function &getUnion();
+/**
+* Compiles and returns an associative array of the arguments for this prepared statement.
+*
+* @param $queryPlaceholder
+*   When collecting the arguments of a subquery, the main placeholder
+*   object should be passed as this parameter.
+*
+* @return
+*   An associative array of all placeholder arguments for this query.
+*/
+public function getArguments(QueryPlaceholderInterface $queryPlaceholder = NULL);
+/* Query building operations */
+/**
+* Sets this query to be DISTINCT.
+*
+* @param $distinct
+*   TRUE to flag this query DISTINCT, FALSE to disable it.
+* @return SelectQueryInterface
+*   The called object.
+*/
+public function distinct($distinct = TRUE);
+/**
+* Adds a field to the list to be SELECTed.
+*
+* @param $table_alias
+*   The name of the table from which the field comes, as an alias. Generally
+*   you will want to use the return value of join() here to ensure that it is
+*   valid.
+* @param $field
+*   The name of the field.
+* @param $alias
+*   The alias for this field. If not specified, one will be generated
+*   automatically based on the $table_alias and $field. The alias will be
+*   checked for uniqueness, so the requested alias may not be the alias
+*   that is assigned in all cases.
+* @return
+*   The unique alias that was assigned for this field.
+*/
+public function addField($table_alias, $field, $alias = NULL);
+/**
+* Add multiple fields from the same table to be SELECTed.
+*
+* This method does not return the aliases set for the passed fields. In the
+* majority of cases that is not a problem, as the alias will be the field
+* name. However, if you do need to know the alias you can call getFields()
+* and examine the result to determine what alias was created. Alternatively,
+* simply use addField() for the few fields you care about and this method for
+* the rest.
+*
+* @param $table_alias
+*   The name of the table from which the field comes, as an alias. Generally
+*   you will want to use the return value of join() here to ensure that it is
+*   valid.
+* @param $fields
+*   An indexed array of fields present in the specified table that should be
+*   included in this query. If not specified, $table_alias.* will be generated
+*   without any aliases.
+* @return SelectQueryInterface
+*   The called object.
+*/
+public function fields($table_alias, array $fields = array());
+/**
+* Adds an expression to the list of "fields" to be SELECTed.
+*
+* An expression can be any arbitrary string that is valid SQL. That includes
+* various functions, which may in some cases be database-dependent. This
+* method makes no effort to correct for database-specific functions.
+*
+* @param $expression
+*   The expression string. May contain placeholders.
+* @param $alias
+*   The alias for this expression. If not specified, one will be generated
+*   automatically in the form "expression_#". The alias will be checked for
+*   uniqueness, so the requested alias may not be the alias that is assigned
+*   in all cases.
+* @param $arguments
+*   Any placeholder arguments needed for this expression.
+* @return
+*   The unique alias that was assigned for this expression.
+*/
+public function addExpression($expression, $alias = NULL, $arguments = array());
+/**
+* Default Join against another table in the database.
+*
+* This method is a convenience method for innerJoin().
+*
+* @param $table
+*   The table against which to join.
+* @param $alias
+*   The alias for the table. In most cases this should be the first letter
+*   of the table, or the first letter of each "word" in the table.
+* @param $condition
+*   The condition on which to join this table. If the join requires values,
+*   this clause should use a named placeholder and the value or values to
+*   insert should be passed in the 4th parameter. For the first table joined
+*   on a query, this value is ignored as the first table is taken as the base
+*   table. The token %alias can be used in this string to be replaced with
+*   the actual alias. This is useful when $alias is modified by the database
+*   system, for example, when joining the same table more than once.
+* @param $arguments
+*   An array of arguments to replace into the $condition of this join.
+* @return
+*   The unique alias that was assigned for this table.
+*/
+public function join($table, $alias = NULL, $condition = NULL, $arguments = array());
+/**
+* Inner Join against another table in the database.
+*
+* @param $table
+*   The table against which to join.
+* @param $alias
+*   The alias for the table. In most cases this should be the first letter
+*   of the table, or the first letter of each "word" in the table.
+* @param $condition
+*   The condition on which to join this table. If the join requires values,
+*   this clause should use a named placeholder and the value or values to
+*   insert should be passed in the 4th parameter. For the first table joined
+*   on a query, this value is ignored as the first table is taken as the base
+*   table. The token %alias can be used in this string to be replaced with
+*   the actual alias. This is useful when $alias is modified by the database
+*   system, for example, when joining the same table more than once.
+* @param $arguments
+*   An array of arguments to replace into the $condition of this join.
+* @return
+*   The unique alias that was assigned for this table.
+*/
+public function innerJoin($table, $alias = NULL, $condition = NULL, $arguments = array());
+/**
+* Left Outer Join against another table in the database.
+*
+* @param $table
+*   The table against which to join.
+* @param $alias
+*   The alias for the table. In most cases this should be the first letter
+*   of the table, or the first letter of each "word" in the table.
+* @param $condition
+*   The condition on which to join this table. If the join requires values,
+*   this clause should use a named placeholder and the value or values to
+*   insert should be passed in the 4th parameter. For the first table joined
+*   on a query, this value is ignored as the first table is taken as the base
+*   table. The token %alias can be used in this string to be replaced with
+*   the actual alias. This is useful when $alias is modified by the database
+*   system, for example, when joining the same table more than once.
+* @param $arguments
+*   An array of arguments to replace into the $condition of this join.
+* @return
+*   The unique alias that was assigned for this table.
+*/
+public function leftJoin($table, $alias = NULL, $condition = NULL, $arguments = array());
+/**
+* Right Outer Join against another table in the database.
+*
+* @param $table
+*   The table against which to join.
+* @param $alias
+*   The alias for the table. In most cases this should be the first letter
+*   of the table, or the first letter of each "word" in the table.
+* @param $condition
+*   The condition on which to join this table. If the join requires values,
+*   this clause should use a named placeholder and the value or values to
+*   insert should be passed in the 4th parameter. For the first table joined
+*   on a query, this value is ignored as the first table is taken as the base
+*   table. The token %alias can be used in this string to be replaced with
+*   the actual alias. This is useful when $alias is modified by the database
+*   system, for example, when joining the same table more than once.
+* @param $arguments
+*   An array of arguments to replace into the $condition of this join.
+* @return
+*   The unique alias that was assigned for this table.
+*/
+public function rightJoin($table, $alias = NULL, $condition = NULL, $arguments = array());
+/**
+* Join against another table in the database.
+*
+* This method does the "hard" work of queuing up a table to be joined against.
+* In some cases, that may include dipping into the Schema API to find the necessary
+* fields on which to join.
+*
+* @param $type
+*   The type of join. Typically one one of INNER, LEFT OUTER, and RIGHT OUTER.
+* @param $table
+*   The table against which to join. May be a string or another SelectQuery
+*   object. If a query object is passed, it will be used as a subselect.
+* @param $alias
+*   The alias for the table. In most cases this should be the first letter
+*   of the table, or the first letter of each "word" in the table. If omitted,
+*   one will be dynamically generated.
+* @param $condition
+*   The condition on which to join this table. If the join requires values,
+*   this clause should use a named placeholder and the value or values to
+*   insert should be passed in the 4th parameter. For the first table joined
+*   on a query, this value is ignored as the first table is taken as the base
+*   table. The token %alias can be used in this string to be replaced with
+*   the actual alias. This is useful when $alias is modified by the database
+*   system, for example, when joining the same table more than once.
+* @param $arguments
+*   An array of arguments to replace into the $condition of this join.
+* @return
+*   The unique alias that was assigned for this table.
+*/
+public function addJoin($type, $table, $alias = NULL, $condition = NULL, $arguments = array());
+/**
+* Orders the result set by a given field.
+*
+* If called multiple times, the query will order by each specified field in the
+* order this method is called.
+*
+* If the query uses DISTINCT or GROUP BY conditions, fields or expressions
+* that are used for the order must be selected to be compatible with some
+* databases like PostgreSQL. The PostgreSQL driver can handle simple cases
+* automatically but it is suggested to explicitly specify them. Additionally,
+* when ordering on an alias, the alias must be added before orderBy() is
+* called.
+*
+* @param $field
+*   The field on which to order.
+* @param $direction
+*   The direction to sort. Legal values are "ASC" and "DESC". Any other value
+*   will be converted to "ASC".
+* @return SelectQueryInterface
+*   The called object.
+*/
+public function orderBy($field, $direction = 'ASC');
+/**
+* Orders the result set by a random value.
+*
+* This may be stacked with other orderBy() calls. If so, the query will order
+* by each specified field, including this one, in the order called. Although
+* this method may be called multiple times on the same query, doing so
+* is not particularly useful.
+*
+* Note: The method used by most drivers may not scale to very large result
+* sets. If you need to work with extremely large data sets, you may create
+* your own database driver by subclassing off of an existing driver and
+* implementing your own randomization mechanism. See
+*
+* http://jan.kneschke.de/projects/mysql/order-by-rand/
+*
+* for an example of such an alternate sorting mechanism.
+*
+* @return SelectQueryInterface
+*   The called object
+*/
+public function orderRandom();
+/**
+* Restricts a query to a given range in the result set.
+*
+* If this method is called with no parameters, will remove any range
+* directives that have been set.
+*
+* @param $start
+*   The first record from the result set to return. If NULL, removes any
+*   range directives that are set.
+* @param $length
+*   The number of records to return from the result set.
+* @return SelectQueryInterface
+*   The called object.
+*/
+public function range($start = NULL, $length = NULL);
+/**
+* Add another Select query to UNION to this one.
+*
+* Union queries consist of two or more queries whose
+* results are effectively concatenated together. Queries
+* will be UNIONed in the order they are specified, with
+* this object's query coming first. Duplicate columns will
+* be discarded. All forms of UNION are supported, using
+* the second '$type' argument.
+*
+* Note: All queries UNIONed together must have the same
+* field structure, in the same order. It is up to the
+* caller to ensure that they match properly. If they do
+* not, an SQL syntax error will result.
+*
+* @param $query
+*   The query to UNION to this query.
+* @param $type
+*   The type of UNION to add to the query. Defaults to plain
+*   UNION.
+* @return SelectQueryInterface
+*   The called object.
+*/
+public function union(SelectQueryInterface $query, $type = '');
+/**
+* Groups the result set by the specified field.
+*
+* @param $field
+*   The field on which to group. This should be the field as aliased.
+* @return SelectQueryInterface
+*   The called object.
+*/
+public function groupBy($field);
+/**
+* Get the equivalent COUNT query of this query as a new query object.
+*
+* @return SelectQueryInterface
+*   A new SelectQuery object with no fields or expressions besides COUNT(*).
+*/
+public function countQuery();
+/**
+* Indicates if preExecute() has already been called on that object.
+*
+* @return
+*   TRUE is this query has already been prepared, FALSE otherwise.
+*/
+public function isPrepared();
+/**
+* Generic preparation and validation for a SELECT query.
+*
+* @return
+*   TRUE if the validation was successful, FALSE if not.
+*/
+public function preExecute(SelectQueryInterface $query = NULL);
+/**
+* Helper function to build most common HAVING conditional clauses.
+*
+* This method can take a variable number of parameters. If called with two
+* parameters, they are taken as $field and $value with $operator having a value
+* of IN if $value is an array and = otherwise.
+*
+* @param $field
+*   The name of the field to check. If you would like to add a more complex
+*   condition involving operators or functions, use having().
+* @param $value
+*   The value to test the field against. In most cases, this is a scalar. For more
+*   complex options, it is an array. The meaning of each element in the array is
+*   dependent on the $operator.
+* @param $operator
+*   The comparison operator, such as =, <, or >=. It also accepts more complex
+*   options such as IN, LIKE, or BETWEEN. Defaults to IN if $value is an array
+*   = otherwise.
+* @return QueryConditionInterface
+*   The called object.
+*/
+public function havingCondition($field, $value = NULL, $operator = NULL);
+/**
+* Clone magic method.
+*
+* Select queries have dependent objects that must be deep-cloned.  The
+* connection object itself, however, should not be cloned as that would
+* duplicate the connection itself.
+*/
+public function __clone();
+/**
+* Add FOR UPDATE to the query.
+*
+* FOR UPDATE prevents the rows retrieved by the SELECT statement from being
+* modified or deleted by other transactions until the current transaction
+* ends. Other transactions that attempt UPDATE, DELETE, or SELECT FOR UPDATE
+* of these rows will be blocked until the current transaction ends.
+*
+* @param $set
+*   IF TRUE, FOR UPDATE will be added to the query, if FALSE then it won't.
+*
+* @return QueryConditionInterface
+*   The called object.
+*/
+public function forUpdate($set = TRUE);
+}
+/**
+* The base extender class for Select queries.
+*/
+class SelectQueryExtender implements SelectQueryInterface {
+/**
+* The SelectQuery object we are extending/decorating.
+*
+* @var SelectQueryInterface
+*/
+protected $query;
+/**
+* The connection object on which to run this query.
+*
+* @var DatabaseConnection
+*/
+protected $connection;
+/**
+* A unique identifier for this query object.
+*/
+protected $uniqueIdentifier;
+/**
+* The placeholder counter.
+*/
+protected $placeholder = 0;
+public function __construct(SelectQueryInterface $query, DatabaseConnection $connection) {
+$this->uniqueIdentifier = uniqid('', TRUE);
+$this->query = $query;
+$this->connection = $connection;
+}
+/**
+* Implements QueryPlaceholderInterface::uniqueIdentifier().
+*/
+public function uniqueIdentifier() {
+return $this->uniqueIdentifier;
+}
+/**
+* Implements QueryPlaceholderInterface::nextPlaceholder().
+*/
+public function nextPlaceholder() {
+return $this->placeholder++;
+}
+/* Implementations of QueryAlterableInterface. */
+public function addTag($tag) {
+$this->query->addTag($tag);
+return $this;
+}
+public function hasTag($tag) {
+return $this->query->hasTag($tag);
+}
+public function hasAllTags() {
+$args = func_get_args();
+return call_user_func_array(array($this->query, 'hasAllTags'), $args);
+}
+public function hasAnyTag() {
+$args = func_get_args();
+return call_user_func_array(array($this->query, 'hasAnyTag'), $args);
+}
+public function addMetaData($key, $object) {
+$this->query->addMetaData($key, $object);
+return $this;
+}
+public function getMetaData($key) {
+return $this->query->getMetaData($key);
+}
+/* Implementations of QueryConditionInterface for the WHERE clause. */
+public function condition($field, $value = NULL, $operator = NULL) {
+$this->query->condition($field, $value, $operator);
+return $this;
+}
+public function &conditions() {
+return $this->query->conditions();
+}
+public function arguments() {
+return $this->query->arguments();
+}
+public function where($snippet, $args = array()) {
+$this->query->where($snippet, $args);
+return $this;
+}
+public function compile(DatabaseConnection $connection, QueryPlaceholderInterface $queryPlaceholder) {
+return $this->query->compile($connection, $queryPlaceholder);
+}
+public function compiled() {
+return $this->query->compiled();
+}
+/* Implementations of QueryConditionInterface for the HAVING clause. */
+public function havingCondition($field, $value = NULL, $operator = '=') {
+$this->query->havingCondition($field, $value, $operator);
+return $this;
+}
+public function &havingConditions() {
+return $this->query->havingConditions();
+}
+public function havingArguments() {
+return $this->query->havingArguments();
+}
+public function having($snippet, $args = array()) {
+$this->query->having($snippet, $args);
+return $this;
+}
+public function havingCompile(DatabaseConnection $connection) {
+return $this->query->havingCompile($connection);
+}
+/* Implementations of QueryExtendableInterface. */
+public function extend($extender_name) {
+// The extender can be anywhere so this needs to go to the registry, which
+// is surely loaded by now.
+$class = $this->connection->getDriverClass($extender_name, array(), TRUE);
+return new $class($this, $this->connection);
+}
+/* Alter accessors to expose the query data to alter hooks. */
+public function &getFields() {
+return $this->query->getFields();
+}
+public function &getExpressions() {
+return $this->query->getExpressions();
+}
+public function &getOrderBy() {
+return $this->query->getOrderBy();
+}
+public function &getGroupBy() {
+return $this->query->getGroupBy();
+}
+public function &getTables() {
+return $this->query->getTables();
+}
+public function &getUnion() {
+return $this->query->getUnion();
+}
+public function getArguments(QueryPlaceholderInterface $queryPlaceholder = NULL) {
+return $this->query->getArguments($queryPlaceholder);
+}
+public function isPrepared() {
+return $this->query->isPrepared();
+}
+public function preExecute(SelectQueryInterface $query = NULL) {
+// If no query object is passed in, use $this.
+if (!isset($query)) {
+$query = $this;
+}
+return $this->query->preExecute($query);
+}
+public function execute() {
+// By calling preExecute() here, we force it to preprocess the extender
+// object rather than just the base query object.  That means
+// hook_query_alter() gets access to the extended object.
+if (!$this->preExecute($this)) {
+return NULL;
+}
+return $this->query->execute();
+}
+public function distinct($distinct = TRUE) {
+$this->query->distinct($distinct);
+return $this;
+}
+public function addField($table_alias, $field, $alias = NULL) {
+return $this->query->addField($table_alias, $field, $alias);
+}
+public function fields($table_alias, array $fields = array()) {
+$this->query->fields($table_alias, $fields);
+return $this;
+}
+public function addExpression($expression, $alias = NULL, $arguments = array()) {
+return $this->query->addExpression($expression, $alias, $arguments);
+}
+public function join($table, $alias = NULL, $condition = NULL, $arguments = array()) {
+return $this->query->join($table, $alias, $condition, $arguments);
+}
+public function innerJoin($table, $alias = NULL, $condition = NULL, $arguments = array()) {
+return $this->query->innerJoin($table, $alias, $condition, $arguments);
+}
+public function leftJoin($table, $alias = NULL, $condition = NULL, $arguments = array()) {
+return $this->query->leftJoin($table, $alias, $condition, $arguments);
+}
+public function rightJoin($table, $alias = NULL, $condition = NULL, $arguments = array()) {
+return $this->query->rightJoin($table, $alias, $condition, $arguments);
+}
+public function addJoin($type, $table, $alias = NULL, $condition = NULL, $arguments = array()) {
+return $this->query->addJoin($type, $table, $alias, $condition, $arguments);
+}
+public function orderBy($field, $direction = 'ASC') {
+$this->query->orderBy($field, $direction);
+return $this;
+}
+public function orderRandom() {
+$this->query->orderRandom();
+return $this;
+}
+public function range($start = NULL, $length = NULL) {
+$this->query->range($start, $length);
+return $this;
+}
+public function union(SelectQueryInterface $query, $type = '') {
+$this->query->union($query, $type);
+return $this;
+}
+public function groupBy($field) {
+$this->query->groupBy($field);
+return $this;
+}
+public function forUpdate($set = TRUE) {
+$this->query->forUpdate($set);
+return $this;
+}
+public function countQuery() {
+return $this->query->countQuery();
+}
+function isNull($field) {
+$this->query->isNull($field);
+return $this;
+}
+function isNotNull($field) {
+$this->query->isNotNull($field);
+return $this;
+}
+public function exists(SelectQueryInterface $select) {
+$this->query->exists($select);
+return $this;
+}
+public function notExists(SelectQueryInterface $select) {
+$this->query->notExists($select);
+return $this;
+}
+public function __toString() {
+return (string) $this->query;
+}
+public function __clone() {
+$this->uniqueIdentifier = uniqid('', TRUE);
+// We need to deep-clone the query we're wrapping, which in turn may
+// deep-clone other objects.  Exciting!
+$this->query = clone($this->query);
+}
+/**
+* Magic override for undefined methods.
+*
+* If one extender extends another extender, then methods in the inner extender
+* will not be exposed on the outer extender.  That's because we cannot know
+* in advance what those methods will be, so we cannot provide wrapping
+* implementations as we do above.  Instead, we use this slower catch-all method
+* to handle any additional methods.
+*/
+public function __call($method, $args) {
+$return = call_user_func_array(array($this->query, $method), $args);
+// Some methods will return the called object as part of a fluent interface.
+// Others will return some useful value.  If it's a value, then the caller
+// probably wants that value.  If it's the called object, then we instead
+// return this object.  That way we don't "lose" an extender layer when
+// chaining methods together.
+if ($return instanceof SelectQueryInterface) {
+return $this;
+}
+else {
+return $return;
+}
+}
+}
+/**
+* Query builder for SELECT statements.
+*/
+class SelectQuery extends Query implements SelectQueryInterface {
+/**
+* The fields to SELECT.
+*
+* @var array
+*/
+protected $fields = array();
+/**
+* The expressions to SELECT as virtual fields.
+*
+* @var array
+*/
+protected $expressions = array();
+/**
+* The tables against which to JOIN.
+*
+* This property is a nested array. Each entry is an array representing
+* a single table against which to join. The structure of each entry is:
+*
+* array(
+*   'type' => $join_type (one of INNER, LEFT OUTER, RIGHT OUTER),
+*   'table' => $table,
+*   'alias' => $alias_of_the_table,
+*   'condition' => $condition_clause_on_which_to_join,
+*   'arguments' => $array_of_arguments_for_placeholders_in_the condition.
+*   'all_fields' => TRUE to SELECT $alias.*, FALSE or NULL otherwise.
+* )
+*
+* If $table is a string, it is taken as the name of a table. If it is
+* a SelectQuery object, it is taken as a subquery.
+*
+* @var array
+*/
+protected $tables = array();
+/**
+* The fields by which to order this query.
+*
+* This is an associative array. The keys are the fields to order, and the value
+* is the direction to order, either ASC or DESC.
+*
+* @var array
+*/
+protected $order = array();
+/**
+* The fields by which to group.
+*
+* @var array
+*/
+protected $group = array();
+/**
+* The conditional object for the WHERE clause.
+*
+* @var DatabaseCondition
+*/
+protected $where;
+/**
+* The conditional object for the HAVING clause.
+*
+* @var DatabaseCondition
+*/
+protected $having;
+/**
+* Whether or not this query should be DISTINCT
+*
+* @var boolean
+*/
+protected $distinct = FALSE;
+/**
+* The range limiters for this query.
+*
+* @var array
+*/
+protected $range;
+/**
+* An array whose elements specify a query to UNION, and the UNION type. The
+* 'type' key may be '', 'ALL', or 'DISTINCT' to represent a 'UNION',
+* 'UNION ALL', or 'UNION DISTINCT' statement, respectively.
+*
+* All entries in this array will be applied from front to back, with the
+* first query to union on the right of the original query, the second union
+* to the right of the first, etc.
+*
+* @var array
+*/
+protected $union = array();
+/**
+* Indicates if preExecute() has already been called.
+* @var boolean
+*/
+protected $prepared = FALSE;
+/**
+* The FOR UPDATE status
+*/
+protected $forUpdate = FALSE;
+public function __construct($table, $alias = NULL, DatabaseConnection $connection, $options = array()) {
+$options['return'] = Database::RETURN_STATEMENT;
+parent::__construct($connection, $options);
+$this->where = new DatabaseCondition('AND');
+$this->having = new DatabaseCondition('AND');
+$this->addJoin(NULL, $table, $alias);
+}
+/* Implementations of QueryAlterableInterface. */
+public function addTag($tag) {
+$this->alterTags[$tag] = 1;
+return $this;
+}
+public function hasTag($tag) {
+return isset($this->alterTags[$tag]);
+}
+public function hasAllTags() {
+$args = func_get_args();
+return !(boolean)array_diff($args, array_keys($this->alterTags));
+}
+public function hasAnyTag() {
+$args = func_get_args();
+return (boolean)array_intersect($args, array_keys($this->alterTags));
+}
+public function addMetaData($key, $object) {
+$this->alterMetaData[$key] = $object;
+return $this;
+}
+public function getMetaData($key) {
+return isset($this->alterMetaData[$key]) ? $this->alterMetaData[$key] : NULL;
+}
+/* Implementations of QueryConditionInterface for the WHERE clause. */
+public function condition($field, $value = NULL, $operator = NULL) {
+$this->where->condition($field, $value, $operator);
+return $this;
+}
+public function &conditions() {
+return $this->where->conditions();
+}
+public function arguments() {
+if (!$this->compiled()) {
+return NULL;
+}
+$args = $this->where->arguments() + $this->having->arguments();
+foreach ($this->tables as $table) {
+if ($table['arguments']) {
+$args += $table['arguments'];
+}
+// If this table is a subquery, grab its arguments recursively.
+if ($table['table'] instanceof SelectQueryInterface) {
+$args += $table['table']->arguments();
+}
+}
+foreach ($this->expressions as $expression) {
+if ($expression['arguments']) {
+$args += $expression['arguments'];
+}
+}
+// If there are any dependent queries to UNION,
+// incorporate their arguments recursively.
+foreach ($this->union as $union) {
+$args += $union['query']->arguments();
+}
+return $args;
+}
+public function where($snippet, $args = array()) {
+$this->where->where($snippet, $args);
+return $this;
+}
+public function isNull($field) {
+$this->where->isNull($field);
+return $this;
+}
+public function isNotNull($field) {
+$this->where->isNotNull($field);
+return $this;
+}
+public function exists(SelectQueryInterface $select) {
+$this->where->exists($select);
+return $this;
+}
+public function notExists(SelectQueryInterface $select) {
+$this->where->notExists($select);
+return $this;
+}
+public function compile(DatabaseConnection $connection, QueryPlaceholderInterface $queryPlaceholder) {
+$this->where->compile($connection, $queryPlaceholder);
+$this->having->compile($connection, $queryPlaceholder);
+foreach ($this->tables as $table) {
+// If this table is a subquery, compile it recursively.
+if ($table['table'] instanceof SelectQueryInterface) {
+$table['table']->compile($connection, $queryPlaceholder);
+}
+}
+// If there are any dependent queries to UNION, compile it recursively.
+foreach ($this->union as $union) {
+$union['query']->compile($connection, $queryPlaceholder);
+}
+}
+public function compiled() {
+if (!$this->where->compiled() || !$this->having->compiled()) {
+return FALSE;
+}
+foreach ($this->tables as $table) {
+// If this table is a subquery, check its status recursively.
+if ($table['table'] instanceof SelectQueryInterface) {
+if (!$table['table']->compiled()) {
+return FALSE;
+}
+}
+}
+foreach ($this->union as $union) {
+if (!$union['query']->compiled()) {
+return FALSE;
+}
+}
+return TRUE;
+}
+/* Implementations of QueryConditionInterface for the HAVING clause. */
+public function havingCondition($field, $value = NULL, $operator = NULL) {
+$this->having->condition($field, $value, $operator);
+return $this;
+}
+public function &havingConditions() {
+return $this->having->conditions();
+}
+public function havingArguments() {
+return $this->having->arguments();
+}
+public function having($snippet, $args = array()) {
+$this->having->where($snippet, $args);
+return $this;
+}
+public function havingCompile(DatabaseConnection $connection) {
+return $this->having->compile($connection, $this);
+}
+/* Implementations of QueryExtendableInterface. */
+public function extend($extender_name) {
+$override_class = $extender_name . '_' . $this->connection->driver();
+if (class_exists($override_class)) {
+$extender_name = $override_class;
+}
+return new $extender_name($this, $this->connection);
+}
+public function havingIsNull($field) {
+$this->having->isNull($field);
+return $this;
+}
+public function havingIsNotNull($field) {
+$this->having->isNotNull($field);
+return $this;
+}
+public function havingExists(SelectQueryInterface $select) {
+$this->having->exists($select);
+return $this;
+}
+public function havingNotExists(SelectQueryInterface $select) {
+$this->having->notExists($select);
+return $this;
+}
+public function forUpdate($set = TRUE) {
+if (isset($set)) {
+$this->forUpdate = $set;
+}
+return $this;
+}
+/* Alter accessors to expose the query data to alter hooks. */
+public function &getFields() {
+return $this->fields;
+}
+public function &getExpressions() {
+return $this->expressions;
+}
+public function &getOrderBy() {
+return $this->order;
+}
+public function &getGroupBy() {
+return $this->group;
+}
+public function &getTables() {
+return $this->tables;
+}
+public function &getUnion() {
+return $this->union;
+}
+public function getArguments(QueryPlaceholderInterface $queryPlaceholder = NULL) {
+if (!isset($queryPlaceholder)) {
+$queryPlaceholder = $this;
+}
+$this->compile($this->connection, $queryPlaceholder);
+return $this->arguments();
+}
+/**
+* Indicates if preExecute() has already been called on that object.
+*/
+public function isPrepared() {
+return $this->prepared;
+}
+/**
+* Generic preparation and validation for a SELECT query.
+*
+* @return
+*   TRUE if the validation was successful, FALSE if not.
+*/
+public function preExecute(SelectQueryInterface $query = NULL) {
+// If no query object is passed in, use $this.
+if (!isset($query)) {
+$query = $this;
+}
+// Only execute this once.
+if ($query->isPrepared()) {
+return TRUE;
+}
+// Modules may alter all queries or only those having a particular tag.
+if (isset($this->alterTags)) {
+// Many contrib modules assume that query tags used for access-checking
+// purposes follow the pattern $entity_type . '_access'. But this is
+// not the case for taxonomy terms, since core used to add term_access
+// instead of taxonomy_term_access to its queries. Provide backwards
+// compatibility by adding both tags here instead of attempting to fix
+// all contrib modules in a coordinated effort.
+// TODO:
+// - Extract this mechanism into a hook as part of a public (non-security)
+//   issue.
+// - Emit E_USER_DEPRECATED if term_access is used.
+//   https://www.drupal.org/node/2575081
+$term_access_tags = array('term_access' => 1, 'taxonomy_term_access' => 1);
+if (array_intersect_key($this->alterTags, $term_access_tags)) {
+$this->alterTags += $term_access_tags;
+}
+$hooks = array('query');
+foreach ($this->alterTags as $tag => $value) {
+$hooks[] = 'query_' . $tag;
+}
+drupal_alter($hooks, $query);
+}
+$this->prepared = TRUE;
+// Now also prepare any sub-queries.
+foreach ($this->tables as $table) {
+if ($table['table'] instanceof SelectQueryInterface) {
+$table['table']->preExecute();
+}
+}
+foreach ($this->union as $union) {
+$union['query']->preExecute();
+}
+return $this->prepared;
+}
+public function execute() {
+// If validation fails, simply return NULL.
+// Note that validation routines in preExecute() may throw exceptions instead.
+if (!$this->preExecute()) {
+return NULL;
+}
+$args = $this->getArguments();
+return $this->connection->query((string) $this, $args, $this->queryOptions);
+}
+public function distinct($distinct = TRUE) {
+$this->distinct = $distinct;
+return $this;
+}
+public function addField($table_alias, $field, $alias = NULL) {
+// If no alias is specified, first try the field name itself.
+if (empty($alias)) {
+$alias = $field;
+}
+// If that's already in use, try the table name and field name.
+if (!empty($this->fields[$alias])) {
+$alias = $table_alias . '_' . $field;
+}
+// If that is already used, just add a counter until we find an unused alias.
+$alias_candidate = $alias;
+$count = 2;
+while (!empty($this->fields[$alias_candidate])) {
+$alias_candidate = $alias . '_' . $count++;
+}
+$alias = $alias_candidate;
+$this->fields[$alias] = array(
+'field' => $field,
+'table' => $table_alias,
+'alias' => $alias,
+);
+return $alias;
+}
+public function fields($table_alias, array $fields = array()) {
+if ($fields) {
+foreach ($fields as $field) {
+// We don't care what alias was assigned.
+$this->addField($table_alias, $field);
+}
+}
+else {
+// We want all fields from this table.
+$this->tables[$table_alias]['all_fields'] = TRUE;
+}
+return $this;
+}
+public function addExpression($expression, $alias = NULL, $arguments = array()) {
+if (empty($alias)) {
+$alias = 'expression';
+}
+$alias_candidate = $alias;
+$count = 2;
+while (!empty($this->expressions[$alias_candidate])) {
+$alias_candidate = $alias . '_' . $count++;
+}
+$alias = $alias_candidate;
+$this->expressions[$alias] = array(
+'expression' => $expression,
+'alias' => $alias,
+'arguments' => $arguments,
+);
+return $alias;
+}
+public function join($table, $alias = NULL, $condition = NULL, $arguments = array()) {
+return $this->addJoin('INNER', $table, $alias, $condition, $arguments);
+}
+public function innerJoin($table, $alias = NULL, $condition = NULL, $arguments = array()) {
+return $this->addJoin('INNER', $table, $alias, $condition, $arguments);
+}
+public function leftJoin($table, $alias = NULL, $condition = NULL, $arguments = array()) {
+return $this->addJoin('LEFT OUTER', $table, $alias, $condition, $arguments);
+}
+public function rightJoin($table, $alias = NULL, $condition = NULL, $arguments = array()) {
+return $this->addJoin('RIGHT OUTER', $table, $alias, $condition, $arguments);
+}
+public function addJoin($type, $table, $alias = NULL, $condition = NULL, $arguments = array()) {
+if (empty($alias)) {
+if ($table instanceof SelectQueryInterface) {
+$alias = 'subquery';
+}
+else {
+$alias = $table;
+}
+}
+$alias_candidate = $alias;
+$count = 2;
+while (!empty($this->tables[$alias_candidate])) {
+$alias_candidate = $alias . '_' . $count++;
+}
+$alias = $alias_candidate;
+if (is_string($condition)) {
+$condition = str_replace('%alias', $alias, $condition);
+}
+$this->tables[$alias] = array(
+'join type' => $type,
+'table' => $table,
+'alias' => $alias,
+'condition' => $condition,
+'arguments' => $arguments,
+);
+return $alias;
+}
+public function orderBy($field, $direction = 'ASC') {
+// Only allow ASC and DESC, default to ASC.
+$direction = strtoupper($direction) == 'DESC' ? 'DESC' : 'ASC';
+$this->order[$field] = $direction;
+return $this;
+}
+public function orderRandom() {
+$alias = $this->addExpression('RAND()', 'random_field');
+$this->orderBy($alias);
+return $this;
+}
+public function range($start = NULL, $length = NULL) {
+$this->range = func_num_args() ? array('start' => $start, 'length' => $length) : array();
+return $this;
+}
+public function union(SelectQueryInterface $query, $type = '') {
+// Handle UNION aliasing.
+switch ($type) {
+// Fold UNION DISTINCT to UNION for better cross database support.
+case 'DISTINCT':
+case '':
+$type = 'UNION';
+break;
+case 'ALL':
+$type = 'UNION ALL';
+default:
+}
+$this->union[] = array(
+'type' => $type,
+'query' => $query,
+);
+return $this;
+}
+public function groupBy($field) {
+$this->group[$field] = $field;
+return $this;
+}
+public function countQuery() {
+// Create our new query object that we will mutate into a count query.
+$count = clone($this);
+$group_by = $count->getGroupBy();
+$having = $count->havingConditions();
+if (!$count->distinct && !isset($having[0])) {
+// When not executing a distinct query, we can zero-out existing fields
+// and expressions that are not used by a GROUP BY or HAVING. Fields
+// listed in a GROUP BY or HAVING clause need to be present in the
+// query.
+$fields =& $count->getFields();
+foreach (array_keys($fields) as $field) {
+if (empty($group_by[$field])) {
+unset($fields[$field]);
+}
+}
+$expressions =& $count->getExpressions();
+foreach (array_keys($expressions) as $field) {
+if (empty($group_by[$field])) {
+unset($expressions[$field]);
+}
+}
+// Also remove 'all_fields' statements, which are expanded into tablename.*
+// when the query is executed.
+foreach ($count->tables as $alias => &$table) {
+unset($table['all_fields']);
+}
+}
+// If we've just removed all fields from the query, make sure there is at
+// least one so that the query still runs.
+$count->addExpression('1');
+// Ordering a count query is a waste of cycles, and breaks on some
+// databases anyway.
+$orders = &$count->getOrderBy();
+$orders = array();
+if ($count->distinct && !empty($group_by)) {
+// If the query is distinct and contains a GROUP BY, we need to remove the
+// distinct because SQL99 does not support counting on distinct multiple fields.
+$count->distinct = FALSE;
+}
+$query = $this->connection->select($count);
+$query->addExpression('COUNT(*)');
+return $query;
+}
+public function __toString() {
+// For convenience, we compile the query ourselves if the caller forgot
+// to do it. This allows constructs like "(string) $query" to work. When
+// the query will be executed, it will be recompiled using the proper
+// placeholder generator anyway.
+if (!$this->compiled()) {
+$this->compile($this->connection, $this);
+}
+// Create a sanitized comment string to prepend to the query.
+$comments = $this->connection->makeComment($this->comments);
+// SELECT
+$query = $comments . 'SELECT ';
+if ($this->distinct) {
+$query .= 'DISTINCT ';
+}
+// FIELDS and EXPRESSIONS
+$fields = array();
+foreach ($this->tables as $alias => $table) {
+if (!empty($table['all_fields'])) {
+$fields[] = $this->connection->escapeTable($alias) . '.*';
+}
+}
+foreach ($this->fields as $alias => $field) {
+// Always use the AS keyword for field aliases, as some
+// databases require it (e.g., PostgreSQL).
+$fields[] = (isset($field['table']) ? $this->connection->escapeTable($field['table']) . '.' : '') . $this->connection->escapeField($field['field']) . ' AS ' . $this->connection->escapeAlias($field['alias']);
+}
+foreach ($this->expressions as $alias => $expression) {
+$fields[] = $expression['expression'] . ' AS ' . $this->connection->escapeAlias($expression['alias']);
+}
+$query .= implode(', ', $fields);
+// FROM - We presume all queries have a FROM, as any query that doesn't won't need the query builder anyway.
+$query .= "\nFROM ";
+foreach ($this->tables as $alias => $table) {
+$query .= "\n";
+if (isset($table['join type'])) {
+$query .= $table['join type'] . ' JOIN ';
+}
+// If the table is a subquery, compile it and integrate it into this query.
+if ($table['table'] instanceof SelectQueryInterface) {
+// Run preparation steps on this sub-query before converting to string.
+$subquery = $table['table'];
+$subquery->preExecute();
+$table_string = '(' . (string) $subquery . ')';
+}
+else {
+$table_string = '{' . $this->connection->escapeTable($table['table']) . '}';
+}
+// Don't use the AS keyword for table aliases, as some
+// databases don't support it (e.g., Oracle).
+$query .=  $table_string . ' ' . $this->connection->escapeTable($table['alias']);
+if (!empty($table['condition'])) {
+$query .= ' ON ' . $table['condition'];
+}
+}
+// WHERE
+if (count($this->where)) {
+// There is an implicit string cast on $this->condition.
+$query .= "\nWHERE " . $this->where;
+}
+// GROUP BY
+if ($this->group) {
+$query .= "\nGROUP BY " . implode(', ', $this->group);
+}
+// HAVING
+if (count($this->having)) {
+// There is an implicit string cast on $this->having.
+$query .= "\nHAVING " . $this->having;
+}
+// ORDER BY
+if ($this->order) {
+$query .= "\nORDER BY ";
+$fields = array();
+foreach ($this->order as $field => $direction) {
+$fields[] = $field . ' ' . $direction;
+}
+$query .= implode(', ', $fields);
+}
+// RANGE
+// There is no universal SQL standard for handling range or limit clauses.
+// Fortunately, all core-supported databases use the same range syntax.
+// Databases that need a different syntax can override this method and
+// do whatever alternate logic they need to.
+if (!empty($this->range)) {
+$query .= "\nLIMIT " . (int) $this->range['length'] . " OFFSET " . (int) $this->range['start'];
+}
+// UNION is a little odd, as the select queries to combine are passed into
+// this query, but syntactically they all end up on the same level.
+if ($this->union) {
+foreach ($this->union as $union) {
+$query .= ' ' . $union['type'] . ' ' . (string) $union['query'];
+}
+}
+if ($this->forUpdate) {
+$query .= ' FOR UPDATE';
+}
+return $query;
+}
+public function __clone() {
+// On cloning, also clone the dependent objects. However, we do not
+// want to clone the database connection object as that would duplicate the
+// connection itself.
+$this->where = clone($this->where);
+$this->having = clone($this->having);
+foreach ($this->union as $key => $aggregate) {
+$this->union[$key]['query'] = clone($aggregate['query']);
+}
+}
+}
+/**
+* @} End of "addtogroup database".
+*/