Support Joomla!

Joomla! 1.5 Documentation

Packages

Package: Joomla-Framework

License

Content on this site is copyright © 2005 - 2008 by the individual contributors and can be used in accordance with the Creative Commons License, Attribution- NonCommercial- ShareAlike 2.5. Some parts of this website may be subject to other licenses.
Source code for file /joomla/application/router.php

Documentation is available at router.php

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