UsagePaginating data collections
In order to paginate items into pages, Zend_Paginator
must have a generic way of accessing that data. For that reason,
all data access takes place through data source adapters. Several
adapters ship with Zend Framework by default:
Adapters for Zend_PaginatorAdapterDescriptionArrayUse a PHP arrayDbSelect
Use a Zend_Db_Select
instance, which will return an array
DbTableSelect
Use a Zend_Db_Table_Select
instance, which will return an instance of
Zend_Db_Table_Rowset_Abstract.
This provides additional information about the
result set, such as column names.
Iterator
Use an Iterator
instance
Null
Do not use Zend_Paginator to manage
data pagination. You can still take advantage of
the pagination control feature.
Instead of selecting every matching row of a given query, the
DbSelect and DbTableSelect adapters retrieve only the smallest
amount of data necessary for displaying the current page.
Because of this, a second query is dynamically generated to
determine the total number of matching rows. However, it is
possible to directly supply a count or count query yourself.
See the setRowCount() method in the DbSelect
adapter for more information.
To create an instance of Zend_Paginator, you must
supply an adapter to the constructor:
For convenience, you may take advantage of the static
factory() method for the adapters packaged with Zend
Framework:
In the case of the Null adapter, in lieu of a data collection
you must supply an item count to its constructor.
Although the instance is technically usable in this state, in your
controller action you'll need to tell the paginator what page
number the user requested. This allows him to advance through the
paginated data.
setCurrentPageNumber($page);
]]>
The simplest way to keep track of this value is through a URL.
Although we recommend using a
Zend_Controller_Router_Interface-compatible
router to handle this, it is not a requirement.
The following is an example route you might use in an INI
configuration file:
With the above route (and using Zend Framework MVC components),
you might set the current page number like this:
setCurrentPageNumber($this->_getParam('page'));
]]>
There are other options available; see
Configuration
for more on them.
Finally, you'll need to assign the paginator instance to your view.
If you're using Zend_View with the ViewRenderer action
helper, the following will work:
view->paginator = $paginator;
]]>The DbSelect and DbTableSelect adapter
The usage of most adapters is pretty straight-forward. However, the
database adapters require a more detailed explanation regarding
the retrieval and count of the data from the database.
To use the DbSelect and DbTableSelect adapters you don't have to retrieve the data
upfront from the database. Both adapters do the retrieval for you, aswell as the
counting of the total pages. If additional work has to be done on the database results
the adapter getItems() method has to be extended in your
application.
Additionally these adapters do not fetch all records from the
database in order to count them. Instead, the adapters manipulates the original query to
produce the corresponding COUNT query. Paginator then executes that COUNT query to get
the number of rows. This does require an extra round-trip to the database, but this is
many times faster than fetching an entire result set and using
count(). Especially with large collections of data.
The database adapters will try and build the most efficient query that will execute
on pretty much all modern databases. However, depending on your database or even your
own schema setup, there might be more efficient ways to get a rowcount. For this
scenario the database adapters allow you to set a custom COUNT query. For example,
if you keep track of the count of blog posts in a separate table, you could achieve a
faster count query with the following setup:
select()->from('posts'));
$adapter->setRowCount(
$db->select()
->from(
'item_counts',
array(
Zend_Paginator_Adapter_DbSelect::ROW_COUNT_COLUMN => 'post_count'
)
)
);
$paginator = new Zend_Paginator($adapter);
]]>
This approach will probably not give you a huge performance gain on
small collections and/or simple select queries. However, with complex
queries and large collections, a similar approach could give you a
significant performance boost.
Rendering pages with view scripts
The view script is used to render the page items (if you're using
Zend_Paginator to do so) and display the pagination
control.
Because Zend_Paginator implements the SPL
interface IteratorAggregate,
looping over your items and displaying them is simple.