File Source for paginate_db

<?php
// *** Tangra (Application Framework and Tools for PHP)
// $Id$
//
/**
* Contains Paginate_DB_Data class
*
* @package tangra_lib
* @subpackage db
*/
/**
*
*/
require_once(TANGRA_MAIN_DIR.'db/db_connection.class.php');
/**
* Used to paginate db data
*
* This class is useful for working with DB data when you need pagination
*
* @package tangra_lib
* @subpackage db
* @see Grid
*/
class Paginate_DB_Data extends Tangra_Class {
/**
* If set to false some methods will throw exception if you try to fetch non existing page.
*
* @var boolean
* @access private
*/
private $forgiving;
/**
* Holds current page index
*
* @var unknown_type
* @access private
*/
private $current_page = 0;
/**
* Holds total number of rows
*
* @var unknown_type
* @access private
*/
private $total_rows;
/**
* Holds size of the page
*
* @var unknown_type
* @access private
*/
private $page_size;
/**
* Holds count of currently available pages
*
* @var unknown_type
* @access private
*/
private $total_pages;
/**
* SQL select statement for selecting data
*
* @var unknown_type
*/
private $sql_select;
/**
* SQL select statement for counting rows that match "where" clause
*
* @var unknown_type
*/
private $sql_count;
/**
* Constructor
*
* @param integer $page_size Page size. How many rows will each page have
* @param string $sql_select SQL statement that will be used to set actual data
* @param string $sql_count SQL statement that will be used to count rows matching the "where" clause. Note that returned value have to be aliased with "as total_rows", otherwise you will get an exception
* @param boolean $forgiving If set to false some methods will throw exception if you try to fetch non existing page. If true - fetch* methods will guess some safe value. Default is false
*/
function __construct($page_size, $sql_select, $sql_count, $forgiving = true) {
$this->set_page_size($page_size);
$this->set_sql_select($sql_select);
//sql_count must be as "select count(id) as total_rows from some_table where..."
$this->set_sql_count($sql_count);
$this->set_forgiving($forgiving);
}
/**
* Returns current page
*
* @return integer
*/
public function get_current_page() {
return $this->current_page;
}
/**
* Sets page size
*
* @param integer $page_size
*/
public function set_page_size($page_size) {
tangra_if_not_int_throw_e($page_size);
$this->page_size = $page_size;
}
/**
* Returns page size
*
* @return unknown
*/
public function get_page_size() {
return $this->page_size;
}
/**
* Sets SQL statement used to get actual data
*
* @param unknown_type $sql_select
*/
public function set_sql_select($sql_select) {
$this->sql_select = $sql_select;
}
/**
* Gets SQL statement used to get actual data
*
* @return string
*/
public function get_sql_select() {
return $this->sql_select;
}
/**
* Sets SQL statement that will be used to count rows matching the "where" clause. Note that returned value have to be aliased with "as total_rows", otherwise you will get an exception
*
* @param string $sql_count
*/
public function set_sql_count($sql_count) {
$this->sql_count = $sql_count;
}
/**
* Gets SQL statement that will be used to count rows matching the "where" clause
*
* @return string
*/
public function get_sql_count() {
return $this->sql_count;
}
/**
* Sets forgiving mode. If set to false some methods will throw exception if you try to fetch non existing page. If true - fetch* methods will guess some safe value. Default is false
*
* @param boolean $forgiving
*/
public function set_forgiving($forgiving) {
$this->forgiving = $forgiving ? true : false;
}
/**
* Gets forgiving mode
*
* @return unknown
* @see Paginate_DB_Data::set_forgiving
*/
public function get_forgiving() {
return $this->forgiving;
}
/**
* Check the forgivenes mode and throws exception if mode is false
*
* @param unknown_type $exception
* @access private
*/
protected function ask_for_forgivenes($exception) {
if (!$this->get_forgiving()) {
throw $exception;
}
}
/**
* Sets total rows.
*
* @param unknown_type $total_rows
*/
protected function set_total_rows($total_rows) {
$this->total_rows = $total_rows;
}
/**
* Returns total rows (current sql_count)
*
* @return integer
*/
public function get_total_rows() {
return $this->total_rows;
}
/**
* Sets total pages for current sql count
*
* @param integer $total_pages
*/
public function set_total_pages($total_pages) {
$this->total_pages = $total_pages;
}
/**
* Returns total pages
*
* @return integer
*/
public function get_total_pages() {
return $this->total_pages;
}
/**
* Executes $sql_count and recalculates total rows and total pages
*
* @param DB_Connection $dbc
*/
public function refresh(DB_Connection $dbc) {
$rez = $dbc->execute($this->get_sql_count());
$rez_obj = $rez->fetch_object();
$this->set_total_rows($rez_obj->TOTAL_ROWS);
if ($this->get_total_rows()) {
$this->set_total_pages($this->calculate_total_pages());
} else {
$this->set_total_pages(0);
}
}
/**
* Calculates start of current page
*
* @return integer
* @internal
*/
protected function calculate_start() {
return $this->get_current_page() * $this->get_page_size();
}
/**
* Calculates total pages
*
* @return unknown
* @internal
*/
protected function calculate_total_pages() {
return ceil($this->get_total_rows() / $this->get_page_size());
}
/**
* Gathers current page rows
*
* @param DB_Connection $dbc
* @return array Returned rows
* @internal
*/
protected function _fetch_current_page(DB_Connection $dbc) {
$start = $this->calculate_start();
$rez = $dbc->select_limit($this->get_sql_select(), $this->get_page_size(), $start);
$ret = array();
while(!$rez->is_eof()) {
$row = $rez->fetch_row();
array_push($ret, $row);
}
return $ret;
}
/**
* Gathers current page rows
*
* @param DB_Connection $dbc
* @return array Returned rows
*/
public function fetch_current_page(DB_Connection $dbc) {
$this->refresh($dbc);
return $this->_fetch_current_page($dbc);
}
/**
* Sets current page
*
* @param integer $current_page
* @internal
*/
protected function set_current_page($current_page) {
tangra_if_not_int_throw_e($current_page);
if ($this->is_valid_page($current_page)) {
$this->current_page = $current_page;
} else {
if ($this->get_forgiving()) {
//correcting invalid page
if ($current_page < 0) {
$this->current_page = 0;
} else {
$this->current_page = $this->get_total_pages() - 1;
}
} else {
$this->ask_for_forgivenes(new Tangra_Exception('No such page: '.$current_page));
}
}
}
/**
* checks if $page is valid page index, i.e. there is such page
*
* @param integer $page
* @return boolean
* @internal
*/
private function is_valid_page($page) {
$ret = false;
if ($page >= 0 && $page <= $this->get_total_pages()) {
$ret = true;
}
return $ret;
}
/**
* Fetches first page
*
* @param DB_Connection $dbc
* @return array
*/
public function fetch_first_page(DB_Connection $dbc) {
$this->refresh($dbc);
$this->set_current_page(0);
return $this->_fetch_current_page($dbc);
}
/**
* Fetches last page
*
* @param DB_Connection $dbc
* @return array
*/
public function fetch_last_page(DB_Connection $dbc) {
$this->refresh($dbc);
$this->set_current_page($this->get_total_pages() - 1);
return $this->_fetch_current_page($dbc);
}
/**
* Fetches next page
*
* @param DB_Connection $dbc
* @return array
*/
public function fetch_next_page(DB_Connection $dbc) {
$this->refresh($dbc);
$next_page = $this->get_current_page() + 1;
if (!($next_page <= $this->get_total_pages())) {
$next_page = $this->get_total_pages();
}
$this->set_current_page($next_page);
return $this->_fetch_current_page($dbc);
}
/**
* Fetches previous page
*
* @param DB_Connection $dbc
* @return array
*/
public function fetch_prev_page(DB_Connection $dbc) {
$this->refresh($dbc);
$prev_page = $this->get_current_page() - 1;
if (!($prev_page >= 0)) {
$this->ask_for_forgivenes(new Tangra_Exception('No such page: '.$current_page));
$prev_page = 0;
}
$this->set_current_page($prev_page);
return $this->_fetch_current_page($dbc);
}
/**
* Fetches page specified by $page
*
* @param integer $page Page number
* @param DB_Connection $dbc
* @return array
*/
public function fetch_page($page, DB_Connection $dbc) {
tangra_if_not_int_throw_e($page);
$this->refresh($dbc);
$this->set_current_page($page);
return $this->_fetch_current_page($dbc);
}
}

Source for file paginate_db_data.class.php