class PagerSelectExtender in Drupal 9

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.

Hierarchy

• class \Drupal\Core\Database\Query\SelectExtender implements SelectInterface
  • class \Drupal\Core\Database\Query\PagerSelectExtender

15 files declare their use of PagerSelectExtender

CommentStorage.php in core/modules/comment/src/CommentStorage.php

DatabaseTestController.php in core/modules/system/tests/modules/database_test/src/Controller/DatabaseTestController.php

DatabaseTestForm.php in core/modules/system/tests/modules/database_test/src/Form/DatabaseTestForm.php

DbLogController.php in core/modules/dblog/src/Controller/DbLogController.php

ForumManager.php in core/modules/forum/src/ForumManager.php

... See full list

1 string reference to 'PagerSelectExtender'

ConnectionTest::providerGetDriverClass in core/tests/Drupal/Tests/Core/Database/ConnectionTest.php

Data provider for testGetDriverClass().

File

core/lib/Drupal/Core/Database/Query/PagerSelectExtender.php, line 17

Namespace

Drupal\Core\Database\Query

class PagerSelectExtender extends SelectExtender {

  /**
   * The highest element we've autogenerated so far.
   *
   * @var int
   *
   * @deprecated in drupal:9.2.0 and is removed from drupal:10.0.0. Use
   *   \Drupal::service('pager.manager')->getMaxPagerElementId() instead.
   *
   * @see https://www.drupal.org/node/3194594
   */
  public static $maxElement = 0;

  /**
   * The number of elements per page to allow.
   *
   * @var int
   */
  protected $limit = 10;

  /**
   * The unique ID of this pager on this page.
   *
   * @var int
   */
  protected $element = NULL;

  /**
   * The count query that will be used for this pager.
   *
   * @var \Drupal\Core\Database\Query\SelectInterface
   */
  protected $customCountQuery = FALSE;

  /**
   * Constructs a PagerSelectExtender object.
   *
   * @param \Drupal\Core\Database\Query\SelectInterface $query
   *   Select query object.
   * @param \Drupal\Core\Database\Connection $connection
   *   Database connection object.
   */
  public function __construct(SelectInterface $query, Connection $connection) {
    parent::__construct($query, $connection);

    // Add pager tag. Do this here to ensure that it is always added before
    // preExecute() is called.
    $this
      ->addTag('pager');
  }

  /**
   * Override the execute method.
   *
   * Before we run the query, we need to add pager-based range() instructions
   * to it.
   */
  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;
    }

    // A NULL limit is the "kill switch" for pager queries.
    if (empty($this->limit)) {
      return;
    }
    $this
      ->ensureElement();
    $total_items = $this
      ->getCountQuery()
      ->execute()
      ->fetchField();
    $pager = $this->connection
      ->getPagerManager()
      ->createPager($total_items, $this->limit, $this->element);
    $this
      ->range($pager
      ->getCurrentPage() * $this->limit, $this->limit);

    // Now that we've added our pager-based range instructions, run the query normally.
    return $this->query
      ->execute();
  }

  /**
   * Ensure that there is an element associated with this query.
   *
   * After running this method, access $this->element to get the element for this
   * query.
   */
  protected function ensureElement() {
    if (!isset($this->element)) {
      $this
        ->element($this->connection
        ->getPagerManager()
        ->getMaxPagerElementId() + 1);
    }
  }

  /**
   * 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.
   *
   * @param \Drupal\Core\Database\Query\SelectInterface $query
   *   The count query object.  It must return a single row with a single column,
   *   which is the total number of records.
   */
  public function setCountQuery(SelectInterface $query) {
    $this->customCountQuery = $query;
  }

  /**
   * Retrieve the count query for this pager.
   *
   * The count query may be specified manually or, by default, taken from the
   * query we are extending.
   *
   * @return \Drupal\Core\Database\Query\SelectInterface
   *   A count query object.
   */
  public function getCountQuery() {
    if ($this->customCountQuery) {
      return $this->customCountQuery;
    }
    else {
      return $this->query
        ->countQuery();
    }
  }

  /**
   * Specify the maximum number of elements per page for this query.
   *
   * The default if not specified is 10 items per page.
   *
   * @param int|false $limit
   *   An integer specifying the number of elements per page. If passed a false
   *   value (FALSE, 0, NULL), the pager is disabled.
   */
  public function limit($limit = 10) {
    $this->limit = $limit;
    return $this;
  }

  /**
   * 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.
   *
   * @param $element
   *   Element ID that is used to differentiate different pager queries.
   */
  public function element($element) {
    $this->element = $element;
    $this->connection
      ->getPagerManager()
      ->reservePagerElementId($this->element);
    return $this;
  }

  /**
   * 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.
   *
   * @return int
   *   Element ID that is used to differentiate between different pager
   *   queries.
   */
  public function getElement() : int {
    $this
      ->ensureElement();
    return $this->element;
  }

}

