class PagerSelectExtender

Same name in other branches
  1. 8.9.x core/lib/Drupal/Core/Database/Query/PagerSelectExtender.php \Drupal\Core\Database\Query\PagerSelectExtender
  2. 10 core/tests/fixtures/database_drivers/module/core_fake/src/Driver/Database/CoreFakeWithAllCustomClasses/PagerSelectExtender.php \Drupal\core_fake\Driver\Database\CoreFakeWithAllCustomClasses\PagerSelectExtender
  3. 10 core/lib/Drupal/Core/Database/Query/PagerSelectExtender.php \Drupal\Core\Database\Query\PagerSelectExtender
  4. 11.x core/tests/fixtures/database_drivers/module/core_fake/src/Driver/Database/CoreFakeWithAllCustomClasses/PagerSelectExtender.php \Drupal\core_fake\Driver\Database\CoreFakeWithAllCustomClasses\PagerSelectExtender
  5. 11.x core/lib/Drupal/Core/Database/Query/PagerSelectExtender.php \Drupal\Core\Database\Query\PagerSelectExtender

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

Expanded class hierarchy of 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
View source
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

Title Sort descending Deprecated Modifiers Object type Summary Overriden Title 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 Overrides SelectInterface::addExpression
SelectExtender::addField public function Overrides SelectInterface::addField
SelectExtender::addJoin public function Overrides SelectInterface::addJoin
SelectExtender::addMetaData public function Overrides AlterableInterface::addMetaData
SelectExtender::addTag public function Overrides AlterableInterface::addTag
SelectExtender::alwaysFalse public function Overrides ConditionInterface::alwaysFalse
SelectExtender::andConditionGroup public function Overrides ConditionInterface::andConditionGroup
SelectExtender::arguments public function Overrides ConditionInterface::arguments
SelectExtender::compile public function Overrides ConditionInterface::compile
SelectExtender::compiled public function Overrides ConditionInterface::compiled
SelectExtender::condition public function Overrides ConditionInterface::condition
SelectExtender::conditionGroupFactory public function Overrides ConditionInterface::conditionGroupFactory
SelectExtender::conditions public function Overrides ConditionInterface::conditions 1
SelectExtender::countQuery public function Overrides SelectInterface::countQuery 1
SelectExtender::distinct public function Overrides SelectInterface::distinct
SelectExtender::escapeField public function Overrides SelectInterface::escapeField
SelectExtender::escapeLike public function Overrides SelectInterface::escapeLike
SelectExtender::exists public function Overrides ConditionInterface::exists
SelectExtender::extend public function Overrides ExtendableInterface::extend
SelectExtender::fields public function Overrides SelectInterface::fields
SelectExtender::forUpdate public function Overrides SelectInterface::forUpdate
SelectExtender::getArguments public function Overrides SelectInterface::getArguments
SelectExtender::getExpressions public function Overrides SelectInterface::getExpressions
SelectExtender::getFields public function Overrides SelectInterface::getFields
SelectExtender::getGroupBy public function Overrides SelectInterface::getGroupBy
SelectExtender::getMetaData public function Overrides AlterableInterface::getMetaData
SelectExtender::getOrderBy public function Overrides SelectInterface::getOrderBy
SelectExtender::getTables public function Overrides SelectInterface::getTables
SelectExtender::getUnion public function Overrides SelectInterface::getUnion
SelectExtender::groupBy public function Overrides SelectInterface::groupBy
SelectExtender::hasAllTags public function Overrides AlterableInterface::hasAllTags
SelectExtender::hasAnyTag public function Overrides AlterableInterface::hasAnyTag
SelectExtender::hasTag public function Overrides AlterableInterface::hasTag
SelectExtender::having public function Overrides SelectInterface::having
SelectExtender::havingArguments public function Overrides SelectInterface::havingArguments
SelectExtender::havingCompile public function Overrides SelectInterface::havingCompile
SelectExtender::havingCondition public function Overrides SelectInterface::havingCondition
SelectExtender::havingConditions public function Overrides SelectInterface::havingConditions
SelectExtender::havingExists public function Overrides SelectInterface::havingExists
SelectExtender::havingIsNotNull public function Overrides SelectInterface::havingIsNotNull
SelectExtender::havingIsNull public function Overrides SelectInterface::havingIsNull
SelectExtender::havingNotExists public function Overrides SelectInterface::havingNotExists
SelectExtender::innerJoin public function Overrides SelectInterface::innerJoin
SelectExtender::isNotNull public function Overrides ConditionInterface::isNotNull
SelectExtender::isNull public function Overrides ConditionInterface::isNull
SelectExtender::isPrepared public function Overrides SelectInterface::isPrepared
SelectExtender::join public function Overrides SelectInterface::join
SelectExtender::leftJoin public function Overrides SelectInterface::leftJoin
SelectExtender::nextPlaceholder public function Overrides PlaceholderInterface::nextPlaceholder
SelectExtender::notExists public function Overrides ConditionInterface::notExists
SelectExtender::orConditionGroup public function Overrides ConditionInterface::orConditionGroup
SelectExtender::orderBy public function Overrides SelectInterface::orderBy
SelectExtender::orderRandom public function Overrides SelectInterface::orderRandom
SelectExtender::preExecute public function Overrides SelectInterface::preExecute 1
SelectExtender::range public function Overrides SelectInterface::range
SelectExtender::union public function Overrides SelectInterface::union
SelectExtender::uniqueIdentifier public function Overrides PlaceholderInterface::uniqueIdentifier
SelectExtender::where public function Overrides ConditionInterface::where
SelectExtender::__call public function Magic override for undefined methods.
SelectExtender::__clone public function Overrides SelectInterface::__clone
SelectExtender::__toString public function Overrides SelectInterface::__toString

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.