Source for file Common.php

<?php
/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
 
/**
 * Contains the Pager_Common class
 *
 * PHP versions 4 and 5
 *
 * LICENSE: Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 * IN NO EVENT SHALL THE FREEBSD PROJECT OR CONTRIBUTORS BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * @category   HTML
 * @package    Pager
 * @author     Lorenzo Alberton <l dot alberton at quipo dot it>
 * @author     Richard Heyes <richard@phpguru.org>
 * @copyright  2003-2006 Lorenzo Alberton, Richard Heyes
 * @license    http://www.debian.org/misc/bsd.license  BSD License (3 Clause)
 * @version    CVS: $Id: Common.php,v 1.60 2007/07/29 08:10:34 quipo Exp $
 * @link       http://pear.php.net/package/Pager
 */
 
/**
 * Two constants used to guess the path- and file-name of the page
 * when the user doesn't set any other value
 */
if (substr($_SERVER['PHP_SELF'], -1) == '/') {
    $http = !empty($_SERVER['HTTPS']) ? 'https://' : 'http://';
    define('CURRENT_FILENAME', '');
    define('CURRENT_PATHNAME', $http.$_SERVER['HTTP_HOST'].str_replace('\\', '/', $_SERVER['PHP_SELF']));
} else {
    define('CURRENT_FILENAME', preg_replace('/(.*)\?.*/', '\\1', basename($_SERVER['PHP_SELF'])));
    define('CURRENT_PATHNAME', str_replace('\\', '/', dirname($_SERVER['PHP_SELF'])));
}
/**
 * Error codes
 */
define('PAGER_OK',                         0);
define('ERROR_PAGER',                     -1);
define('ERROR_PAGER_INVALID',             -2);
define('ERROR_PAGER_INVALID_PLACEHOLDER', -3);
define('ERROR_PAGER_INVALID_USAGE',       -4);
define('ERROR_PAGER_NOT_IMPLEMENTED',     -5);
 
/**
 * Pager_Common - Common base class for [Sliding|Jumping] Window Pager
 * Extend this class to write a custom paging class
 *
 * @category   HTML
 * @package    Pager
 * @author     Lorenzo Alberton <l dot alberton at quipo dot it>
 * @author     Richard Heyes <richard@phpguru.org>
 * @copyright  2003-2005 Lorenzo Alberton, Richard Heyes
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 * @link       http://pear.php.net/package/Pager
 */
class Pager_Common
{
    // {{{ class vars
 
    /**
     * @var integer number of items
     * @access private
     */
    var $_totalItems;
 
    /**
     * @var integer number of items per page
     * @access private
     */
    var $_perPage     = 10;
 
    /**
     * @var integer number of page links for each window
     * @access private
     */
    var $_delta       = 10;
 
    /**
     * @var integer current page number
     * @access private
     */
    var $_currentPage = 1;
 
    /**
     * @var integer total pages number
     * @access private
     */
    var $_totalPages  = 1;
 
    /**
     * @var string CSS class for links
     * @access private
     */
    var $_linkClass   = '';
 
    /**
     * @var string wrapper for CSS class name
     * @access private
     */
    var $_classString = '';
 
    /**
     * @var string path name
     * @access private
     */
    var $_path        = CURRENT_PATHNAME;
 
    /**
     * @var string file name
     * @access private
     */
    var $_fileName    = CURRENT_FILENAME;
    
    /**
     * @var boolean If false, don't override the fileName option. Use at your own risk.
     * @access private
     */
    var $_fixFileName = true;
 
    /**
     * @var boolean you have to use FALSE with mod_rewrite
     * @access private
     */
    var $_append      = true;
 
    /**
     * @var string specifies which HTTP method to use
     * @access private
     */
    var $_httpMethod  = 'GET';
    
    /**
     * @var string specifies which HTML form to use
     * @access private
     */
    var $_formID  = '';
 
    /**
     * @var boolean whether or not to import submitted data
     * @access private
     */
    var $_importQuery = true;
 
    /**
     * @var string name of the querystring var for pageID
     * @access private
     */
    var $_urlVar      = 'pageID';
 
    /**
     * @var array data to pass through the link
     * @access private
     */
    var $_linkData    = array();
 
