doctrine2/manual/docs/en/utilities/pagination/working-with-pager.txt

Paginating queries is as simple as effectively do the queries itself. {{Doctrine_Pager}} is the responsible to process queries and paginate them. Check out this small piece of code:

<code type="php">
// Defining initial variables
$currentPage = 1;
$resultsPerPage = 50;

// Creating pager object
$pager = new Doctrine_Pager(
    Doctrine_Query::create()
        ->from( 'User u' )
        ->leftJoin( 'u.Group g' )
        ->orderby( 'u.username ASC' ),
    $currentPage, // Current page of request
    $resultsPerPage // (Optional) Number of results per page. Default is 25
);
</code>

Until this place, the source you have is the same as the old {{Doctrine_Query}} object. The only difference is that now you have 2 new arguments. Your old query object plus these 2 arguments are now encapsulated by the {{Doctrine_Pager}} object.
At this stage, {{Doctrine_Pager}} defines the basic data needed to control pagination. If you want to know that actual status of the pager, all you have to do is to check if it's already executed:

<code type="php">
$pager->getExecuted();
</code>

If you try to access any of the methods provided by Doctrine_Pager now, you'll experience {{Doctrine_Pager_Exception}} thrown, reporting you that Pager was not yet executed. When executed, {{Doctrine_Pager}} offer you powerful methods to retrieve information. The API usage is listed at the end of this topic.

To run the query, the process is similar to the current existent {{Doctrine_Query}} execute call. It even allow arguments the way you usually do it. Here is the PHP complete syntax, including the syntax of optional parameters:

<code type="php">
$pager->execute([$args = array() [, $fetchType = Doctrine::FETCH_RECORD]]);
</code>

There are some special cases where the return records query differ of the counter query. To allow this situation, {{Doctrine_Pager}} has some methods that enable you to count and then to execute. The first thing you have to do is to define the count query:

<code type="php">
$pager->setCountQuery($query [, $params = null]);

// ...

$rs = $pager->execute();
</code>

The first param of {{setCountQuery}} can be either a valid {{Doctrine_Query}} object or a DQL string. The second argument you can define the optional parameters that may be sent in the counter query. If you do not define the params now, you're still able to define it later by calling the {{setCountQueryParams}}:

<code type="php">
$pager->setCountQueryParams([$params = array() [, $append = false]]);
</code>

This method accepts 2 parameters. The first one is the params to be sent in count query and the second parameter is if the {{$params}} should be appended to the list or if it should override the list of count query parameters. The default behavior is to override the list.
One last thing to mention about count query is, if you do not define any parameter for count query, it will still send the parameters you define in {{$pager->execute()}} call.

Count query is always enabled to be accessed. If you do not define it and call {{$pager->getCountQuery()}}, it will return the "fetcher" query to you.

If you need access the other functionalities that {{Doctrine_Pager}} provides, you can access them through the API:

<code type="php">
// Returns the check if Pager was already executed
$pager->getExecuted();

// Return the total number of itens found on query search
$pager->getNumResults();

// Return the first page (always 1)
$pager->getFirstPage();

// Return the total number of pages
$pager->getLastPage();

// Return the current page
$pager->getPage();

// Defines a new current page (need to call execute again to adjust offsets and values)
$pager->setPage($page);

// Return the next page
$pager->getNextPage();

// Return the previous page
$pager->getPreviousPage();

// Return true if it's necessary to paginate or false if not
$pager->haveToPaginate();

// Return the maximum number of records per page
$pager->getMaxPerPage();

// Defined a new maximum number of records per page (need to call execute again to adjust offset and values)
$pager->setMaxPerPage($maxPerPage);

// Returns the number of itens in current page
$pager->getResultsInPage();

// Returns the Doctrine_Query object that is used to make the count results to pager
$pager->getCountQuery();

// Defines the counter query to be used by pager
$pager->setCountQuery($query, $params = null);

// Returns the params to be used by counter Doctrine_Query (return $defaultParams if no param is defined)
$pager->getCountQueryParams($defaultParams = array());

// Defines the params to be used by counter Doctrine_Query
$pager->setCountQueryParams($params = array(), $append = false);

// Return the Doctrine_Query object
$pager->getQuery();
</code>