PHP Class lithium\net\http\Router

Using Route objects, these two operations can be handled in a reciprocally consistent way. For example, if you wanted the /login URL to be routed to myapp\controllers\SessionsController::add(), you could set up a route like the following in config/routes.php: {{{ use lithium\net\http\Router; Router::connect('/login', array('controller' => 'Sessions', 'action' => 'add')); -- or -- Router::connect('/login', 'Sessions::add'); }}} Not only would that correctly route all requests for /login to SessionsController::add(), but any time the framework generated a route with matching parameters, Router would return the correct short URL. While most framework components that work with URLs (and utilize routing) handle calling the Router directly (i.e. controllers doing redirects, or helpers generating links), if you have a scenario where you need to call the Router directly, you can use the match() method. This allows you to keep your application's URL structure nicely decoupled from the underlying software design. For more information on parsing and generating URLs, see the parse() and match() methods.
Inheritance: extends lithium\core\StaticObject
Exibir arquivo Open project: unionofrad/lithium Class Usage Examples

Protected Properties

Property Type Description
$_classes array Classes used by Router.
$_configurations array An array of loaded Route objects used to match Request objects against.
$_formatters array An array of named closures matching up to corresponding route parameter values. Used to format those values.
$_modifiers array Array of closures used to format route parameters when parsing URLs.
$_scope string If is set to true, the scope of the user's request will be used. saved
$_scopes Contain the configuration of scopes.
$_unicode Flag for generating Unicode-capable routes. Turn this off if you don't need it, or if you're using a broken OS distribution (i.e. CentOS).

Public Methods

Method Description
attach ( $name, $config = null, array $vars = [] ) Attach a scope to a mount point.
attached ( $name = null, array $vars = [] ) : mixed Returns an attached mount point configuration.
config ( array $config = [] ) : array Modify Router configuration settings and dependencies.
connect ( string | object $template, array | string $params = [], array | callable $options = [] ) : array Connects a new route and returns the current routes array. This method creates a new Route object and registers it with the Router. The order in which routes are connected matters, since the order of precedence is taken into account in parsing and matching operations.
formatters ( array $formatters = [] ) : array Used to get or set an array of named formatter closures, which are used to format route parameters when generating URLs. For example, for controller/action parameters to be dashed instead of underscored or camelBacked, you could do the following:
get ( integer $route = null, string | boolean $scope = null ) : object | array | null Returns one or multiple connected routes.
match ( array | string $url = [], Request $context = null, array $options = [] ) : string Attempts to match an array of route parameters (i.e. 'controller', 'action', etc.) against a connected Route object. For example, given the following route:
modifiers ( array $modifiers = [] ) : array Used to get or set an array of named formatter closures, which are used to format route parameters when parsing URLs. For example, the following would match a posts/index url to a PostsController::indexAction() method.
parse ( object $request ) : array Accepts an instance of lithium\action\Request (or a subclass) and matches it against each route, in the order that the routes are connected.
process ( Request $request ) : Request Wrapper method which takes a Request object, parses it through all attached Route objects, assigns the resulting parameters to the Request object, and returns it.
reset ( ) Resets the Router to its default state, unloading all routes.
scope ( string $name = null, Closure $closure = null ) : mixed Scope getter/setter.

Protected Methods

Method Description
_compileScope ( array $config ) : array Compiles the scope into regular expression patterns for matching against request URLs
_compileStack ( $stack )
_formatError ( $url )
_initScopes ( ) Initialize static::$_scopes with a lithium\core\Configuration instance.
_matchOptions ( string | array &$url, Request $context, array $options ) : array Initialize options for Router::match().
_parseController ( array $params )
_parseScope ( string $name, string $request ) : mixed Return the unscoped url to route.
_parseString ( string $path, boolean $context, array $options = [] ) : array Helper function for taking a path string and parsing it into a controller and action array.
_persist ( array $url, Request $context ) : array Copies persistent parameters (parameters in the request which have been designated to persist) to the current URL, unless the parameter has been explicitly disabled from persisting by setting the value in the URL to null, or by assigning some other value.
_prefix ( string $path, object $context = null, array $options = [] ) : string Returns the prefix (scheme + hostname) for a URL based on the passed $options and the $context.
_prepareParams ( array | string $url, Request $context, array $options ) : array | string Prepares URL parameters for matching. Detects and Passes through un-routed URL strings, leaving them untouched.

Method Details

_compileScope() protected static method

Compiles the scope into regular expression patterns for matching against request URLs
protected static _compileScope ( array $config ) : array
$config array Array of settings.
return array Returns the complied settings.

_compileStack() protected static method

protected static _compileStack ( $stack )

_formatError() protected static method

protected static _formatError ( $url )

_initScopes() protected static method

Initialize static::$_scopes with a lithium\core\Configuration instance.
protected static _initScopes ( )

_matchOptions() protected static method

Initialize options for Router::match().
protected static _matchOptions ( string | array &$url, Request $context, array $options ) : array
$url string | array Options to match to a URL. Optionally, this can be a string containing a manually generated URL.
$context lithium\action\Request
$options array Options for the generation of the matched URL.
return array The initialized options.

