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