Modules

Route
extends Kohana_Route

Routes are used to determine the controller and action for a requested URI. Every route generates a regular expression which is used to match a URI and a route. Routes may also contain keys which can be used to set the controller, action, and parameters.

Each will be translated to a regular expression using a default regular expression pattern. You can override the default pattern by providing a pattern for the key:

// This route will only match when <id> is a digit
Route::set('user', 'user/<action>/<id>', array('id' => '\d+'));

// This route will match when <path> is anything
Route::set('file', '<path>', array('path' => '.*'));

It is also possible to create optional segments by using parentheses in the URI definition:

// This is the standard default route, and no keys are required
Route::set('default', '(<controller>(/<action>(/<id>)))');

// This route only requires the <file> key
Route::set('file', '(<path>/)<file>(.<format>)', array('path' => '.*', 'format' => '\w+'));

Routes also provide a way to generate URIs (called "reverse routing"), which makes them an extremely powerful and flexible way to generate internal links.

package: Kohana
category: Base
author: Kohana Team
copyright: © 2008-2010 Kohana Team
license: http://kohanaframework.org/license

Class declared in SYSPATH/classes/route.php on line 3.

Constants

REGEX_KEY

string(18) "<([a-zA-Z0-9_]++)>"

REGEX_SEGMENT

string(12) "[^/.,;?\n]++"

REGEX_ESCAPE

string(17) "[.\+*?[^\]${}=!|]"

Properties

public static string $default_action

default action for all routes

string(5) "index"

protected $_defaults

protected $_regex

protected $_route_regex

protected static array $_routes

list of route objects

array(5) (
    "codebench" => object Route(4) {
        protected _uri => string(19) "codebench(/<class>)"
        protected _regex => array(0) 
        protected _defaults => array(3) (
            "controller" => string(9) "codebench"
            "action" => string(5) "index"
            "class" => NULL
        )
        protected _route_regex => string(44) "#^codebench(?:/(?P<class>[^/.,;?\n]++))?$#uD"
    }
    "docs/media" => object Route(4) {
        protected _uri => string(20) "guide/media(/<file>)"
        protected _regex => array(1) (
            "file" => string(2) ".+"
        )
        protected _defaults => array(3) (
            "controller" => string(9) "userguide"
            "action" => string(5) "media"
            "file" => NULL
        )
        protected _route_regex => string(35) "#^guide/media(?:/(?P<file>.+))?$#uD"
    }
    "docs/api" => object Route(4) {
        protected _uri => string(19) "guide/api(/<class>)"
        protected _regex => array(1) (
            "class" => string(13) "[a-zA-Z0-9_]+"
        )
        protected _defaults => array(3) (
            "controller" => string(9) "userguide"
            "action" => string(3) "api"
            "class" => NULL
        )
        protected _route_regex => string(45) "#^guide/api(?:/(?P<class>[a-zA-Z0-9_]+))?$#uD"
    }
    "docs/guide" => object Route(4) {
        protected _uri => string(25) "guide(/<module>(/<page>))"
        protected _regex => array(1) (
            "page" => string(2) ".+"
        )
        protected _defaults => array(3) (
            "controller" => string(9) "userguide"
            "action" => string(4) "docs"
            "module" => string(0) ""
        )
        protected _route_regex => string(59) "#^guide(?:/(?P<module>[^/.,;?\n]++)(?:/(?P<page>.+))?)?$#uD"
    }
    "default" => object Route(4) {
        protected _uri => string(32) "(<controller>(/<action>(/<id>)))"
        protected _regex => array(0) 
        protected _defaults => array(2) (
            "controller" => string(7) "welcome"
            "action" => string(5) "index"
        )
        protected _route_regex => string(95) "#^(?:(?P<controller>[^/.,;?\n]++)(?:/(?P<action>[^/.,;?\n]++)(?:/(?P<id>[^/.,;?\n]++))?)?)?$#uD"
    }
)

protected $_uri

Methods

public __construct( [ string $uri = NULL , array $regex = NULL ] ) (defined in Kohana_Route)

Creates a new route. Sets the URI and regular expressions for keys. Routes should always be created with Route::set or they will not be properly stored.

$route = new Route($uri, $regex);

Parameters

string $uri = NULL - Route URI pattern
array $regex = NULL - Key patterns

Return Values

void

Source Code

public function __construct($uri = NULL, array $regex = NULL)
{
	if ($uri === NULL)
	{
		// Assume the route is from cache
		return;
	}

	if ( ! empty($regex))
	{
		$this->_regex = $regex;
	}

	// Store the URI that this route will match
	$this->_uri = $uri;

	// Store the compiled regex locally
	$this->_route_regex = $this->_compile();
}