_parseController() protected static method

protected static _parseController ( array $params )
$params array

_parseScope() protected static method

Return the unscoped url to route.
protected static _parseScope ( string $name, string $request ) : mixed
$name string Scope name.
$request string A `lithium\action\Request` instance .
return mixed The url to route, or `false` if the request doesn't match the scope.

_parseString() protected static method

Helper function for taking a path string and parsing it into a controller and action array.
protected static _parseString ( string $path, boolean $context, array $options = [] ) : array
$path string Path string to parse i.e. `li3_bot.Logs::index` or `Posts::index`.
$context boolean
$options array
return array

_persist() protected static method

For example: embed:lithium\tests\cases\net\http\RouterTest::testParameterPersistence(1-10)
See also: lithium\action\Request::$persist
protected static _persist ( array $url, Request $context ) : array
$url array The parameters that define the URL to be matched.
$context lithium\action\Request A request object, which contains a `$persist` property, which is an array of keys to be persisted in URLs between requests.
return array Returns the modified URL array.

_prefix() protected static method

Returns the prefix (scheme + hostname) for a URL based on the passed $options and the $context.
protected static _prefix ( string $path, object $context = null, array $options = [] ) : string
$path string The URL to be prefixed.
$context object The request context.
$options array Options for generating the proper prefix. Currently accepted values are: `'absolute' => true|false`, `'host' => string` and `'scheme' => string`.
return string The prefixed URL, depending on the passed options.

_prepareParams() protected static method

Will not attempt to parse strings as shorthand parameters but instead interpret them as normal, non-routed URLs when they are prefixed with a known scheme.
protected static _prepareParams ( array | string $url, Request $context, array $options ) : array | string
$url array | string An array of parameters, shorthand parameter string or URL string.
$context lithium\action\Request
$options array
return array | string Depending on the type of $url either a string or an array.

attach() public static method

Example 1: Router::attach('app', array( 'absolute' => true, 'host' => 'localhost', 'scheme' => 'http://', 'prefix' => 'web/tests' )); Example 2: Router::attach('app', array( 'absolute' => true, 'host' => '{:subdomain:[a-z]+}.{:hostname}.{:tld}', 'scheme' => '{:scheme:https://}', 'prefix' => '' )); Attach the variables to populate for the app scope. Router::attach('app', null, array( 'subdomain' => 'www', 'hostname' => 'li3', 'tld' => 'me' ));
public static attach ( $name, $config = null, array $vars = [] )
$vars array

attached() public static method

Example: Router::attach('app', array( 'absolute' => true, 'host' => '{:subdomain:[a-z]+}.{:hostname}.{:tld}', 'scheme' => '{:scheme:https://}', 'prefix' => '' )); $result = Router::attached('app', array( 'subdomain' => 'app', 'hostname' => 'blog', 'tld' => 'co.uk' )); Will give the following array in $result: array( 'absolute' => true, 'host' => 'blog.mysite.co.uk', 'scheme' => 'http://', 'prefix' => '' ));
public static attached ( $name = null, array $vars = [] ) : mixed
$vars array
return mixed The settings array of the scope or an array of settings array if `$name === null`.

config() public static method

Modify Router configuration settings and dependencies.
public static config ( array $config = [] ) : array
$config array Optional array to override configuration. Acceptable keys are `'classes'` and `'unicode'`.
return array Returns the current configuration settings.

connect() public static method

A callable can be passed in place of $options. In this case the callable acts as a *route handler*. Route handlers should return an instance of lithium\net\http\Response and can be used to short-circuit the framework's lookup and invocation of controller actions: Router::connect('/photos/{:id:[0-9]+}.jpg', array(), function($request) { return new Response(array( 'headers' => array('Content-type' => 'image/jpeg'), 'body' => Photos::first($request->id)->bytes() )); });
See also: lithium\net\http\Route
See also: lithium\net\http\Route::$_handler
See also: lithium\net\http\Router::parse()
See also: lithium\net\http\Router::match()
See also: lithium\net\http\Router::_parseString()
See also: lithium\net\http\Response
public static connect ( string | object $template, array | string $params = [], array | callable $options = [] ) : array
$template string | object An empty string, a route string `/` or an instance of `lithium\net\http\Route`.
$params array | string An array describing the default or required elements of the route or alternatively a path string i.e. `Posts::index`.
$options array | callable Either an array of options (`'handler'`, `'formatters'`, `'modifiers'`, `'unicode'` as well as any options for `Route`) or a callable that will be used as a route handler.
return array Array of routes

formatters() public static method

use lithium\util\Inflector; Router::formatters(array( 'controller' => function($value) { return Inflector::slug($value); }, 'action' => function($value) { return Inflector::slug($value); } )); _Note_: Because formatters are copied to Route objects on an individual basis, make sure you append custom formatters _before_ connecting new routes.
public static formatters ( array $formatters = [] ) : array
$formatters array An array of named formatter closures to append to (or overwrite) the existing list.
return array Returns the formatters array.

get() public static method

