/libraries/joomla/application/web/router.php

  1<?php
  2/**
  3 * @package     Joomla.Platform
  4 * @subpackage  Application
  5 *
  6 * @copyright   Copyright (C) 2005 - 2012 Open Source Matters, Inc. All rights reserved.
  7 * @license     GNU General Public License version 2 or later; see LICENSE
  8 */
  9
 10defined('JPATH_PLATFORM') or die;
 11
 12/**
 13 * Class to define an abstract Web application router.
 14 *
 15 * @package     Joomla.Platform
 16 * @subpackage  Application
 17 * @since       12.2
 18 */
 19abstract class JApplicationWebRouter
 20{
 21	/**
 22	 * @var    JApplicationWeb  The web application on whose behalf we are routing the request.
 23	 * @since  12.2
 24	 */
 25	protected $app;
 26
 27	/**
 28	 * @var    string  The default page controller name for an empty route.
 29	 * @since  12.2
 30	 */
 31	protected $default;
 32
 33	/**
 34	 * @var    string  Controller class name prefix for creating controller objects by name.
 35	 * @since  12.2
 36	 */
 37	protected $controllerPrefix;
 38
 39	/**
 40	 * @var    JInput  An input object from which to derive the route.
 41	 * @since  12.2
 42	 */
 43	protected $input;
 44
 45	/**
 46	 * Constructor.
 47	 *
 48	 * @param   JApplicationWeb  $app    The web application on whose behalf we are routing the request.
 49	 * @param   JInput           $input  An optional input object from which to derive the route.  If none
 50	 *                                   is given than the input from the application object will be used.
 51	 *
 52	 * @since   12.2
 53	 */
 54	public function __construct(JApplicationWeb $app, JInput $input = null)
 55	{
 56		$this->app   = $app;
 57		$this->input = ($input === null) ? $this->app->input : $input;
 58	}
 59
 60	/**
 61	 * Find and execute the appropriate controller based on a given route.
 62	 *
 63	 * @param   string  $route  The route string for which to find and execute a controller.
 64	 *
 65	 * @return  void
 66	 *
 67	 * @since   12.2
 68	 * @throws  InvalidArgumentException
 69	 * @throws  RuntimeException
 70	 */
 71	public function execute($route)
 72	{
 73		// Get the controller name based on the route patterns and requested route.
 74		$name = $this->parseRoute($route);
 75
 76		// Get the controller object by name.
 77		$controller = $this->fetchController($name);
 78
 79		// Execute the controller.
 80		$controller->execute();
 81	}
 82
 83	/**
 84	 * Set the controller name prefix.
 85	 *
 86	 * @param   string  $prefix  Controller class name prefix for creating controller objects by name.
 87	 *
 88	 * @return  JApplicationWebRouter  This object for method chaining.
 89	 *
 90	 * @since   12.2
 91	 */
 92	public function setControllerPrefix($prefix)
 93	{
 94		$this->controllerPrefix	= (string) $prefix;
 95
 96		return $this;
 97	}
 98
 99	/**
100	 * Set the default controller name.
101	 *
102	 * @param   string  $name  The default page controller name for an empty route.
103	 *
104	 * @return  JApplicationWebRouter  This object for method chaining.
105	 *
106	 * @since   12.2
107	 */
108	public function setDefaultController($name)
109	{
110		$this->default = (string) $name;
111
112		return $this;
113	}
114
115	/**
116	 * Parse the given route and return the name of a controller mapped to the given route.
117	 *
118	 * @param   string  $route  The route string for which to find and execute a controller.
119	 *
120	 * @return  string  The controller name for the given route excluding prefix.
121	 *
122	 * @since   12.2
123	 * @throws  InvalidArgumentException
124	 */
125	abstract protected function parseRoute($route);
126
127	/**
128	 * Get a JController object for a given name.
129	 *
130	 * @param   string  $name  The controller name (excluding prefix) for which to fetch and instance.
131	 *
132	 * @return  JController
133	 *
134	 * @since   12.2
135	 * @throws  RuntimeException
136	 */
137	protected function fetchController($name)
138	{
139		// Derive the controller class name.
140		$class = $this->controllerPrefix . ucfirst($name);
141
142		// If the controller class does not exist panic.
143		if (!class_exists($class) || !is_subclass_of($class, 'JController'))
144		{
145			throw new RuntimeException(sprintf('Unable to locate controller `%s`.', $class), 404);
146		}
147
148		// Instantiate the controller.
149		$controller = new $class($this->input, $this->app);
150
151		return $controller;
152	}
153}