classes/kohana/pagination.php

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