public static all( ) (defined in Kohana_Route)

Retrieves all named routes.

$routes = Route::all();

Return Values

array - Routes by name

Source Code

public static function all()
{
	return Route::$_routes;
}

public static cache( [ boolean $save = bool FALSE ] ) (defined in Kohana_Route)

Saves or loads the route cache. If your routes will remain the same for a long period of time, use this to reload the routes from the cache rather than redefining them on every page load.

if ( ! Route::cache())
{
    // Set routes here
    Route::cache(TRUE);
}

Parameters

boolean $save = bool FALSE - Cache the current routes

Return Values

void - When saving routes
boolean - When loading routes

Source Code

public static function cache($save = FALSE)
{
	if ($save === TRUE)
	{
		// Cache all defined routes
		Kohana::cache('Route::cache()', Route::$_routes);
	}
	else
	{
		if ($routes = Kohana::cache('Route::cache()'))
		{
			Route::$_routes = $routes;

			// Routes were cached
			return TRUE;
		}
		else
		{
			// Routes were not cached
			return FALSE;
		}
	}
}

public defaults( [ array $defaults = NULL ] ) (defined in Kohana_Route)

Provides default values for keys when they are not present. The default action will always be "index" unless it is overloaded here.

$route->defaults(array(
    'controller' => 'welcome',
    'action'     => 'index'
));

Parameters

array $defaults = NULL - Key values

Return Values

$this

Source Code

public function defaults(array $defaults = NULL)
{
	$this->_defaults = $defaults;

	return $this;
}

public static get( string $name ) (defined in Kohana_Route)

Retrieves a named route.

$route = Route::get('default');

Parameters

string $name required - Route name

Return Values

Route

Source Code

public static function get($name)
{
	if ( ! isset(Route::$_routes[$name]))
	{
		throw new Kohana_Exception('The requested route does not exist: :route',
			array(':route' => $name));
	}

	return Route::$_routes[$name];
}

public matches( string $uri ) (defined in Kohana_Route)

Tests if the route matches a given URI. A successful match will return all of the routed parameters as an array. A failed match will return boolean FALSE.

// Params: controller = users, action = edit, id = 10
$params = $route->matches('users/edit/10');

This method should almost always be used within an if/else block:

if ($params = $route->matches($uri))
{
    // Parse the parameters
}

Parameters

string $uri required - URI to match

Return Values

array - On success
FALSE - On failure

Source Code

public function matches($uri)
{
	if ( ! preg_match($this->_route_regex, $uri, $matches))
		return FALSE;

	$params = array();
	foreach ($matches as $key => $value)
	{
		if (is_int($key))
		{
			// Skip all unnamed keys
			continue;
		}

		// Set the value for all matched keys
		$params[$key] = $value;
	}

	foreach ($this->_defaults as $key => $value)
	{
		if ( ! isset($params[$key]) OR $params[$key] === '')
		{
			// Set default values for any key that was not matched
			$params[$key] = $value;
		}
	}

	return $params;
}

public static name( object $route ) (defined in Kohana_Route)

Get the name of a route.

$name = Route::name($route)

Parameters

object $route required - Route instance

Return Values

string

Source Code

public static function name(Route $route)
{
	return array_search($route, Route::$_routes);
}

public static set( string $name , string $uri [, array $regex = NULL ] ) (defined in Kohana_Route)

Stores a named route and returns it. The "action" will always be set to "index" if it is not defined.

Route::set('default', '(<controller>(/<action>(/<id>)))')
    ->defaults(array(
        'controller' => 'welcome',
    ));

Parameters

string $name required - Route name
string $uri required - URI pattern
array $regex = NULL - Regex patterns for route keys

Return Values

Route

Source Code

public static function set($name, $uri, array $regex = NULL)
{
	return Route::$_routes[$name] = new Route($uri, $regex);
}

public uri( [ array $params = NULL ] ) (defined in Kohana_Route)

Generates a URI for the current route based on the parameters given.

// Using the "default" route: "users/profile/10"
$route->uri(array(
    'controller' => 'users',
    'action'     => 'profile',
    'id'         => '10'
));

Parameters

array $params = NULL - URI parameters

Return Values

string

Source Code

