Add RouteBuilder::loadPlugin.

Deprecate the static method and provide a route builder method that
allows routes to be loaded inside scopes.

Refs #10689

src/Core/Plugin.php

@@ -329,6 +329,7 @@ class Plugin
      * @param string|null $plugin name of the plugin, if null will operate on all plugins having enabled the
      * loading of routes files
      * @return bool
+     * @deprecated 3.5.0 Use Cake\Routing\RouteBuilder::loadPlugin() instead.
      */
     public static function routes($plugin = null)
     {

src/Routing/RouteBuilder.php

@@ -16,6 +16,8 @@ namespace Cake\Routing;
 
 use BadMethodCallException;
 use Cake\Core\App;
+use Cake\Core\Exception\MissingPluginException;
+use Cake\Core\Plugin;
 use Cake\Routing\Route\Route;
 use Cake\Utility\Inflector;
 use InvalidArgumentException;
@@ -519,6 +521,35 @@ class RouteBuilder
     }
 
     /**
+     * Load routes from a plugin.
+     *
+     * The routes file will have a local variable named `$routes` made available which contains
+     * the current RouteBuilder instance.
+     *
+     * @param string $name The plugin name
+     * @param string $file The routes file to load. Defaults to `routes.php`
+     * @return void
+     * @throws \Cake\Core\Exception\MissingPluginException When the plugin has not been loaded.
+     * @throws \InvalidArgumentException When the plugin does not have a routes file.
+     */
+    public function loadPlugin($name, $file = 'routes.php')
+    {
+        if (!Plugin::loaded($name)) {
+            throw new MissingPluginException(['plugin' => $name]);
+        }
+        $path = Plugin::configPath($name) . DIRECTORY_SEPARATOR . $file;
+        if (!file_exists($path)) {
+            throw new InvalidArgumentException(sprintf(
+                'Cannot load routes for the plugin named %s. The %s file does not exist.',
+                $name,
+                $path
+            ));
+        }
+        $routes = $this;
+        include $path;
+    }
+
+    /**
      * Connects a new Route.
      *
      * Routes are a way of connecting request URLs to objects in your application.

tests/TestCase/Routing/RouteBuilderTest.php

@@ -14,6 +14,7 @@
  */
 namespace Cake\Test\TestCase\Routing;
 
+use Cake\Core\Plugin;
 use Cake\Routing\RouteBuilder;
 use Cake\Routing\RouteCollection;
 use Cake\Routing\Router;
@@ -41,6 +42,17 @@ class RouteBuilderTest extends TestCase
     }
 
     /**
+     * Teardown method
+     *
+     * @return void
+     */
+    public function tearDown()
+    {
+        parent::tearDown();
+        Plugin::unload('TestPlugin');
+    }
+
+    /**
      * Test path()
      *
      * @return void
@@ -906,4 +918,44 @@ class RouteBuilderTest extends TestCase
         $result = $this->collection->parse('/articles/123');
         $this->assertEquals(['123'], $result['pass']);
     }
+
+    /**
+     * Test loading routes from a missing plugin
+     *
+     * @expectedException Cake\Core\Exception\MissingPluginException
+     * @return void
+     */
+    public function testLoadPluginBadPlugin()
+    {
+        $routes = new RouteBuilder($this->collection, '/');
+        $routes->loadPlugin('Nope');
+    }
+
+    /**
+     * Test loading routes from a missing file
+     *
+     * @expectedException InvalidArgumentException
+     * @expectedExceptionMessage Cannot load routes for the plugin named TestPlugin.
+     * @return void
+     */
+    public function testLoadPluginBadFile()
+    {
+        Plugin::load('TestPlugin');
+        $routes = new RouteBuilder($this->collection, '/');
+        $routes->loadPlugin('TestPlugin', 'nope.php');
+    }
+
+    /**
+     * Test loading routes with success
+     *
+     * @return void
+     */
+    public function testLoadPlugin()
+    {
+        Plugin::load('TestPlugin');
+        $routes = new RouteBuilder($this->collection, '/');
+        $routes->loadPlugin('TestPlugin');
+        $this->assertCount(1, $this->collection->routes());
+        $this->assertNotEmpty($this->collection->parse('/test_plugin'));
+    }
 }

tests/test_app/Plugin/TestPlugin/config/routes.php

@@ -2,3 +2,7 @@
 use Cake\Core\Configure;
 
 Configure::write('PluginTest.test_plugin.routes', 'loaded plugin routes');
+
+if (isset($routes)) {
+    $routes->get('/test_plugin', ['controller' => 'TestPlugin', 'plugin' => 'TestPlugin', 'action' => 'index']);
+}