PagerSelectExtender
class PagerSelectExtender extends SelectExtender (View source)
Query extender for pager queries.
This is the "default" pager mechanism. It creates a paged query with a fixed number of entries per page.
When adding this extender along with other extenders, be sure to add PagerSelectExtender last, so that its range and count are based on the full query.
Properties
| protected SelectInterface | $query | The Select query object we are extending/decorating. |
from SelectExtender |
| protected Connection | $connection | The connection object on which to run this query. |
from SelectExtender |
| protected string | $uniqueIdentifier | A unique identifier for this query object. |
from SelectExtender |
| protected int | $placeholder | The placeholder counter. |
from SelectExtender |
| protected int | $limit | The number of elements per page to allow. |
|
| protected int | $element | The unique ID of this pager on this page. |
|
| protected SelectInterface | $customCountQuery | The count query that will be used for this pager. |
Methods
Constructs a PagerSelectExtender object.
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.
Helper function to build most common HAVING conditional clauses.
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 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.
Compiles and returns an associative array of the arguments for this prepared statement.
Indicates if preExecute() has already been called on that object.
Override the execute method.
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.
Restricts a query to a given range in the result set.
Get the equivalent COUNT query of this query as a new query object.
Returns a string representation of how the query will be executed in SQL.
Creates an object holding a group of conditions.
Creates a new group of conditions ANDed together.
Creates a new group of conditions ORed together.
Ensure that there is an element associated with this query.
Retrieve the count query for this pager.
Specify the maximum number of elements per page for this query.
Specify the element ID for this pager query.
Gets the element ID for this pager query.
Details
__construct(SelectInterface $query, Connection $connection)
Constructs a PagerSelectExtender object.
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()
Override the execute method.
Before we run the query, we need to add pager-based range() instructions to it.
$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.
protected
ensureElement()
Ensure that there is an element associated with this query.
After running this method, access $this->element to get the element for this query.
setCountQuery(SelectInterface $query)
Specify the count query object to use for this pager.
You will rarely need to specify a count query directly. If not specified, one is generated off of the pager query itself.
SelectInterface
getCountQuery()
Retrieve the count query for this pager.
The count query may be specified manually or, by default, taken from the query we are extending.
limit(int|false $limit = 10)
Specify the maximum number of elements per page for this query.
The default if not specified is 10 items per page.
element($element)
Specify the element ID for this pager query.
The element is used to differentiate different pager queries on the same page so that they may be operated independently. If you do not specify an element, every pager query on the page will get a unique element. If for whatever reason you want to explicitly define an element for a given query, you may do so here.
Note that no collision detection is done when setting an element ID explicitly, so it is possible for two pagers to end up using the same ID if both are set explicitly.
int
getElement()
Gets the element ID for this pager query.
The element is used to differentiate different pager queries on the same page so that they may be operated independently.