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}} already sent a dummy query to database to collect useful information to allow you to access them before even execute the real query. Let's say for example you want to know how many matches were found:

<code type="php">
echo 'Total of items found: ' . $pager->getNumResults();
</code>

There are a couple of other interesting information that can be retrieved from pager before you execute the query. 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>

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

<code type="php">
// 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 (automatically 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 (automatically adjust offset and values)
$pager->setMaxPerPage($maxPerPage);

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