    /**
     * @var array additional URL vars
     * @access private
     */
    var $_extraVars   = array();
    
    /**
     * @var array URL vars to ignore
     * @access private
     */
    var $_excludeVars = array();
 
    /**
     * @var boolean TRUE => expanded mode (for Pager_Sliding)
     * @access private
     */
    var $_expanded    = true;
    
    /**
     * @var boolean TRUE => show accesskey attribute on <a> tags
     * @access private
     */
    var $_accesskey   = false;
 
    /**
     * @var string extra attributes for the <a> tag
     * @access private
     */
    var $_attributes  = '';
    
    /**
     * @var string onclick
     * @access private
     */
    var $_onclick = '';
 
    /**
     * @var string alt text for "first page" (use "%d" placeholder for page number)
     * @access private
     */
    var $_altFirst     = 'first page';
 
    /**
     * @var string alt text for "previous page"
     * @access private
     */
    var $_altPrev     = 'previous page';
 
    /**
     * @var string alt text for "next page"
     * @access private
     */
    var $_altNext     = 'next page';
 
    /**
     * @var string alt text for "last page" (use "%d" placeholder for page number)
     * @access private
     */
    var $_altLast     = 'last page';
 
    /**
     * @var string alt text for "page"
     * @access private
     */
    var $_altPage     = 'page';
 
    /**
     * @var string image/text to use as "prev" link
     * @access private
     */
    var $_prevImg     = '&lt;&lt; Back';
 
    /**
     * @var string image/text to use as "next" link
     * @access private
     */
    var $_nextImg     = 'Next &gt;&gt;';
 
    /**
     * @var string link separator
     * @access private
     */
    var $_separator   = '';
 
    /**
     * @var integer number of spaces before separator
     * @access private
     */
    var $_spacesBeforeSeparator = 0;
 
    /**
     * @var integer number of spaces after separator
     * @access private
     */
    var $_spacesAfterSeparator  = 1;
 
    /**
     * @var string CSS class name for current page link
     * @access private
     */
    var $_curPageLinkClassName  = '';
 
    /**
     * @var string Text before current page link
     * @access private
     */
    var $_curPageSpanPre        = '';
 
    /**
     * @var string Text after current page link
     * @access private
     */
    var $_curPageSpanPost       = '';
 
    /**
     * @var string Text before first page link
     * @access private
     */
    var $_firstPagePre  = '[';
 
    /**
     * @var string Text to be used for first page link
     * @access private
     */
    var $_firstPageText = '';
 
    /**
     * @var string Text after first page link
     * @access private
     */
    var $_firstPagePost = ']';
 
    /**
     * @var string Text before last page link
     * @access private
     */
    var $_lastPagePre   = '[';
 
    /**
     * @var string Text to be used for last page link
     * @access private
     */
    var $_lastPageText  = '';
 
    /**
     * @var string Text after last page link
     * @access private
     */
    var $_lastPagePost  = ']';
 
    /**
     * @var string Will contain the HTML code for the spaces
     * @access private
     */
    var $_spacesBefore  = '';
 
    /**
     * @var string Will contain the HTML code for the spaces
     * @access private
     */
    var $_spacesAfter   = '';
 
    /**
     * @var string $_firstLinkTitle 
     * @access private
     */
    var $_firstLinkTitle = 'first page';
 
    /**
     * @var string $_nextLinkTitle 
     * @access private
     */
    var $_nextLinkTitle = 'next page';
 
    /**
     * @var string $_prevLinkTitle 
     * @access private
     */
    var $_prevLinkTitle = 'previous page';
 
    /**
     * @var string $_lastLinkTitle 
     * @access private
     */
    var $_lastLinkTitle = 'last page';
 
    /**
     * @var string Text to be used for the 'show all' option in the select box
     * @access private
     */
    var $_showAllText   = '';
 
    /**
     * @var array data to be paged
     * @access private
     */
    var $_itemData      = null;
 
    /**
     * @var boolean If TRUE and there's only one page, links aren't shown
     * @access private
     */
    var $_clearIfVoid   = true;
 
    /**
     * @var boolean Use session for storing the number of items per page
     * @access private
     */
    var $_useSessions   = false;
 
    /**
     * @var boolean Close the session when finished reading/writing data
     * @access private
     */
    var $_closeSession  = false;
 
