PHP Class PageIterator

PageIterator is a class for stepping through an array, such as a database query result, page by page.
It returns the index numbers of the elements to be displayed on each page and page numbers for links to previous and next pages.
Page Iterator does not mess with the design of your page, nor with your database. It only handles the logic of browsing through a large set of data.


Scenario

require_once 'PageIterator.inc';
if (empty($pageNo)) $pageNo = 1;

// $recordSet is an array of data to be printed
$paginator = new PageIterator(sizeof($recordSet), $pageNo);

// Print links to the previous and next pages
while ($paginator -> hasNextPage()) {
    $ndx = $paginator -> nextPage();
    if ($ndx == $pageNo) {
        echo "[Page $ndx]";
        echo '  ';
    }
    else {
        echo '<a href="' . basename($PHP_SELF) . "?pageNo=$ndx" . '">';
        echo "[Page $ndx]";
        echo '</a>&nbsp; ';
    }
}
echo '<br /><br />';

// Print the contents of $recordSet
while ($paginator -> hasNextElement()) {
    $ndx = $paginator -> nextElement();
    echo 'Record No. ' . ($ndx + 1) . ': ' . $recordSet[$ndx] . '<br />';
}


Constructor

PageIterator($elementCount [, $currentPage [, $elementsPerPage [, $maxLinks [, $currentElement]]]])
int $elementCount The total number of elements in the data set (or the size of the array) to be iterated over.
optional int $elementsPerPage The number of elements to be displayed per page. Defaults to 10.
optional int $currentPage The number of the page to be displayed (1 - n).
This argument will be ignored if $currentElement is specified.
optional int $maxLinks The maximum number of page links (3 or more).
If not specified, PageIterator will return a link to every page.
optional int $currentElement The index number of the currently active element (0 - n-1).
Note! Using $currentElement is most useful for static data sets. In dynamic data sets, such as the result of a database query, the index number of an element may change with each page request.

Functions

Only functions considered public are documented here.

Functions related to page numbers

boolean hasNextPage()
Returns true if there are more page links to be printed.
Use this function in a while loop with nextPage() in order to print the correct number of page links.

int nextPage()
Returns the number of the next page to be linked to and moves the pointer to the next page link. You can only call this function once with every page because the pointer moves forward each time.
In order to print the page links over again, you must first call firstPage() to reset the pointer.
For considerations of efficiency, this function does not check if the maximum number of links is exceeded. Use hasNextPage() in a loop to print the correct number of links.

int firstPage()
Resets the pointer and returns the number of the first page to be linked to. It is not necessary to call this function the first time you iterate the page links.

mixed getPreviousPageNumber()
Returns the number of the previous page, or false if the first page is active.

mixed getNextPageNumber()
Returns the number of the next page to be displayed, or false if the last page has been reached.

int getCurrentPageNumber()
Returns the number of the page currently displayed.

int getPageCount()
Returns the total number of pages to be displayed.

Functions related to element numbers

boolean hasNextElement()
Returns true if more elements are to be printed in the current page.
It is vital to call this function before every call to nextElement() in order to avoid an offset error.

int nextElement()
Returns the number of the next element to be printed and moves the pointer to the subsequent element. You can only call this function once with every element because the pointer moves forward each time.
In order to print the elements over again, you must first call firstElement() to reset the pointer.
For considerations of efficiency, this function does not check if any further elements should be printed. Therefore, it is vital to call hasNextElement() before every call to nextElement(). Otherwise, you will print too many elements in the current page and, ultimately, receive an ‘undefined offset’ error.

int firstElement()
Resets the pointer and returns the number of the first element to be printed. It is not necessary to call this function the first time you iterate the element list.

int getFirstElementNumber()
Returns the number of the first element to be displayed in the current page.

int getLastElementNumber()
Returns the number of the last element to be displayed in the current page.

int getElementCount()
Returns the total number of elements (= the size of the array to be iterated).

[End of documentation]