SelectExtender
class SelectExtender implements SelectInterface (View source)
The base extender class for Select queries.
Properties
| protected SelectInterface | $query | The Select query object we are extending/decorating. |
|
| protected Connection | $connection | The connection object on which to run this query. |
|
| protected string | $uniqueIdentifier | A unique identifier for this query object. |
|
| protected int | $placeholder | The placeholder counter. |
Methods
Returns a unique identifier for this object.
Returns the next placeholder ID for the query.
Adds a tag to a query.
Determines if a given query has a given tag.
Determines if a given query has all specified tags.
Determines if a given query has any specified tag.
Adds additional metadata to the query.
Retrieves a given piece of metadata.
Helper function: builds the most common conditional clauses.
Gets the, possibly nested, list of conditions in this conditional clause.
Gets a complete list of all values to insert into the prepared statement.
Adds an arbitrary WHERE clause to the query.
Compiles the saved conditions for later retrieval.
Check whether a condition has been previously compiled.
Helper function to build most common HAVING conditional clauses.
Gets a list of all conditions in the HAVING clause.
Gets a list of all values to insert into the HAVING clause.
Adds an arbitrary HAVING clause to the query.
Sets a condition in the HAVING clause that the specified field be NULL.
Sets a condition in the HAVING clause that the specified field be NOT NULL.
Sets a HAVING condition that the specified subquery returns values.
Sets a HAVING condition that the specified subquery returns no values.
Enhance this object by wrapping it in an extender object.
Returns a reference to the fields array for this query.
Returns a reference to the expressions array for this query.
Returns a reference to the order by array for this query.
Returns a reference to the group-by array for this query.
Returns a reference to the tables array for this query.
Returns a reference to the union queries for this query. This include queries for UNION, UNION ALL, and UNION DISTINCT.
Escapes characters that work as wildcard characters in a LIKE pattern.
Escapes a field name string.
Compiles and returns an associative array of the arguments for this prepared statement.
Indicates if preExecute() has already been called on that object.
Runs the query against the database.
Sets this query to be DISTINCT.
Adds a field to the list to be SELECTed.
Add multiple fields from the same table to be SELECTed.
Adds an expression to the list of "fields" to be SELECTed.
Default Join against another table in the database.
Inner Join against another table in the database.
Left Outer Join against another table in the database.
Join against another table in the database.
Orders the result set by a given field.
Orders the result set by a random value.
Restricts a query to a given range in the result set.
Groups the result set by the specified field.
Add FOR UPDATE to the query.
Get the equivalent COUNT query of this query as a new query object.
Sets a condition that is always false.
Returns a string representation of how the query will be executed in SQL.
Clone magic method.
Magic override for undefined methods.
Creates an object holding a group of conditions.
Creates a new group of conditions ANDed together.
Creates a new group of conditions ORed together.
Details
__construct(SelectInterface $query, Connection $connection)
No description
uniqueIdentifier()
Returns a unique identifier for this object.
The
nextPlaceholder()
Returns the next placeholder ID for the query.
$this
addTag($tag)
Adds a tag to a query.
Tags are strings that identify a query. A query may have any number of tags. Tags are used to mark a query so that alter hooks may decide if they wish to take action. Tags should be all lower-case and contain only letters, numbers, and underscore, and start with a letter. That is, they should follow the same rules as PHP identifiers in general.
true
hasTag($tag)
Determines if a given query has a given tag.
true
hasAllTags()
Determines if a given query has all specified tags.
Each tag to check should be supplied as a separate argument.
true
hasAnyTag()
Determines if a given query has any specified tag.
Each tag to check should be supplied as a separate argument.
$this
addMetaData($key, $object)
Adds additional metadata to the query.
Often, a query may need to provide additional contextual data to alter hooks. Alter hooks may then use that information to decide if and how to take action.
The
getMetaData($key)
Retrieves a given piece of metadata.
$this
condition(string|ConditionInterface $field, string|array|SelectInterface|null $value = NULL, string|null $operator = '=')
Helper function: builds the most common conditional clauses.
This method takes 1 to 3 parameters.
If called with 1 parameter, it should be a ConditionInterface that in itself forms a valid where clause. Use e.g. to build clauses with nested ANDs and ORs.
If called with 2 parameters, they are taken as $field and $value with $operator having a value of =.
Do not use this method to test for NULL values. Instead, use QueryConditionInterface::isNull() or QueryConditionInterface::isNotNull().
To improve readability, the operators EXISTS and NOT EXISTS have their own utility method defined.
Drupal considers LIKE case insensitive and the following is often used to tell the database that case insensitive equivalence is desired:
array
conditions()
Gets the, possibly nested, list of conditions in this conditional clause.
This method returns by reference. That allows alter hooks to access the data structure directly and manipulate it before it gets compiled.
The data structure that is returned is an indexed array of entries, where each entry looks like the following:
An
arguments()
Gets a complete list of all values to insert into the prepared statement.
$this
where(string $snippet, array $args = [])
Adds an arbitrary WHERE clause to the query.
compile(Connection $connection, PlaceholderInterface $queryPlaceholder)
Compiles the saved conditions for later retrieval.
This method does not return anything, but simply prepares data to be retrieved via __toString() and arguments().
true
compiled()
Check whether a condition has been previously compiled.
ConditionInterface
havingCondition($field, $value = NULL, $operator = '=')
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.
array
havingConditions()
Gets a list of all conditions in the HAVING clause.
This method returns by reference. That allows alter hooks to access the data structure directly and manipulate it before it gets compiled.
array
havingArguments()
Gets a list of all values to insert into the HAVING clause.
$this
having($snippet, $args = [])
Adds an arbitrary HAVING clause to the query.
havingCompile(Connection $connection)
Compiles the HAVING clause for later retrieval.
$this
havingIsNull($field)
Sets a condition in the HAVING clause that the specified field be NULL.
$this
havingIsNotNull($field)
Sets a condition in the HAVING clause that the specified field be NOT NULL.
$this
havingExists(SelectInterface $select)
Sets a HAVING condition that the specified subquery returns values.
$this
havingNotExists(SelectInterface $select)
Sets a HAVING condition that the specified subquery returns no values.
ExtendableInterface
extend($extender_name)
Enhance this object by wrapping it in an extender object.
A
getFields()
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:
A
getExpressions()
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:
A
getOrderBy()
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:
A
getGroupBy()
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:
A
getTables()
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:
A
getUnion()
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:
string
escapeLike($string)
Escapes characters that work as wildcard characters in a LIKE pattern.
The
escapeField(string $string)
Escapes a field name string.
Force all field names to be strictly alphanumeric-plus-underscore. For some database drivers, it may also wrap the field name in database-specific escape characters.
An
getArguments(PlaceholderInterface $queryPlaceholder = NULL)
Compiles and returns an associative array of the arguments for this prepared statement.
true
isPrepared()
Indicates if preExecute() has already been called on that object.
true
preExecute(SelectInterface $query = NULL)
Generic preparation and validation for a SELECT query.
StatementInterface|null
execute()
Runs the query against the database.
$this
distinct($distinct = TRUE)
Sets this query to be DISTINCT.
The
addField($table_alias, $field, $alias = NULL)
Adds a field to the list to be SELECTed.
$this
fields($table_alias, array $fields = [])
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.
The
addExpression($expression, $alias = NULL, $arguments = [])
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.
The
join($table, $alias = NULL, $condition = NULL, $arguments = [])
Default Join against another table in the database.
This method is a convenience method for innerJoin().
The
innerJoin($table, $alias = NULL, $condition = NULL, $arguments = [])
Inner Join against another table in the database.
The
leftJoin($table, $alias = NULL, $condition = NULL, $arguments = [])
Left Outer Join against another table in the database.
The
addJoin($type, $table, $alias = NULL, $condition = NULL, $arguments = [])
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.
$this
orderBy($field, $direction = 'ASC')
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.
$this
orderRandom()
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.
$this
range($start = NULL, $length = NULL)
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.
$this
union(SelectInterface $query, $type = '')
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.
$this
groupBy($field)
Groups the result set by the specified field.
ConditionInterface
forUpdate($set = TRUE)
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.
SelectInterface
countQuery()
Get the equivalent COUNT query of this query as a new query object.
$this
isNull(string|SelectInterface $field)
Sets a condition that the specified field be NULL.
$this
isNotNull(string|SelectInterface $field)
Sets a condition that the specified field be NOT NULL.
$this
exists(SelectInterface $select)
Sets a condition that the specified subquery returns values.
$this
notExists(SelectInterface $select)
Sets a condition that the specified subquery returns no values.
$this
alwaysFalse()
Sets a condition that is always false.
string
__toString()
Returns a string representation of how the query will be executed in SQL.
__clone()
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.
__call($method, $args)
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.
ConditionInterface
conditionGroupFactory($conjunction = 'AND')
Creates an object holding a group of conditions.
See andConditionGroup() and orConditionGroup() for more.
ConditionInterface
andConditionGroup()
Creates a new group of conditions ANDed together.
ConditionInterface
orConditionGroup()
Creates a new group of conditions ORed together.