    /**
     * @var string name of the session var for number of items per page
     * @access private
     */
    var $_sessionVar    = 'setPerPage';
 
    /**
     * Pear error mode (when raiseError is called)
     * (see PEAR doc)
     *
     * @var int $_pearErrorMode 
     * @access private
     */
    var $_pearErrorMode = null;
 
    // }}}
    // {{{ public vars
 
    /**
     * @var string Complete set of links
     * @access public
     */
    var $links = '';
 
    /**
     * @var string Complete set of link tags
     * @access public
     */
    var $linkTags = '';
 
    /**
     * @var array Array with a key => value pair representing
     *             page# => bool value (true if key==currentPageNumber).
     *             can be used for extreme customization.
     * @access public
     */
    var $range = array();
    
    /**
     * @var array list of available options (safety check)
     * @access private
     */
    var $_allowed_options = array(
        'totalItems',
        'perPage',
        'delta',
        'linkClass',
        'path',
        'fileName',
        'fixFileName',
        'append',
        'httpMethod',
        'formID',
        'importQuery',
        'urlVar',
        'altFirst',
        'altPrev',
        'altNext',
        'altLast',
        'altPage',
        'prevImg',
        'nextImg',
        'expanded',
        'accesskey',
        'attributes',
        'onclick',
        'separator',
        'spacesBeforeSeparator',
        'spacesAfterSeparator',
        'curPageLinkClassName',
        'curPageSpanPre',
        'curPageSpanPost',
        'firstPagePre',
        'firstPageText',
        'firstPagePost',
        'lastPagePre',
        'lastPageText',
        'lastPagePost',
        'firstLinkTitle',
        'nextLinkTitle',
        'prevLinkTitle',
        'lastLinkTitle',
        'showAllText',
        'itemData',
        'clearIfVoid',
        'useSessions',
        'closeSession',
        'sessionVar',
        'pearErrorMode',
        'extraVars',
        'excludeVars',
        'currentPage',
    );
 
    // }}}
    // {{{ build()
 
    /**
     * Generate or refresh the links and paged data after a call to setOptions()
     *
     * @access public
     */
    function build()
    {
        //reset
        $this->_pageData = array();
        $this->links = '';
 
        $this->_generatePageData();
        $this->_setFirstLastText();
 
        if ($this->_totalPages > (2 * $this->_delta + 1)) {
            $this->links .= $this->_printFirstPage();
        }
 
        $this->links .= $this->_getBackLink();
        $this->links .= $this->_getPageLinks();
        $this->links .= $this->_getNextLink();
 
        $this->linkTags .= $this->_getFirstLinkTag();
        $this->linkTags .= $this->_getPrevLinkTag();
        $this->linkTags .= $this->_getNextLinkTag();
        $this->linkTags .= $this->_getLastLinkTag();
 
        if ($this->_totalPages > (2 * $this->_delta + 1)) {
            $this->links .= $this->_printLastPage();
        }
    }
 
    // }}}
    // {{{ getPageData()
 
    /**
     * Returns an array of current pages data
     *
     * @param $pageID Desired page ID (optional)
     * @return array Page data
     * @access public
     */
    function getPageData($pageID = null)
    {
        $pageID = empty($pageID) ? $this->_currentPage : $pageID;
 
        if (!isset($this->_pageData)) {
            $this->_generatePageData();
        }
        if (!empty($this->_pageData[$pageID])) {
            return $this->_pageData[$pageID];
        }
        return array();
    }
 
    // }}}
    // {{{ getPageIdByOffset()
 
    /**
     * Returns pageID for given offset
     *
     * @param $index Offset to get pageID for
     * @return int PageID for given offset
     */
    function getPageIdByOffset($index)
    {
        $msg = '<b>PEAR::Pager Error:</b>'
              .' function "getPageIdByOffset()" not implemented.';
        return $this->raiseError($msg, ERROR_PAGER_NOT_IMPLEMENTED);
    }
 
    // }}}
    // {{{ getOffsetByPageId()
 
