<?php

namespace Drupal\Core\Pager;

/**
 * This is a service for pager information.
 *
 * The pager.manager service manages the pager information which will eventually
 * be rendered into pager elements in the response. To gather information
 * related to pager information in the request, use the pager.parameters
 * service.
 *
 * Since there can be multiple pagers per requested page, each one is
 * represented by an 'element' ID. This is an integer. It represents the index
 * of the pager element within the 'page' query. The value of the element is an
 * integer telling us the current page number for that pager.
 *
 * @see \Drupal\Core\Pager\PagerParametersInterface
 */
interface PagerManagerInterface {

  /**
   * 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:
   * @code
   *   $query = $connection->select('some_table')
   *     ->extend(PagerSelectExtender::class);
   * @endcode
   *
   * 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:
   * @code
   *   // First find the total number of items and initialize the pager.
   *   $total = my_module_select("SELECT COUNT(*) FROM data WHERE status = 1")->result();
   *   $num_per_page = \Drupal::config('my_module.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 = my_module_select("SELECT * FROM data " . $where . " LIMIT %d, %d", $offset, $num_per_page)->fetchAll();
   *   $render = [];
   *   $render[] = [
   *     '#theme' => 'my_module_results',
   *     '#result' => $result,
   *   ];
   *
   *   // Finally, add the pager to the render array, and return.
   *   $render[] = ['#type' => 'pager'];
   *   return $render;
   * @endcode
   *
   * 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:
   * @code
   *
   *   // 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('my_module.settings')->get('num_per_page');
   *   $offset = $num_per_page * $page;
   *   $result = my_module_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;
   * @endcode
   *
   * @param int $total
   *   The total number of items to be paged.
   * @param int $limit
   *   The number of items the calling code will display per page.
   * @param int $element
   *   (optional) An integer to distinguish between multiple pagers on one page.
   *
   * @return \Drupal\Core\Pager\Pager
   *   The pager.
   */
  public function createPager($total, $limit, $element = 0);

  /**
   * Gets a pager from the static cache.
   *
   * @param int $element
   *   The pager element index.
   *
   * @return \Drupal\Core\Pager\Pager|null
   *   The pager, or null if not found.
   */
  public function getPager($element = 0);

  /**
   * Returns the current page being requested for display within a pager.
   *
   * @param int $pager_id
   *   (optional) An integer to distinguish between multiple pagers on one page.
   *
   * @return int
   *   The number of the current requested page, within the pager represented by
   *   $element. This is determined from the URL query parameter
   *   \Drupal::request()->query->get('page'), or 0 by default. Note that this
   *   number may differ from the actual page being displayed. For example, if a
   *   search for "example text" brings up three pages of results, but a user
   *   visits search/node/example+text?page=10, this function will return 10,
   *   even though the default pager implementation adjusts for this and still
   *   displays the third page of search results at that URL.
   */
  public function findPage(int $pager_id = 0): int;

  /**
   * Gets the URL query parameter array of a pager link.
   *
   * Adds to or adjusts the 'page' URL query parameter so that if you follow the
   * link, you'll get page $index for pager $element on the page.
   *
   * The 'page' URL query parameter is a comma-delimited string, where each
   * value is the target content page for the corresponding pager $element. For
   * instance, if we have 5 pagers on a single page, and we want to have a link
   * to a page that should display the 6th content page for the 3rd pager, and
   * the 1st content page for all the other pagers, then the URL query will look
   * like this: ?page=0,0,5,0,0 (page numbering starts at zero).
   *
   * @param array $query
   *   An associative array of URL query parameters to add to.
   * @param int $element
   *   An integer to distinguish between multiple pagers on one page.
   * @param int $index
   *   The index of the target page, for the given element, in the pager array.
   *
   * @return array
   *   The altered $query parameter array.
   */
  public function getUpdatedParameters(array $query, $element, $index);

  /**
   * Gets the extent of the pager page element IDs.
   *
   * @return int
   *   The maximum element ID available, -1 if there are no elements.
   */
  public function getMaxPagerElementId();

  /**
   * Reserve a pager element ID.
   *
   * Calling code may need to reserve the ID of a pager before actually creating
   * it. This methods allows to do so ensuring no collision occurs with
   * ::getMaxPagerElementId().
   *
   * @param int $element
   *   The ID of the pager to be reserved.
   *
   * @see \Drupal\Core\Database\Query\PagerSelectExtender::element()
   */
  public function reservePagerElementId(int $element): void;

}