/**
* Connects a new Route in the router.
*
* Routes are a way of connecting request urls to objects in your application. At their core routes
* are a set or regular expressions that are used to match requests to destinations.
*
* Examples:
*
* `Router::connect('/:controller/:action/*');`
*
* The first parameter will be used as a controller name while the second is used as the action name.
* the '/*' syntax makes this route greedy in that it will match requests like `/posts/index` as well as requests
* like `/posts/edit/1/foo/bar`.
*
* `Router::connect('/home-page', array('controller' => 'pages', 'action' => 'display', 'home'));`
*
* The above shows the use of route parameter defaults. And providing routing parameters for a static route.
*
* {{{
* Router::connect(
* '/:lang/:controller/:action/:id',
* array(),
* array('id' => '[0-9]+', 'lang' => '[a-z]{3}')
* );
* }}}
*
* Shows connecting a route with custom route parameters as well as providing patterns for those parameters.
* Patterns for routing parameters do not need capturing groups, as one will be added for each route params.
*
* @param string $route A string describing the template of the route
* @param array $defaults An array describing the default route parameters. These parameters will be used by default
* and can supply routing parameters that are not dynamic. See above.
* @param array $options An array matching the named elements in the route to regular expressions which that
* element should match. Also contains additional parameters such as which routed parameters should be
* shifted into the passed arguments. As well as supplying patterns for routing parameters.
* @see routes
* @return array Array of routes
* @access public
* @static
*/
public static function connect($route, $defaults = array(), $options = array())
{
foreach (self::$__prefixes as $prefix) {
if (isset($defaults[$prefix])) {
$defaults['prefix'] = $prefix;
break;
}
}
if (isset($defaults['prefix'])) {
self::$__prefixes[] = $defaults['prefix'];
self::$__prefixes = array_keys(array_flip(self::$__prefixes));
}
$defaults += array('action' => 'index', 'plugin' => null);
$routeClass = 'CakeRoute';
if (isset($options['routeClass'])) {
$routeClass = $options['routeClass'];
unset($options['routeClass']);
}
$Route = new $routeClass($route, $defaults, $options);
if ($routeClass !== 'CakeRoute' && !is_subclass_of($Route, 'CakeRoute')) {
trigger_error(__('Route classes must extend CakeRoute', true), E_USER_WARNING);
return false;
}
self::$routes[] = $Route;
return self::$routes;
}