    /**
     * Returns offsets for given pageID. Eg, if you
     * pass it pageID one and your perPage limit is 10
     * it will return (1, 10). PageID of 2 would
     * give you (11, 20).
     *
     * @param integer PageID to get offsets for
     * @return array  First and last offsets
     * @access public
     */
    function getOffsetByPageId($pageid = null)
    {
        $pageid = isset($pageid) ? $pageid : $this->_currentPage;
        if (!isset($this->_pageData)) {
            $this->_generatePageData();
        }
 
        if (isset($this->_pageData[$pageid]) || is_null($this->_itemData)) {
            return array(
                        max(($this->_perPage * ($pageid - 1)) + 1, 1),
                        min($this->_totalItems, $this->_perPage * $pageid)
                   );
        } else {
            return array(0, 0);
        }
    }
 
    // }}}
    // {{{ getPageRangeByPageId()
 
    /**
     * @param integer PageID to get offsets for
     * @return array  First and last offsets
     */
    function getPageRangeByPageId($pageID)
    {
        $msg = '<b>PEAR::Pager Error:</b>'
              .' function "getPageRangeByPageId()" not implemented.';
        return $this->raiseError($msg, ERROR_PAGER_NOT_IMPLEMENTED);
    }
 
    // }}}
    // {{{ getLinks()
 
    /**
     * Returns back/next/first/last and page links,
     * both as ordered and associative array.
     *
     * NB: in original PEAR::Pager this method accepted two parameters,
     * $back_html and $next_html. Now the only parameter accepted is
     * an integer ($pageID), since the html text for prev/next links can
     * be set in the factory. If a second parameter is provided, then
     * the method act as it previously did. This hack was done to mantain
     * backward compatibility only.
     *
     * @param integer $pageID Optional pageID. If specified, links
     *                 for that page are provided instead of current one.  [ADDED IN NEW PAGER VERSION]
     * @param  string $next_html HTML to put inside the next link [deprecated: use the factory instead]
     * @return array back/next/first/last and page links
     */
    function getLinks($pageID=null, $next_html='')
    {
        $msg = '<b>PEAR::Pager Error:</b>'
              .' function "getLinks()" not implemented.';
        return $this->raiseError($msg, ERROR_PAGER_NOT_IMPLEMENTED);
    }
 
    // }}}
    // {{{ getCurrentPageID()
 
    /**
     * Returns ID of current page
     *
     * @return integer ID of current page
     */
    function getCurrentPageID()
    {
        return $this->_currentPage;
    }
 
    // }}}
    // {{{ getNextPageID()
 
    /**
     * Returns next page ID. If current page is last page
     * this function returns FALSE
     *
     * @return mixed Next page ID
     */
    function getNextPageID()
    {
        return ($this->getCurrentPageID() == $this->numPages() ? false : $this->getCurrentPageID() + 1);
    }
 
    // }}}
    // {{{ getPreviousPageID()
 
    /**
     * Returns previous page ID. If current page is first page
     * this function returns FALSE
     *
     * @return mixed Previous pages' ID
     */
    function getPreviousPageID()
    {
        return $this->isFirstPage() ? false : $this->getCurrentPageID() - 1;
    }
 
    // }}}
    // {{{ numItems()
 
    /**
     * Returns number of items
     *
     * @return int Number of items
     */
    function numItems()
    {
        return $this->_totalItems;
    }
 
    // }}}
    // {{{ numPages()
 
    /**
     * Returns number of pages
     *
     * @return int Number of pages
     */
    function numPages()
    {
        return (int)$this->_totalPages;
    }
 
    // }}}
    // {{{ isFirstPage()
 
    /**
     * Returns whether current page is first page
     *
     * @return bool First page or not
     */
    function isFirstPage()
    {
        return ($this->_currentPage < 2);
    }
 
    // }}}
    // {{{ isLastPage()
 
    /**
     * Returns whether current page is last page
     *
     * @return bool Last page or not
     */
    function isLastPage()
    {
        return ($this->_currentPage == $this->_totalPages);
    }
 
    // }}}
    // {{{ isLastPageComplete()
 
    /**
     * Returns whether last page is complete
     *
     * @return bool Last age complete or not
     */
    function isLastPageComplete()
    {
        return !($this->_totalItems % $this->_perPage);
    }
 
    // }}}
    // {{{ _generatePageData()
 
    /**
     * Calculates all page data
     * @access private
     */
    function _generatePageData()
    {
        // Been supplied an array of data?