Из руководства Doctrine 1.1 вольный перевод. Пейджинг (начало).

Пейджинг.

Введение.

В реальных web-приложениях, отображать содержимое таблиц базы данных является одной из самых распространенных задач. Кроме того, представьте себе, что это содержание результатов поиска, содержащее тысячи позиций. К сожалению, возможно это будет огромный список, значительное потребление памяти и может вызвать дискомфорт у пользователя. Именно в таких ситуация нам и необходим постраничный вывод (pagination, pager, пейджер).

В ORM Doctrine присутствует очень гибкая реализация пейджинга, которая позволяет Вам не только организовать постраничных вывод данных, но и контролировать расположение виджета пейджера на web-странице. В этой главе мы узнаем, как создавать объекты пейджера, стили управления постраничным выводом и в конце, обзор объекта шаблона постраничного вывода (pager layout object) — мощного средства ORM Doctrine для отображения ссылок на страницы с вашими данными.

Работа с пейджером.

Постраничные запросы так же просты как и обычные. За постраничный вывод отвечает объект Doctrine_Pager. Это иллюстрирует пример кода ниже:

// 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
);

Здесь у вас есть источник в виде объекта класса Doctrine_Query. Единственным отличием является то, что теперь у вас есть 2 новых аргумента. Ваш старый объект запроса к базе данных плюс эти 2 аргумента передаются в коструктор объекта Doctrine_Pager. На данном этапе, Doctrine_Pager определяет основные данные, необходимые для контроля нумерации данных для вывода. Если вы хотите знать, что на самом деле делает пейджер, для начала надо проверить был ли он выполнен:

$pager->getExecuted();

Если вы пытаетесь получить доступ к любым из методов, предусмотренных по Doctrine_Pager сейчас, вы получите исключение Doctrine_Pager_Exception сообщающее вам, что пейджер еще не был выполнен. После выполнении Doctrine_Pager предлагаем Вам эффективные методы для получения информации. Использование API, перечислены в конце этой темы.

Метод выполнения Doctrine_Pager очень похож на подобный метод класса Doctrine_Query. Он также позволяет передавать аргументы, как вы обычно это делаете. Ниже приведен синтаксис PHP, включая синтаксис передачи дополнительных параметров:

$items = $pager->execute([$args = array() [, $fetchType = null]]);

foreach ($items as $item) {
// ...
}

Существуют некоторые особые случаи, когда запрос возващающий записи отличается от запроса подсчета. Чтобы разрешить эту ситуацию, Doctrine_Pager имеет некоторые методы, которые позволяют рассчитать, а затем выполнить. Первое, что вам нужно сделать, это определить запрос-счетчик:

$pager->setCountQuery($query [, $params = null]);

// ...

$rs = $pager->execute();

Первый параметр в setCountQuery может быть действительным объектом Doctrine_Query или строкой DQL. Вторым аргументом можно указать дополнительные параметры, которые могут быть отправлены в запросе-счетчике. Если вы не определите параметры сразу, то сможете определить в любой момент , вызвав setCountQueryParams:

$pager->setCountQueryParams([$params = array() [, $append = false]]);

Этот метод принимает 2 параметра. Первый параметр будут направлены в запрос-счетчик, а второй параметр, если $params должен быть добавлен к списку, или если он должен переопределить список параметров, количество запросов. Поведение по умолчанию - переопределить список. И последнее, что касается запроса-счетчика, если вы не определяете никаких параметров для него, то будут отправлены параметры, которые определяются в вызове $pager->execute ().

Запрос-счетчик всегда доступен. Если вы не определили его и вызывали $pager-> getCountQuery (), будет возвращен "fetcher" query.

Если вам нужно получить доступ к другой функции, которые Doctrine_Pager предоставляет, вы можете получить к ним доступ через API:

// 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 the first indice of current page
$pager->getFirstIndice();

// Return the last indice of current page
$pager->getLastIndice();

// Return true if it's necessary to paginate or false if not
// возвращает true если надо делать постраничный вывод
$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
// возвращает объект Doctrine_Query, который используется для запроса подсчета результатов для пейджера
$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();

// Return an associated Doctrine_Pager_Range_* instance
$pager->getRange($rangeStyle, $options = array());