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