A specific route can be retrived by providing its index. All connected routes inside all scopes may be retrieved by providing null instead of the route index. To retrieve all routes for the current scope only, pass true for the $scope parameter.
public static get ( integer $route = null, string | boolean $scope = null ) : object | array | null
$route integer Index of the route.
$scope string | boolean Name of the scope to get routes from. Uses default scope if `true`.
return object | array | null If $route is an integer, returns the route object at given index or if that fails returns `null`. If $route is `null` returns an array of routes or scopes with their respective routes depending on the value of $scope.

match() public static method

Router::connect('/login', array('controller' => 'users', 'action' => 'login')); This will match: $url = Router::match(array('controller' => 'users', 'action' => 'login')); returns /login For URLs templates with no insert parameters (i.e. elements like {:id} that are replaced with a value), all parameters must match exactly as they appear in the route parameters. Alternatively to using a full array, you can specify routes using a more compact syntax. The above example can be written as: $url = Router::match('Users::login'); // still returns /login You can combine this with more complicated routes; for example: Router::connect('/posts/{:id:\d+}', array('controller' => 'posts', 'action' => 'view')); This will match: $url = Router::match(array('controller' => 'posts', 'action' => 'view', 'id' => '1138')); returns /posts/1138 Again, you can specify the same URL with a more compact syntax, as in the following: $url = Router::match(array('Posts::view', 'id' => '1138')); again, returns /posts/1138 You can use either syntax anywhere an URL is accepted, i.e. when redirecting or creating links using the Html helper.
See also: lithium\action\Controller::redirect()
See also: lithium\template\helper\Html::link()
public static match ( array | string $url = [], Request $context = null, array $options = [] ) : string
$url array | string An array of parameters to match, or paremeters in their shorthand form (i.e. `'Posts::view'`). Also takes non-routed, manually generated URL strings.
$context lithium\action\Request This supplies the context for any persistent parameters, as well as the base URL for the application.
$options array Options for the generation of the matched URL. Currently accepted values are: - `'absolute'` _boolean_: Indicates whether or not the returned URL should be an absolute path (i.e. including scheme and host name). - `'host'` _string_: If `'absolute'` is `true`, sets the host name to be used, or overrides the one provided in `$context`. - `'scheme'` _string_: If `'absolute'` is `true`, sets the URL scheme to be used, or overrides the one provided in `$context`. - `'scope'` _string_: Optionnal scope name.
return string Returns a generated URL, based on the URL template of the matched route, and prefixed with the base URL of the application.

modifiers() public static method

use lithium\util\Inflector; Router::modifiers(array( 'controller' => function($value) { return Inflector::camelize($value); }, 'action' => function($value) { return Inflector::camelize($value) . 'Action'; } )); _Note_: Because modifiers are copied to Route objects on an individual basis, make sure you append your custom modifiers _before_ connecting new routes.
public static modifiers ( array $modifiers = [] ) : array
$modifiers array An array of named formatter closures to append to (or overwrite) the existing list.
return array Returns the formatters array.

parse() public static method

If a route match the request, lithium\net\http\Router::_scope will be updated according the scope membership of the route
See also: lithium\action\Request
See also: lithium\net\http\Router::connect()
public static parse ( object $request ) : array
$request object A request object containing URL and environment data.
return array Returns an array of parameters specifying how the given request should be routed. The keys returned depend on the `Route` object that was matched, but typically include `'controller'` and `'action'` keys.

process() public static method

Wrapper method which takes a Request object, parses it through all attached Route objects, assigns the resulting parameters to the Request object, and returns it.
public static process ( Request $request ) : Request
$request lithium\action\Request
return lithium\action\Request Returns a copy of the request with parameters applied.

reset() public static method

Resets the Router to its default state, unloading all routes.
public static reset ( )

scope() public static method

Special use case: If $closure is not null executing the closure inside the specified scope.
public static scope ( string $name = null, Closure $closure = null ) : mixed
$name string Name of the scope to use.
$closure Closure A closure to execute inside the scope.
return mixed Returns the previous scope if if `$name` is not null and `$closure` is null, returns the default used scope if `$name` is null, otherwise returns `null`.

Property Details

$_classes protected_oe static_oe property

Classes used by Router.
protected static array $_classes
return array

$_configurations protected_oe static_oe property

An array of loaded Route objects used to match Request objects against.
See also: lithium\net\http\Route
protected static array $_configurations
return array

$_formatters protected_oe static_oe property

An array of named closures matching up to corresponding route parameter values. Used to format those values.
See also: lithium\net\http\Router::formatters()
protected static array $_formatters
return array

$_modifiers protected_oe static_oe property

Array of closures used to format route parameters when parsing URLs.
See also: lithium\net\http\Router::modifiers()
protected static array $_modifiers
return array

$_scope protected_oe static_oe property

If is set to true, the scope of the user's request will be used. saved
See also: lithium\net\http\Router::scope()
protected static string $_scope
return string

$_scopes protected_oe static_oe property

Contain the configuration of scopes.
protected static $_scopes

$_unicode protected_oe static_oe property

Flag for generating Unicode-capable routes. Turn this off if you don't need it, or if you're using a broken OS distribution (i.e. CentOS).
protected static $_unicode