chill-bundles/src/Bundle/ChillMainBundle/Pagination/PaginatorInterface.php

<?php

declare(strict_types=1);

/*
 * Chill is a software for social workers
 *
 * For the full copyright and license information, please view
 * the LICENSE file that was distributed with this source code.
 */

namespace Chill\MainBundle\Pagination;

use Countable;
use Generator;
use RuntimeException;

/**
 * Represent a set of numbered pages.
 *
 * Allow to calculate and render pagination for a set of pages.
 *
 * The items are elements that `could` be shown. The item are divided and shown
 * into pages. Each page is numbered and count a given number of item per page.
 *
 * The first page number is 1, although the first result number is 0.
 */
interface PaginatorInterface extends Countable
{
    /**
     * get the number of pages for this pagination.
     *
     * @return int
     */
    public function countPages();

    /**
     * get the current page.
     *
     * @return PageInterface
     */
    public function getCurrentPage();

    /**
     * get the first result for the current page.
     *
     * @return int
     */
    public function getCurrentPageFirstItemNumber();

    /*
     * get the number of items per page
     */
    public function getItemsPerPage();

    /**
     * get the next page.
     *
     * @throws RuntimeException if the pagination has not next page
     *
     * @return PageInterface
     */
    public function getNextPage();

    /**
     * get page by his number.
     *
     * @param int $number
     *
     * @throws RuntimeException if the pagination has no page with specified number
     */
    public function getPage($number);

    /**
     * get a generator to generate pages.
     *
     * @return Generator which return PageInterface elements
     */
    public function getPagesGenerator();

    /**
     * get the previous page.
     *
     * @throws RuntimeException if the pagination has not previous page
     *
     * @return PageInterface
     */
    public function getPreviousPage();

    /**
     * get the number of results for this paginator.
     *
     * @return int
     */
    public function getTotalItems();

    /**
     * check if the current page has a next page.
     *
     * @return bool
     */
    public function hasNextPage();

    /**
     * check if the page with the given number exists.
     *
     * @param int $number
     */
    public function hasPage($number);

    /**
     * check if the current page has a page before.
     *
     * @return bool
     */
    public function hasPreviousPage();

    /**
     * check if the given page is the current page.
     *
     * @param \Chill\MainBundle\Pagination\PageInterface $page
     *
     * @return bool
     */
    public function isCurrentPage(PageInterface $page);

    /*
     * set the number of items per page
     */
    public function setItemsPerPage($itemsPerPage);
}