Same name and namespace in other branches

1. 8.9.x core/lib/Drupal/Core/Pager/PagerManager.php \Drupal\Core\Pager\PagerManager::createPager()
2. 10 core/lib/Drupal/Core/Pager/PagerManager.php \Drupal\Core\Pager\PagerManager::createPager()
3. 11.x core/lib/Drupal/Core/Pager/PagerManager.php \Drupal\Core\Pager\PagerManager::createPager()

Initializes a pager.

This function sets up the necessary variables so that the render system will correctly process #type 'pager' render arrays to output pagers that correspond to the items being displayed.

If the items being displayed result from a database query performed using Drupal's database API, and if you have control over the construction of the database query, you do not need to call this function directly; instead, you can extend the query object with the 'PagerSelectExtender' extender before executing it. For example:

$query = $connection->select('some_table')
  ->extend(PagerSelectExtender::class);

However, if you are using a different method for generating the items to be paged through, then you should call this service in preparation.

The following example shows how this service can be used in a controller that invokes an external datastore with an SQL-like syntax:

// First find the total number of items and initialize the pager.
$total = mymodule_select("SELECT COUNT(*) FROM data WHERE status = 1")->result();
$num_per_page = \Drupal::config('mymodule.settings')->get('num_per_page');
$pager = \Drupal::service('pager.manager')->createPager($total, $num_per_page);
$page = $pager->getCurrentPage();
// Next, retrieve the items for the current page and put them into a
// render array.
$offset = $num_per_page * $page;
$result = mymodule_select("SELECT * FROM data " . $where . " LIMIT %d, %d", $offset, $num_per_page)->fetchAll();
$render = [];
$render[] = [
  '#theme' => 'mymodule_results',
  '#result' => $result,
];
// Finally, add the pager to the render array, and return.
$render[] = [
  '#type' => 'pager',
];
return $render;

A second example involves a controller that invokes an external search service where the total number of matching results is provided as part of the returned set (so that we do not need a separate query in order to obtain this information). Here, we call PagerManagerInterface->findPage() to calculate the desired offset before the search is invoked:

// Perform the query, using the requested offset from
// PagerManagerInterface::findPage(). This comes from a URL parameter, so
// here we are assuming that the URL parameter corresponds to an actual
// page of results that will exist within the set.
$pager_manager = \Drupal::service('pager.manager');
$page = $pager_manager->findPage();
$num_per_page = \Drupal::config('mymodule.settings')->get('num_per_page');
$offset = $num_per_page * $page;
$result = mymodule_remote_search($keywords, $offset, $num_per_page);
// Now that we have the total number of results, initialize the pager.
$pager_manager = \Drupal::service('pager.manager');
$pager_manager->createPager($result->total, $num_per_page);
// Create a render array with the search results.
$render = [];
$render[] = [
  '#theme' => 'search_results',
  '#results' => $result->data,
  '#type' => 'remote',
];
// Finally, add the pager to the render array, and return.
$render[] = [
  '#type' => 'pager',
];
return $render;

Parameters

int $total: The total number of items to be paged.

int $limit: The number of items the calling code will display per page.

int $element: (optional) An integer to distinguish between multiple pagers on one page.

Return value

\Drupal\Core\Pager\Pager The pager.

Overrides PagerManagerInterface::createPager

File

core/lib/Drupal/Core/Pager/PagerManager.php, line 55

Class

PagerManager

Provides a manager for pagers.

Namespace

Drupal\Core\Pager

Code

public function createPager($total, $limit, $element = 0) {
  $currentPage = $this->pagerParams
    ->findPage($element);
  $pager = new Pager($total, $limit, $currentPage);
  $this->setPager($pager, $element);
  return $pager;
}

---