public function uri(array $params = NULL)
{
	if ($params === NULL)
	{
		// Use the default parameters
		$params = $this->_defaults;
	}
	else
	{
		// Add the default parameters
		$params += $this->_defaults;
	}

	// Start with the routed URI
	$uri = $this->_uri;

	if (strpos($uri, '<') === FALSE AND strpos($uri, '(') === FALSE)
	{
		// This is a static route, no need to replace anything
		return $uri;
	}

	while (preg_match('#\([^()]++\)#', $uri, $match))
	{
		// Search for the matched value
		$search = $match[0];

		// Remove the parenthesis from the match as the replace
		$replace = substr($match[0], 1, -1);

		while (preg_match('#'.Route::REGEX_KEY.'#', $replace, $match))
		{
			list($key, $param) = $match;

			if (isset($params[$param]))
			{
				// Replace the key with the parameter value
				$replace = str_replace($key, $params[$param], $replace);
			}
			else
			{
				// This group has missing parameters
				$replace = '';
				break;
			}
		}

		// Replace the group in the URI
		$uri = str_replace($search, $replace, $uri);
	}

	while (preg_match('#'.Route::REGEX_KEY.'#', $uri, $match))
	{
		list($key, $param) = $match;

		if ( ! isset($params[$param]))
		{
			// Ungrouped parameters are required
			throw new Kohana_Exception('Required route parameter not passed: :param',
				array(':param' => $param));
		}

		$uri = str_replace($key, $params[$param], $uri);
	}

	// Trim all extra slashes from the URI
	$uri = preg_replace('#//+#', '/', rtrim($uri, '/'));

	return $uri;
}

public static url( string $name [, array $params = NULL , mixed $protocol = NULL ] ) (defined in Kohana_Route)

Create a URL from a route name. This is a shortcut for:

echo URL::site(Route::get($name)->uri($params), $protocol);

Parameters

string $name required - Route name
array $params = NULL - URI parameters
mixed $protocol = NULL - Protocol string or boolean, adds protocol and domain

Return Values

string

Source Code

public static function url($name, array $params = NULL, $protocol = NULL)
{
	// Create a URI with the route and convert it to a URL
	return URL::site(Route::get($name)->uri($params), $protocol);
}

protected _compile( ) (defined in Kohana_Route)

Returns the compiled regular expression for the route. This translates keys and optional groups to a proper PCRE regular expression.

$regex = $route->_compile();

Return Values

string

Source Code

protected function _compile()
{
	// The URI should be considered literal except for keys and optional parts
	// Escape everything preg_quote would escape except for : ( ) < >
	$regex = preg_replace('#'.Route::REGEX_ESCAPE.'#', '\\\\$0', $this->_uri);

	if (strpos($regex, '(') !== FALSE)
	{
		// Make optional parts of the URI non-capturing and optional
		$regex = str_replace(array('(', ')'), array('(?:', ')?'), $regex);
	}

	// Insert default regex for keys
	$regex = str_replace(array('<', '>'), array('(?P<', '>'.Route::REGEX_SEGMENT.')'), $regex);

	if ( ! empty($this->_regex))
	{
		$search = $replace = array();
		foreach ($this->_regex as $key => $value)
		{
			$search[]  = "<$key>".Route::REGEX_SEGMENT;
			$replace[] = "<$key>$value";
		}

		// Replace the default regex with the user-specified regex
		$regex = str_replace($search, $replace, $regex);
	}

	return '#^'.$regex.'$#uD';
}

Modules

Route extends Kohana_Route

Constants

Properties

Methods

Constants

REGEX_KEY

REGEX_SEGMENT

REGEX_ESCAPE

Properties

public static string $default_action

protected $_defaults

protected $_regex

protected $_route_regex

protected static array $_routes

protected $_uri

Methods

public __construct( [ string $uri = NULL , array $regex = NULL ] ) (defined in Kohana_Route)

Parameters

Tags

Return Values

Source Code

public static all( ) (defined in Kohana_Route)

Return Values

Source Code

public static cache( [ boolean $save = bool FALSE ] ) (defined in Kohana_Route)

Parameters

Tags

Return Values

Source Code

public defaults( [ array $defaults = NULL ] ) (defined in Kohana_Route)

Parameters

Return Values

Source Code

public static get( string $name ) (defined in Kohana_Route)

Parameters

Tags

Return Values

Source Code

public matches( string $uri ) (defined in Kohana_Route)

Parameters

Return Values

Source Code

public static name( object $route ) (defined in Kohana_Route)

Parameters

Return Values

Source Code

public static set( string $name , string $uri [, array $regex = NULL ] ) (defined in Kohana_Route)

Parameters

Return Values

Source Code

public uri( [ array $params = NULL ] ) (defined in Kohana_Route)

Parameters

Tags

Return Values

Source Code

public static url( string $name [, array $params = NULL , mixed $protocol = NULL ] ) (defined in Kohana_Route)

Parameters

Tags

Return Values

Source Code

protected _compile( ) (defined in Kohana_Route)

Tags

Return Values

Source Code

Route
extends Kohana_Route

public static `string` $default_action

protected static `array` $_routes