diff --git a/en/appendices/3-5-migration-guide.rst b/en/appendices/3-5-migration-guide.rst index 3bc276ed21..e3f9450750 100644 --- a/en/appendices/3-5-migration-guide.rst +++ b/en/appendices/3-5-migration-guide.rst @@ -8,7 +8,7 @@ To upgrade to 3.5.x run the following composer command: .. code-block:: bash - php composer.phar require "cakephp/cakephp:3.5.*" + php composer.phar require --update-with-dependencies "cakephp/cakephp:3.5.*" Deprecations ============ @@ -180,6 +180,7 @@ Routing match. * ``Cake\Routing\RouteBuilder`` now has methods to create routes for specific HTTP methods. e.g ``get()`` and ``post()``. +* ``Cake\Routing\RouteBuilder::loadPlugin()`` was added. * ``Cake\Routing\Route`` now has fluent methods for defining options. Validation diff --git a/en/development/routing.rst b/en/development/routing.rst index f44e819a12..fc9db66a78 100644 --- a/en/development/routing.rst +++ b/en/development/routing.rst @@ -692,7 +692,11 @@ When using scopes you can nest plugin scopes within prefix scopes:: }); The above would create a route that looks like ``/admin/debug_kit/:controller``. -It would have the ``prefix``, and ``plugin`` route elements set. +It would have the ``prefix``, and ``plugin`` route elements set. The +:ref:`plugin-routes` section has more information on building plugin routes. + +Creating Links to Plugin Routes +------------------------------- You can create links that point to a plugin, by adding the plugin key to your URL array:: @@ -710,7 +714,7 @@ a link that has no plugin you can do the following:: ['plugin' => null, 'controller' => 'Users', 'action' => 'profile'] ); -By setting ``plugin => null`` you tell the Router that you want to +By setting ``'plugin' => null`` you tell the Router that you want to create a link that is not part of a plugin. SEO-Friendly Routing diff --git a/en/plugins.rst b/en/plugins.rst index 95a99eeeea..3a9f1a102f 100644 --- a/en/plugins.rst +++ b/en/plugins.rst @@ -280,6 +280,56 @@ autoloader once you've created your plugin: $ php composer.phar dumpautoload +.. _plugin-routes: + +Plugin Routes +============= + +Plugins can provide routes files containing their routes. Each plugin can +contain a **config/routes.php** file. This routes file can be loaded when the +plugin is added, or in the application's routes file. To create the +ContactManager plugin routes. Put the following into +**plugins/ContactManager/config/routes.php**:: + + '/contact-manager'], + function ($routes) { + $routes->get('/contacts', ['controller' => 'Contacts']); + $routes->get('/contacts/:id', ['controller' => 'Contacts', 'action' => 'view']); + $routes->put('/contacts/:id', ['controller' => 'Contacts', 'action' => 'update']); + } + ); + +The above will connect default routes for your plugin. You can customize this +file with more specific routes later on. + +Before you can access your controllers, you'll need to ensure the plugin is +loaded and the plugin routes are loaded. In your **config/bootstrap.php** add +the following:: + + Plugin::load('ContactManager', ['routes' => true]); + +You can also load plugin routes in your application's routes list. Doing this +provides you more control on how plugin routes are loaded and allows you to wrap +plugin routes in additional scopes or prefixes:: + + Router::scope('/', function ($routes) { + // Connect other routes. + $routes->scope('/backend', function ($routes) { + $routes->loadPlugin('ContactManager'); + }); + }); + +The above would result in URLs like ``/backend/contact_manager/contacts``. + +.. versionadded:: 3.5.0 + ``RouteBuilder::loadPlugin()`` was added in 3.5.0 + Plugin Controllers ================== @@ -319,34 +369,6 @@ Also make the ``AppController`` if you don't have one already:: A plugin's ``AppController`` can hold controller logic common to all controllers in a plugin but is not required if you don't want to use one. -Before you can access your controllers, you'll need to ensure the plugin is -loaded and the plugin routes are loaded. In your **config/bootstrap.php** add -the following:: - - Plugin::load('ContactManager', ['routes' => true]); - -If you are using ``Plugin::loadAll()`` ensure that routes are loaded:: - - Plugin::loadAll(['routes' => true]); - -Then create the ContactManager plugin routes. Put the following into -**plugins/ContactManager/config/routes.php**:: - - '/contact-manager'], - function ($routes) { - $routes->fallbacks(DashedRoute::class); - } - ); - -The above will connect default routes for you plugin. You can customize this -file with more specific routes later on. - If you want to access what we've got going thus far, visit ``/contact-manager/contacts``. You should get a "Missing Model" error because we don't have a Contact model defined yet.