Merge pull request #3800 from markstory/3.0-scoped-routes

3.0 scoped routes

src/Routing/Route/Route.php

@@ -150,7 +150,7 @@ public function compiled() {
  * @return array Returns a string regular expression of the compiled route.
  */
 	public function compile() {
-		if ($this->compiled()) {
+		if (!empty($this->compiledRoute)) {
 			return $this->_compiledRoute;
 		}
 		$this->_writeRoute();
@@ -259,7 +259,7 @@ public function getName() {
 	public function parse($url) {
 		$request = Router::getRequest(true) ?: Request::createFromGlobals();
 
-		if (!$this->compiled()) {
+		if (empty($this->_compiledRoute)) {
 			$this->compile();
 		}
 		list($url, $ext) = $this->_parseExtension($url);
@@ -399,7 +399,7 @@ protected function _parseArgs($args, $context) {
  * @return mixed Either a string url for the parameters if they match or false.
  */
 	public function match(array $url, array $context = []) {
-		if (!$this->compiled()) {
+		if (empty($this->_compiledRoute)) {
 			$this->compile();
 		}
 		$defaults = $this->defaults;

src/Routing/Router.php

@@ -19,6 +19,7 @@
 use Cake\Error;
 use Cake\Network\Request;
 use Cake\Routing\RouteCollection;
+use Cake\Routing\ScopedRouteCollection;
 use Cake\Routing\Route\Route;
 use Cake\Utility\Inflector;
 
@@ -116,6 +117,13 @@ class Router {
  */
 	const UUID = '[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{12}';
 
+/**
+ * A hash of ScopedRouteCollection objects indexed by path.
+ *
+ * @var array
+ */
+	protected static $_pathScopes = [];
+
 /**
  * Named expressions
  *
@@ -1035,6 +1043,62 @@ public static function parseNamedParams(Request $request, $options = []) {
 		return $request;
 	}
 
+/**
+ * Create a routing scope.
+ *
+ * Routing scopes allow you to keep your routes DRY and avoid repeating
+ * common path prefixes, and or parameter sets.
+ *
+ * Scoped collections will be indexed by path for faster route parsing. If you
+ * re-open or re-use a scope the connected routes will be merged with the
+ * existing ones.
+ *
+ * ### Example
+ *
+ * {{{
+ * Router::scope('/blog', ['plugin' => 'Blog'], function($routes) {
+ *    $routes->connect('/', ['controller' => 'Articles']);
+ * });
+ * }}}
+ *
+ * The above would result in a `/blog/` route being created, with both the
+ * plugin & controller default parameters set.
+ *
+ * You can use Router::plugin() and Router::prefix() as shortcuts to creating
+ * specific kinds of scopes.
+ *
+ * Routing scopes will inherit the globally set extensions configured with
+ * Router::parseExtensions(). You can also set valid extensions using 
+ * `$routes->extensions()` in your closure.
+ *
+ * @param string $path The path prefix for the scope. This path will be prepended
+ *    to all routes connected in the scoped collection.
+ * @param array $params An array of routing defaults to add to each connected route.
+ *   If you have no parameters, this argument can be a callable.
+ * @param callable $callback The callback to invoke with the scoped collection.
+ * @throws \InvalidArgumentException When an invalid callable is provided.
+ * @return void
+ */
+	public static function scope($path, $params = [], $callback = null) {
+		if ($callback === null) {
+			$callback = $params;
+			$params = [];
+		}
+		if (!is_callable($callback)) {
+			$msg = 'Need a callable function/object to connect routes.';
+			throw new \InvalidArgumentException($msg);
+		}
+
+		$collection = new ScopedRouteCollection($path, $params, static::$_validExtensions);
+		$callback($collection);
+
+		if (empty(static::$_pathScopes[$path])) {
+			static::$_pathScopes[$path] = $collection;
+		} else {
+			static::$_pathScopes[$path]->merge($collection);
+		}
+	}
+
 /**
  * Loads route configuration
  *