Members

Name	Modifiers	Type	Description	Overrides
PagerSelectExtender::$customCountQuery	protected	property	The count query that will be used for this pager.
PagerSelectExtender::$element	protected	property	The unique ID of this pager on this page.
PagerSelectExtender::$limit	protected	property	The number of elements per page to allow.
PagerSelectExtender::$maxElement Deprecated	public static	property	The highest element we've autogenerated so far.
PagerSelectExtender::element	public	function	Specify the element ID for this pager query.
PagerSelectExtender::ensureElement	protected	function	Ensure that there is an element associated with this query.
PagerSelectExtender::execute	public	function	Override the execute method. Overrides SelectExtender::execute
PagerSelectExtender::getCountQuery	public	function	Retrieve the count query for this pager.
PagerSelectExtender::getElement	public	function	Gets the element ID for this pager query.
PagerSelectExtender::limit	public	function	Specify the maximum number of elements per page for this query.
PagerSelectExtender::setCountQuery	public	function	Specify the count query object to use for this pager.
PagerSelectExtender::__construct	public	function	Constructs a PagerSelectExtender object. Overrides SelectExtender::__construct
SelectExtender::$connection	protected	property	The connection object on which to run this query.
SelectExtender::$placeholder	protected	property	The placeholder counter.
SelectExtender::$query	protected	property	The Select query object we are extending/decorating.
SelectExtender::$uniqueIdentifier	protected	property	A unique identifier for this query object.
SelectExtender::addExpression	public	function	Adds an expression to the list of "fields" to be SELECTed. Overrides SelectInterface::addExpression
SelectExtender::addField	public	function	Adds a field to the list to be SELECTed. Overrides SelectInterface::addField
SelectExtender::addJoin	public	function	Join against another table in the database. Overrides SelectInterface::addJoin
SelectExtender::addMetaData	public	function	Adds additional metadata to the query. Overrides AlterableInterface::addMetaData
SelectExtender::addTag	public	function	Adds a tag to a query. Overrides AlterableInterface::addTag
SelectExtender::alwaysFalse	public	function	Sets a condition that is always false. Overrides ConditionInterface::alwaysFalse
SelectExtender::andConditionGroup	public	function	Creates a new group of conditions ANDed together. Overrides ConditionInterface::andConditionGroup
SelectExtender::arguments	public	function	Gets a complete list of all values to insert into the prepared statement. Overrides ConditionInterface::arguments
SelectExtender::compile	public	function	Compiles the saved conditions for later retrieval. Overrides ConditionInterface::compile
SelectExtender::compiled	public	function	Check whether a condition has been previously compiled. Overrides ConditionInterface::compiled
SelectExtender::condition	public	function	Helper function: builds the most common conditional clauses. Overrides ConditionInterface::condition
SelectExtender::conditionGroupFactory	public	function	Creates an object holding a group of conditions. Overrides ConditionInterface::conditionGroupFactory
SelectExtender::conditions	public	function	Gets the, possibly nested, list of conditions in this conditional clause. Overrides ConditionInterface::conditions	1
SelectExtender::countQuery	public	function	Get the equivalent COUNT query of this query as a new query object. Overrides SelectInterface::countQuery	1
SelectExtender::distinct	public	function	Sets this query to be DISTINCT. Overrides SelectInterface::distinct
SelectExtender::escapeField	public	function	Escapes a field name string. Overrides SelectInterface::escapeField
SelectExtender::escapeLike	public	function	Escapes characters that work as wildcard characters in a LIKE pattern. Overrides SelectInterface::escapeLike
SelectExtender::exists	public	function	Sets a condition that the specified subquery returns values. Overrides ConditionInterface::exists
SelectExtender::extend	public	function	Enhance this object by wrapping it in an extender object. Overrides ExtendableInterface::extend
SelectExtender::fields	public	function	Add multiple fields from the same table to be SELECTed. Overrides SelectInterface::fields
SelectExtender::forUpdate	public	function	Add FOR UPDATE to the query. Overrides SelectInterface::forUpdate
SelectExtender::getArguments	public	function	Compiles and returns an associative array of the arguments for this prepared statement. Overrides SelectInterface::getArguments
SelectExtender::getExpressions	public	function	Returns a reference to the expressions array for this query. Overrides SelectInterface::getExpressions
SelectExtender::getFields	public	function	Returns a reference to the fields array for this query. Overrides SelectInterface::getFields
SelectExtender::getGroupBy	public	function	Returns a reference to the group-by array for this query. Overrides SelectInterface::getGroupBy
SelectExtender::getMetaData	public	function	Retrieves a given piece of metadata. Overrides AlterableInterface::getMetaData
SelectExtender::getOrderBy	public	function	Returns a reference to the order by array for this query. Overrides SelectInterface::getOrderBy
SelectExtender::getTables	public	function	Returns a reference to the tables array for this query. Overrides SelectInterface::getTables
SelectExtender::getUnion	public	function	Returns a reference to the union queries for this query. This include queries for UNION, UNION ALL, and UNION DISTINCT. Overrides SelectInterface::getUnion
SelectExtender::groupBy	public	function	Groups the result set by the specified field. Overrides SelectInterface::groupBy
SelectExtender::hasAllTags	public	function	Determines if a given query has all specified tags. Overrides AlterableInterface::hasAllTags
SelectExtender::hasAnyTag	public	function	Determines if a given query has any specified tag. Overrides AlterableInterface::hasAnyTag
SelectExtender::hasTag	public	function	Determines if a given query has a given tag. Overrides AlterableInterface::hasTag
SelectExtender::having	public	function	Adds an arbitrary HAVING clause to the query. Overrides SelectInterface::having
SelectExtender::havingArguments	public	function	Gets a list of all values to insert into the HAVING clause. Overrides SelectInterface::havingArguments
SelectExtender::havingCompile	public	function	Compiles the HAVING clause for later retrieval. Overrides SelectInterface::havingCompile
SelectExtender::havingCondition	public	function	Helper function to build most common HAVING conditional clauses. Overrides SelectInterface::havingCondition
SelectExtender::havingConditions	public	function	Gets a list of all conditions in the HAVING clause. Overrides SelectInterface::havingConditions
SelectExtender::havingExists	public	function	Sets a HAVING condition that the specified subquery returns values. Overrides SelectInterface::havingExists
SelectExtender::havingIsNotNull	public	function	Sets a condition in the HAVING clause that the specified field be NOT NULL. Overrides SelectInterface::havingIsNotNull
SelectExtender::havingIsNull	public	function	Sets a condition in the HAVING clause that the specified field be NULL. Overrides SelectInterface::havingIsNull
SelectExtender::havingNotExists	public	function	Sets a HAVING condition that the specified subquery returns no values. Overrides SelectInterface::havingNotExists
SelectExtender::innerJoin	public	function	Inner Join against another table in the database. Overrides SelectInterface::innerJoin
SelectExtender::isNotNull	public	function	Sets a condition that the specified field be NOT NULL. Overrides ConditionInterface::isNotNull
SelectExtender::isNull	public	function	Sets a condition that the specified field be NULL. Overrides ConditionInterface::isNull
SelectExtender::isPrepared	public	function	Indicates if preExecute() has already been called on that object. Overrides SelectInterface::isPrepared
SelectExtender::join	public	function	Default Join against another table in the database. Overrides SelectInterface::join
SelectExtender::leftJoin	public	function	Left Outer Join against another table in the database. Overrides SelectInterface::leftJoin
SelectExtender::nextPlaceholder	public	function	Returns the next placeholder ID for the query. Overrides PlaceholderInterface::nextPlaceholder
SelectExtender::notExists	public	function	Sets a condition that the specified subquery returns no values. Overrides ConditionInterface::notExists
SelectExtender::orConditionGroup	public	function	Creates a new group of conditions ORed together. Overrides ConditionInterface::orConditionGroup
SelectExtender::orderBy	public	function	Orders the result set by a given field. Overrides SelectInterface::orderBy
SelectExtender::orderRandom	public	function	Orders the result set by a random value. Overrides SelectInterface::orderRandom
SelectExtender::preExecute	public	function	Generic preparation and validation for a SELECT query. Overrides SelectInterface::preExecute	1
SelectExtender::range	public	function	Restricts a query to a given range in the result set. Overrides SelectInterface::range
SelectExtender::union	public	function	Add another Select query to UNION to this one. Overrides SelectInterface::union
SelectExtender::uniqueIdentifier	public	function	Returns a unique identifier for this object. Overrides PlaceholderInterface::uniqueIdentifier
SelectExtender::where	public	function	Adds an arbitrary WHERE clause to the query. Overrides ConditionInterface::where
SelectExtender::__call	public	function	Magic override for undefined methods.
SelectExtender::__clone	public	function	Clone magic method. Overrides SelectInterface::__clone
SelectExtender::__toString	public	function	Returns a string representation of how the query will be executed in SQL. Overrides SelectInterface::__toString