lib/pear/DB/Pager.php

   1 <?php
   2 //
   3 //  Pear DB Pager - Retrieve and return information of databases
   4 //                  result sets
   5 //
   6 //  Copyright (C) 2001  Tomas Von Veschler Cox <cox@idecnet.com>
   7 //
   8 //  This library is free software; you can redistribute it and/or
   9 //  modify it under the terms of the GNU Lesser General Public
  10 //  License as published by the Free Software Foundation; either
  11 //  version 2.1 of the License, or (at your option) any later version.
  12 //
  13 //  This library is distributed in the hope that it will be useful,
  14 //  but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 //  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16 //  Lesser General Public License for more details.
  17 //
  18 //  You should have received a copy of the GNU Lesser General Public
  19 //  License along with this library; if not, write to the Free Software
  20 //  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  21 //
  22 //
  23 // $Id$
  24 ///
  25 // Based on DB_Pager 0.7 from the pear.php.net repository.
  26 // The only modifications made have been modification of the include paths.
  27 //
  28 // rcs_id('$Id$');
  29 // rcs_id('From Pear CVS: Id: Pager.php,v 1.3 2002/05/12 13:59:40 cox Exp');
  30
  31 require_once 'PEAR.php';
  32 require_once 'DB.php';
  33
  34 /**
  35 * This class handles all the stuff needed for displaying paginated results
  36 * from a database query of Pear DB, in a very easy way.
  37 * Documentation and examples of use, can be found in:
  38 * http://vulcanonet.com/soft/pager/ (could be outdated)
  39 *
  40 * IMPORTANT!
  41 * Since PEAR DB already support native row limit (more fast and avaible in
  42 * all the drivers), there is no more need to use $pager->build() or
  43 * the $pager->fetch*() methods.
  44 *
  45 * Usage example:
  46 *
  47 *< ?php
  48 * require_once 'DB/Pager.php';
  49 * $db = DB::connect('your DSN string');
  50 * $from = 0;   // The row to start to fetch from (you might want to get this
  51 *              // param from the $_GET array
  52 * $limit = 10; // The number of results per page
  53 * $maxpages = 10; // The number of pages for displaying in the pager (optional)
  54 * $res = $db->limitQuery($sql, $from, $limit);
  55 * $nrows = 0; // Alternative you could use $res->numRows()
  56 * while ($row = $res->fetchrow()) {
  57 *    // XXX code for building the page here
  58 *     $nrows++;
  59 * }
  60 * $data = DB_Pager::getData($from, $limit, $nrows, $maxpages);
  61 * // XXX code for building the pager here
  62 * ? >
  63 *
  64 * @version 0.7
  65 * @author Tomas V.V.Cox <cox@idecnet.com>
  66 * @see http://vulcanonet.com/soft/pager/
  67 */
  68
  69 class DB_Pager extends PEAR
  70 {
  71
  72     /**
  73     * Constructor
  74     *
  75     * @param object $res  A DB_result object from Pear_DB
  76     * @param int    $from  The row to start fetching
  77     * @param int    $limit  How many results per page
  78     * @param int    $numrows Pager will automatically
  79     *    find this param if is not given. If your Pear_DB backend extension
  80     *    doesn't support numrows(), you can manually calculate it
  81     *    and supply later to the constructor
  82     * @deprecated
  83     */
  84     function DB_Pager (&$res, $from, $limit, $numrows = null)
  85     {
  86         $this->res = $res;
  87         $this->from = $from;
  88         $this->limit = $limit;
  89         $this->numrows = $numrows;
  90     }
  91
  92     /**
  93     * Calculates all the data needed by Pager to work
  94     *
  95     * @return mixed An assoc array with all the data (see getData)
  96     *    or DB_Error on error
  97     * @see DB_Pager::getData
  98     * @deprecated
  99     */
 100     function build()
 101     {
 102         // if there is no numrows given, calculate it
 103         if ($this->numrows === null) {
 104             $this->numrows = $this->res->numrows();
 105             if (DB::isError($this->numrows)) {
 106                 return $this->numrows;
 107             }
 108         }
 109         $data = $this->getData($this->from, $this->limit, $this->numrows);
 110         if (DB::isError($data)) {
 111             return $data;
 112         }
 113         $this->current = $this->from - 1;
 114         $this->top = $data['to'];
 115         return $data;
 116     }
 117
 118     /**
 119     * @deprecated
 120     */
 121     function fetchRow($mode=DB_FETCHMODE_DEFAULT)
 122     {
 123         $this->current++;
 124         if ($this->current >= $this->top) {
 125             return null;
 126         }
 127         return $this->res->fetchRow($mode, $this->current);
 128     }
 129
 130     /**
 131     * @deprecated
 132     */
 133     function fetchInto(&$arr, $mode=DB_FETCHMODE_DEFAULT)
 134     {
 135         $this->current++;
 136         if ($this->current >= $this->top) {
 137             return null;
 138         }
 139         return $this->res->fetchInto($arr, $mode, $this->current);
 140     }
 141
 142     /*
 143     * Gets all the data needed to paginate results
 144     * This is an associative array with the following
 145     * values filled in:
 146     *
 147     * array(
 148     *    'current' => X,    // current page you are
 149     *    'numrows' => X,    // total number of results
 150     *    'next'    => X,    // row number where next page starts
 151     *    'prev'    => X,    // row number where prev page starts
 152     *    'remain'  => X,    // number of results remaning *in next page*
 153     *    'numpages'=> X,    // total number of pages
 154     *    'from'    => X,    // the row to start fetching
 155     *    'to'      => X,    // the row to stop fetching
 156     *    'limit'   => X,    // how many results per page
 157     *    'maxpages'   => X, // how many pages to show (google style)
 158     *    'firstpage'  => X, // the row number of the first page
 159     *    'lastpage'   => X, // the row number where the last page starts
 160     *    'pages'   => array(    // assoc with page "number => start row"
 161     *                1 => X,
 162     *                2 => X,
 163     *                3 => X
 164     *                )
 165     *    );
 166     * @param int $from    The row to start fetching
 167     * @param int $limit   How many results per page
 168     * @param int $numrows Number of results from query
 169     *
 170     * @return array associative array with data or DB_error on error
 171     *
 172     */
 173     function &getData($from, $limit, $numrows, $maxpages = false)
 174     {
 175         if (empty($numrows) || ($numrows < 0)) {
 176             return null;
 177         }
 178         $from = (empty($from)) ? 0 : $from;
 179
 180         if ($limit <= 0) {
 181             return PEAR::raiseError (null, 'wrong "limit" param', null,
 182                                      null, null, 'DB_Error', true);
 183         }
 184
 185         // Total number of pages
 186         $pages = ceil($numrows/$limit);
 187         $data['numpages'] = $pages;
 188
 189         // first & last page
 190         $data['firstpage'] = 1;
 191         $data['lastpage']  = $pages;
 192
 193         // Build pages array
 194         $data['pages'] = array();
 195         for ($i=1; $i <= $pages; $i++) {
 196             $offset = $limit * ($i-1);
 197             $data['pages'][$i] = $offset;
 198             // $from must point to one page
 199             if ($from == $offset) {
 200                 // The current page we are
 201                 $data['current'] = $i;
 202             }
 203         }
 204         if (!isset($data['current'])) {
 205             return PEAR::raiseError (null, 'wrong "from" param', null,
 206                                      null, null, 'DB_Error', true);
 207         }
 208
 209         // Limit number of pages (goole algoritm)
 210         if ($maxpages) {
 211             $radio = floor($maxpages/2);
 212             $minpage = $data['current'] - $radio;
 213             if ($minpage < 1) {
 214                 $minpage = 1;
 215             }
 216             $maxpage = $data['current'] + $radio - 1;
 217             if ($maxpage > $data['numpages']) {
 218                 $maxpage = $data['numpages'];
 219             }
 220             foreach (range($minpage, $maxpage) as $page) {
 221                 $tmp[$page] = $data['pages'][$page];
 222             }
 223             $data['pages'] = $tmp;
 224             $data['maxpages'] = $maxpages;
 225         } else {
 226             $data['maxpages'] = null;
 227         }
 228
 229         // Prev link
 230         $prev = $from - $limit;
 231         $data['prev'] = ($prev >= 0) ? $prev : null;
 232
 233         // Next link
 234         $next = $from + $limit;
 235         $data['next'] = ($next < $numrows) ? $next : null;
 236
 237         // Results remaining in next page & Last row to fetch
 238         if ($data['current'] == $pages) {
 239             $data['remain'] = 0;
 240             $data['to'] = $numrows;
 241         } else {
 242             if ($data['current'] == ($pages - 1)) {
 243                 $data['remain'] = $numrows - ($limit*($pages-1));
 244             } else {
 245                 $data['remain'] = $limit;
 246             }
 247             $data['to'] = $data['current'] * $limit;
 248         }
 249         $data['numrows'] = $numrows;
 250         $data['from']    = $from + 1;
 251         $data['limit']   = $limit;
 252
 253         return $data;
 254     }
 255 }
 256 ?>