From 418be7c67cfdbb445923ba362d0929960386c2ec Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sat, 10 Jun 2017 14:19:19 -0400 Subject: [PATCH 1/4] Add documentation for loadPlugin() Refs cakephp/cakephp#10711 --- en/appendices/3-5-migration-guide.rst | 3 +- en/development/routing.rst | 5 +- en/plugins.rst | 76 +++++++++++++++++---------- 3 files changed, 54 insertions(+), 30 deletions(-) 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..f59fb5a6e2 100644 --- a/en/development/routing.rst +++ b/en/development/routing.rst @@ -694,6 +694,9 @@ 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. +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 +713,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..3b3404aaf1 100644 --- a/en/plugins.rst +++ b/en/plugins.rst @@ -280,6 +280,54 @@ 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->fallbacks(DashedRoute::class); + } + ); + +The above will connect default routes for you 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('/a', function ($routes) { + $routes->loadPlugin('ContactManager'); + }); + }); + +The above would result in URLs like ``/a/contact_manager/contacts``. + +.. versionadded:: 3.5.0 + ``RouteBuilder::loadPlugin()`` was added in 3.5.0 + Plugin Controllers ================== @@ -319,34 +367,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. From 471ce1acced0346c6169dd64fb6c84d4624a1b26 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sat, 10 Jun 2017 16:31:52 -0400 Subject: [PATCH 2/4] Fix typos and make plugin example more thorough. --- en/plugins.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/en/plugins.rst b/en/plugins.rst index 3b3404aaf1..36a1e4afda 100644 --- a/en/plugins.rst +++ b/en/plugins.rst @@ -299,11 +299,13 @@ ContactManager plugin routes. Put the following into 'ContactManager', ['path' => '/contact-manager'], function ($routes) { - $routes->fallbacks(DashedRoute::class); + $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 you plugin. You can customize this +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 From 86e546e3460ba17059f74a2be09fcee19b1b0714 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sat, 10 Jun 2017 16:33:35 -0400 Subject: [PATCH 3/4] Add more links. --- en/development/routing.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/en/development/routing.rst b/en/development/routing.rst index f59fb5a6e2..fc9db66a78 100644 --- a/en/development/routing.rst +++ b/en/development/routing.rst @@ -692,7 +692,8 @@ 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 ------------------------------- From 6a284b423b29fc6d5f82d2ec7040f5e0bb405ee4 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sat, 10 Jun 2017 18:44:47 -0400 Subject: [PATCH 4/4] Add a better URL segment. --- en/plugins.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en/plugins.rst b/en/plugins.rst index 36a1e4afda..3a9f1a102f 100644 --- a/en/plugins.rst +++ b/en/plugins.rst @@ -320,12 +320,12 @@ plugin routes in additional scopes or prefixes:: Router::scope('/', function ($routes) { // Connect other routes. - $routes->scope('/a', function ($routes) { + $routes->scope('/backend', function ($routes) { $routes->loadPlugin('ContactManager'); }); }); -The above would result in URLs like ``/a/contact_manager/contacts``. +The above would result in URLs like ``/backend/contact_manager/contacts``. .. versionadded:: 3.5.0 ``RouteBuilder::loadPlugin()`` was added in 3.5.0