classes/kohana/pagination.php

   1 <?php defined('SYSPATH') or die('No direct script access.');
   2 /**
   3  * Pagination links generator.
   4  *
   5  * @package    Kohana/Pagination
   6  * @category   Base
   7  * @author     Kohana Team
   8  * @copyright  (c) 2008-2009 Kohana Team
   9  * @license    http://kohanaphp.com/license.html
  10  */
  11 class Kohana_Pagination {
  12
  13         // Merged configuration settings
  14         protected $config = array(
  15                 'current_page'      => array('source' => 'query_string', 'key' => 'page'),
  16                 'total_items'       => 0,
  17                 'items_per_page'    => 10,
  18                 'view'              => 'pagination/basic',
  19                 'auto_hide'         => TRUE,
  20                 'first_page_in_url' => FALSE,
  21         );
  22
  23         // Current page number
  24         protected $current_page;
  25
  26         // Total item count
  27         protected $total_items;
  28
  29         // How many items to show per page
  30         protected $items_per_page;
  31
  32         // Total page count
  33         protected $total_pages;
  34
  35         // Item offset for the first item displayed on the current page
  36         protected $current_first_item;
  37
  38         // Item offset for the last item displayed on the current page
  39         protected $current_last_item;
  40
  41         // Previous page number; FALSE if the current page is the first one
  42         protected $previous_page;
  43
  44         // Next page number; FALSE if the current page is the last one
  45         protected $next_page;
  46
  47         // First page number; FALSE if the current page is the first one
  48         protected $first_page;
  49
  50         // Last page number; FALSE if the current page is the last one
  51         protected $last_page;
  52
  53         // Query offset
  54         protected $offset;
  55
  56         /**
  57          * Creates a new Pagination object.
  58          *
  59          * @param   array  configuration
  60          * @return  Pagination
  61          */
  62         public static function factory(array $config = array())
  63         {
  64                 return new Pagination($config);
  65         }
  66
  67         /**
  68          * Creates a new Pagination object.
  69          *
  70          * @param   array  configuration
  71          * @return  void
  72          */
  73         public function __construct(array $config = array())
  74         {
  75                 // Overwrite system defaults with application defaults
  76                 $this->config = $this->config_group() + $this->config;
  77
  78                 // Pagination setup
  79                 $this->setup($config);
  80         }
  81
  82         /**
  83          * Retrieves a pagination config group from the config file. One config group can
  84          * refer to another as its parent, which will be recursively loaded.
  85          *
  86          * @param   string  pagination config group; "default" if none given
  87          * @return  array   config settings
  88          */
  89         public function config_group($group = 'default')
  90         {
  91                 // Load the pagination config file
  92                 $config_file = Kohana::config('pagination');
  93
  94                 // Initialize the $config array
  95                 $config['group'] = (string) $group;
  96
  97                 // Recursively load requested config groups
  98                 while (isset($config['group']) AND isset($config_file->$config['group']))
  99                 {
 100                         // Temporarily store config group name
 101                         $group = $config['group'];
 102                         unset($config['group']);
 103
 104                         // Add config group values, not overwriting existing keys
 105                         $config += $config_file->$group;
 106                 }
 107
 108                 // Get rid of possible stray config group names
 109                 unset($config['group']);
 110
 111                 // Return the merged config group settings
 112                 return $config;
 113         }
 114
 115         /**
 116          * Loads configuration settings into the object and (re)calculates pagination if needed.
 117          * Allows you to update config settings after a Pagination object has been constructed.
 118          *
 119          * @param   array   configuration
 120          * @return  object  Pagination
 121          */
 122         public function setup(array $config = array())
 123         {
 124                 if (isset($config['group']))
 125                 {
 126                         // Recursively load requested config groups
 127                         $config += $this->config_group($config['group']);
 128                 }
 129
 130                 // Overwrite the current config settings
 131                 $this->config = $config + $this->config;
 132
 133                 // Only (re)calculate pagination when needed
 134                 if ($this->current_page === NULL
 135                         OR isset($config['current_page'])
 136                         OR isset($config['total_items'])
 137                         OR isset($config['items_per_page']))
 138                 {
 139                         // Retrieve the current page number
 140                         if ( ! empty($this->config['current_page']['page']))
 141                         {
 142                                 // The current page number has been set manually
 143                                 $this->current_page = (int) $this->config['current_page']['page'];
 144                         }
 145                         else
 146                         {
 147                                 switch ($this->config['current_page']['source'])
 148                                 {
 149                                         case 'query_string':
 150                                                 $this->current_page = isset($_GET[$this->config['current_page']['key']])
 151                                                         ? (int) $_GET[$this->config['current_page']['key']]
 152                                                         : 1;
 153                                                 break;
 154
 155                                         case 'route':
 156                                                 $this->current_page = (int) Request::current()->param($this->config['current_page']['key'], 1);
 157                                                 break;
 158                                 }
 159                         }
 160
 161                         // Calculate and clean all pagination variables
 162                         $this->total_items        = (int) max(0, $this->config['total_items']);
 163                         $this->items_per_page     = (int) max(1, $this->config['items_per_page']);
 164                         $this->total_pages        = (int) ceil($this->total_items / $this->items_per_page);
 165                         $this->current_page       = (int) min(max(1, $this->current_page), max(1, $this->total_pages));
 166                         $this->current_first_item = (int) min((($this->current_page - 1) * $this->items_per_page) + 1, $this->total_items);
 167                         $this->current_last_item  = (int) min($this->current_first_item + $this->items_per_page - 1, $this->total_items);
 168                         $this->previous_page      = ($this->current_page > 1) ? $this->current_page - 1 : FALSE;
 169                         $this->next_page          = ($this->current_page < $this->total_pages) ? $this->current_page + 1 : FALSE;
 170                         $this->first_page         = ($this->current_page === 1) ? FALSE : 1;
 171                         $this->last_page          = ($this->current_page >= $this->total_pages) ? FALSE : $this->total_pages;
 172                         $this->offset             = (int) (($this->current_page - 1) * $this->items_per_page);
 173                 }
 174
 175                 // Chainable method
 176                 return $this;
 177         }
 178
 179         /**
 180          * Generates the full URL for a certain page.
 181          *
 182          * @param   integer  page number
 183          * @return  string   page URL
 184          */
 185         public function url($page = 1)
 186         {
 187                 // Clean the page number
 188                 $page = max(1, (int) $page);
 189
 190                 // No page number in URLs to first page
 191                 if ($page === 1 AND ! $this->config['first_page_in_url'])
 192                 {
 193                         $page = NULL;
 194                 }
 195
 196                 switch ($this->config['current_page']['source'])
 197                 {
 198                         case 'query_string':
 199                                 return URL::site(Request::current()->uri).URL::query(array($this->config['current_page']['key'] => $page));
 200
 201                         case 'route':
 202                                 return URL::site(Request::current()->uri(array($this->config['current_page']['key'] => $page))).URL::query();
 203                 }
 204
 205                 return '#';
 206         }
 207
 208         /**
 209          * Checks whether the given page number exists.
 210          *
 211          * @param   integer  page number
 212          * @return  boolean
 213          * @since   3.0.7
 214          */
 215         public function valid_page($page)
 216         {
 217                 // Page number has to be a clean integer
 218                 if ( ! Validate::digit($page))
 219                         return FALSE;
 220
 221                 return $page > 0 AND $page <= $this->total_pages;
 222         }
 223
 224         /**
 225          * Renders the pagination links.
 226          *
 227          * @param   mixed   string of the view to use, or a Kohana_View object
 228          * @return  string  pagination output (HTML)
 229          */
 230         public function render($view = NULL)
 231         {
 232                 // Automatically hide pagination whenever it is superfluous
 233                 if ($this->config['auto_hide'] === TRUE AND $this->total_pages <= 1)
 234                         return '';
 235
 236                 if ($view === NULL)
 237                 {
 238                         // Use the view from config
 239                         $view = $this->config['view'];
 240                 }
 241
 242                 if ( ! $view instanceof Kohana_View)
 243                 {
 244                         // Load the view file
 245                         $view = View::factory($view);
 246                 }
 247
 248                 // Pass on the whole Pagination object
 249                 return $view->set(get_object_vars($this))->set('page', $this)->render();
 250         }
 251
 252         /**
 253          * Renders the pagination links.
 254          *
 255          * @return  string  pagination output (HTML)
 256          */
 257         public function __toString()
 258         {
 259                 return $this->render();
 260         }
 261
 262         /**
 263          * Returns a Pagination property.
 264          *
 265          * @param   string  URI of the request
 266          * @return  mixed   Pagination property; NULL if not found
 267          */
 268         public function __get($key)
 269         {
 270                 return isset($this->$key) ? $this->$key : NULL;
 271         }
 272
 273         /**
 274          * Updates a single config setting, and recalculates pagination if needed.
 275          *
 276          * @param   string  config key
 277          * @param   mixed   config value
 278          * @return  void
 279          */
 280         public function __set($key, $value)
 281         {
 282                 $this->setup(array($key => $value));
 283         }
 284
 285 } // End Pagination