[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3  * @version        $Id:router.php 8876 2007-09-13 22:54:03Z jinx $
   4  * @package        Joomla.Framework
   5  * @subpackage    Application
   6  * @copyright    Copyright (C) 2005 - 2010 Open Source Matters. All rights reserved.
   7  * @license        GNU/GPL, see LICENSE.php
   8  * Joomla! is free software. This version may have been modified pursuant
   9  * to the GNU General Public License, and as distributed it includes or
  10  * is derivative of works licensed under the GNU General Public License or
  11  * other free or open source software licenses.
  12  * See COPYRIGHT.php for copyright notices and details.
  13  */
  14  
  15  // Check to ensure this file is within the rest of the framework
  16  defined('JPATH_BASE') or die();
  17  
  18  /**
  19   * Set the available masks for the routing mode
  20   */
  21  define('JROUTER_MODE_RAW', 0);
  22  define('JROUTER_MODE_SEF', 1);
  23  
  24  /**
  25   * Class to create and parse routes
  26   *
  27   * @abstract
  28   * @package     Joomla.Framework
  29   * @subpackage    Application
  30   * @since        1.5
  31   */
  32  class JRouter extends JObject
  33  {
  34      /**
  35       * The rewrite mode
  36       *
  37       * @access protected
  38       * @var integer
  39       */
  40      var $_mode = null;
  41  
  42      /**
  43       * An array of variables
  44       *
  45       * @access protected
  46       * @var array
  47       */
  48      var $_vars = array();
  49  
  50      /**
  51       * An array of rules
  52       *
  53       * @access protected
  54       * @var array
  55       */
  56      var $_rules = array(
  57          'build' => array(),
  58          'parse' => array()
  59      );
  60  
  61      /**
  62       * Class constructor
  63       *
  64       * @access public
  65       */
  66  	function __construct($options = array())
  67      {
  68          if(array_key_exists('mode', $options)) {
  69              $this->_mode = $options['mode'];
  70          } else {
  71              $this->_mode = JROUTER_MODE_RAW;
  72          }
  73      }
  74  
  75      /**
  76       * Returns a reference to the global JRouter object, only creating it if it
  77       * doesn't already exist.
  78       *
  79       * This method must be invoked as:
  80       *         <pre>  $menu = &JRouter::getInstance();</pre>
  81       *
  82       * @access    public
  83       * @param string  $client  The name of the client
  84       * @param array   $options An associative array of options
  85       * @return    JRouter    A router object.
  86       */
  87      function &getInstance($client, $options = array())
  88      {
  89          static $instances;
  90  
  91          if (!isset( $instances )) {
  92              $instances = array();
  93          }
  94  
  95          if (empty($instances[$client]))
  96          {
  97              //Load the router object
  98              $info =& JApplicationHelper::getClientInfo($client, true);
  99  
 100              $path = $info->path.DS.'includes'.DS.'router.php';
 101              if(file_exists($path))
 102              {
 103                  require_once $path;
 104  
 105                  // Create a JRouter object
 106                  $classname = 'JRouter'.ucfirst($client);
 107                  $instance = new $classname($options);
 108              }
 109              else
 110              {
 111                  $error = JError::raiseError( 500, 'Unable to load router: '.$client);
 112                  return $error;
 113              }
 114  
 115              $instances[$client] = & $instance;
 116          }
 117  
 118          return $instances[$client];
 119      }
 120  
 121      /**
 122       *  Function to convert a route to an internal URI
 123       *
 124       * @access public
 125       */
 126  	function parse(&$uri)
 127      {
 128          $vars = array();
 129  
 130          // Process the parsed variables based on custom defined rules
 131          $vars = $this->_processParseRules($uri);
 132  
 133          // Parse RAW URL
 134          if($this->_mode == JROUTER_MODE_RAW) {
 135              $vars += $this->_parseRawRoute($uri);
 136          }
 137  
 138          // Parse SEF URL
 139          if($this->_mode == JROUTER_MODE_SEF) {
 140              $vars += $vars + $this->_parseSefRoute($uri);
 141          }
 142  
 143           return  array_merge($this->getVars(), $vars);
 144      }
 145  
 146      /**
 147       * Function to convert an internal URI to a route
 148       *
 149       * @param    string    $string    The internal URL
 150       * @return    string    The absolute search engine friendly URL
 151       */
 152      function &build($url)
 153      {
 154          //Create the URI object
 155          $uri =& $this->_createURI($url);
 156  
 157          //Process the uri information based on custom defined rules
 158          $this->_processBuildRules($uri);
 159  
 160          // Build RAW URL
 161          if($this->_mode == JROUTER_MODE_RAW) {
 162              $this->_buildRawRoute($uri);
 163          }
 164  
 165          // Build SEF URL : mysite/route/index.php?var=x
 166          if ($this->_mode == JROUTER_MODE_SEF) {
 167              $this->_buildSefRoute($uri);
 168          }
 169  
 170          return $uri;
 171      }
 172  
 173      /**
 174       * Get the router mode
 175       *
 176       * @access public
 177       */
 178  	function getMode() {
 179          return $this->_mode;
 180      }
 181  
 182      /**
 183       * Get the router mode
 184       *
 185       * @access public
 186       */
 187  	function setMode($mode) {
 188          $this->_mode = $mode;
 189      }
 190  
 191      /**
 192       * Set a router variable, creating it if it doesn't exist
 193       *
 194       * @access    public
 195       * @param    string  $key    The name of the variable
 196       * @param    mixed   $value  The value of the variable
 197       * @param    boolean $create If True, the variable will be created if it doesn't exist yet
 198        */
 199  	function setVar($key, $value, $create = true) {
 200  
 201          if(!$create && array_key_exists($key, $this->_vars)) {
 202              $this->_vars[$key] = $value;
 203          } else {
 204              $this->_vars[$key] = $value;
 205          }
 206      }
 207  
 208      /**
 209       * Set the router variable array
 210       *
 211       * @access    public
 212       * @param    array   $vars   An associative array with variables
 213       * @param    boolean $create If True, the array will be merged instead of overwritten
 214        */
 215  	function setVars($vars = array(), $merge = true) {
 216  
 217          if($merge) {
 218              $this->_vars = array_merge($this->_vars, $vars);
 219          } else {
 220              $this->_vars = $vars;
 221          }
 222      }
 223  
 224      /**
 225       * Get a router variable
 226       *
 227       * @access    public
 228       * @param    string $key   The name of the variable
 229       * $return  mixed  Value of the variable
 230        */
 231  	function getVar($key)
 232      {
 233          $result = null;
 234          if(isset($this->_vars[$key])) {
 235              $result = $this->_vars[$key];
 236          }
 237          return $result;
 238      }
 239  
 240      /**
 241       * Get the router variable array
 242       *
 243       * @access    public
 244       * @return  array An associative array of router variables
 245        */
 246  	function getVars() {
 247          return $this->_vars;
 248      }
 249  
 250      /**
 251       * Attach a build rule
 252       *
 253       * @access    public
 254       * @param   callback $callback The function to be called.
 255        */
 256  	function attachBuildRule($callback)
 257      {
 258          $this->_rules['build'][] = $callback;
 259      }
 260  
 261      /**
 262       * Attach a parse rule
 263       *
 264       * @access    public
 265       * @param   callback $callback The function to be called.
 266        */
 267  	function attachParseRule($callback)
 268      {
 269          $this->_rules['parse'][] = $callback;
 270      }
 271  
 272      /**
 273       * Function to convert a raw route to an internal URI
 274       *
 275       * @abstract
 276       * @access protected
 277       */
 278  	function _parseRawRoute(&$uri)
 279      {
 280          return false;
 281      }
 282  
 283      /**
 284       *  Function to convert a sef route to an internal URI
 285       *
 286       * @abstract
 287       * @access protected
 288       */
 289  	function _parseSefRoute(&$uri)
 290      {
 291          return false;
 292      }
 293  
 294      /**
 295       * Function to build a raw route
 296       *
 297       * @abstract
 298       * @access protected
 299       */
 300  	function _buildRawRoute(&$uri)
 301      {
 302  
 303      }
 304  
 305      /**
 306       * Function to build a sef route
 307       *
 308       * @abstract
 309       * @access protected
 310       */
 311  	function _buildSefRoute(&$uri)
 312      {
 313  
 314      }
 315  
 316      /**
 317       * Process the parsed router variables based on custom defined rules
 318       *
 319       * @abstract
 320       * @access protected
 321       */
 322  	function _processParseRules(&$uri)
 323      {
 324          $vars = array();
 325  
 326          foreach($this->_rules['parse'] as $rule) {
 327              $vars = call_user_func_array($rule, array(&$this, &$uri));
 328          }
 329  
 330          return $vars;
 331      }
 332  
 333      /**
 334       * Process the build uri query data based on custom defined rules
 335       *
 336       * @abstract
 337       * @access protected
 338       */
 339  	function _processBuildRules(&$uri)
 340      {
 341          foreach($this->_rules['build'] as $rule) {
 342              call_user_func_array($rule, array(&$this, &$uri));
 343          }
 344      }
 345  
 346      /**
 347       * Create a uri based on a full or partial url string
 348       *
 349       * @access    protected
 350       * @return  JURI  A JURI object
 351        */
 352      function &_createURI($url)
 353      {
 354          // Create full URL if we are only appending variables to it
 355          if(substr($url, 0, 1) == '&')
 356          {
 357              $vars = array();
 358              if(strpos($url, '&amp;') !== false)
 359              {
 360                 $url = str_replace('&amp;','&',$url);
 361              }
 362  
 363              parse_str($url, $vars);
 364  
 365              $vars = array_merge($this->getVars(), $vars);
 366  
 367              foreach($vars as $key => $var)
 368              {
 369                  if($var == "") {
 370                      unset($vars[$key]);
 371                  }
 372              }
 373  
 374              $url = 'index.php?'.JURI::buildQuery($vars);
 375          }
 376  
 377          // Decompose link into url component parts
 378          $uri = new JURI($url);
 379  
 380          return $uri;
 381      }
 382  
 383      /**
 384       * Encode route segments
 385       *
 386       * @access    protected
 387       * @param   array     An array of route segments
 388       * @return  array
 389        */
 390  	function _encodeSegments($segments)
 391      {
 392          $total = count($segments);
 393          for($i=0; $i<$total; $i++) {
 394              $segments[$i] = str_replace(':', '-', $segments[$i]);
 395          }
 396  
 397          return $segments;
 398      }
 399  
 400      /**
 401       * Decode route segments
 402       *
 403       * @access    protected
 404       * @param   array     An array of route segments
 405       * @return  array
 406        */
 407  	function _decodeSegments($segments)
 408      {
 409          $total = count($segments);
 410          for($i=0; $i<$total; $i++)  {
 411              $segments[$i] = preg_replace('/-/', ':', $segments[$i], 1);
 412          }
 413  
 414          return $segments;
 415      }
 416  }