From 2930bcd1df4899449adef12ae371ae2ad9d0ebba Mon Sep 17 00:00:00 2001
From: Mark Story <mark@mark-story.com>
Date: Sat, 19 Mar 2016 11:52:12 -0400
Subject: [PATCH] Add docs for nested resource routing.

Refs cakephp/cakephp#8493
---
 en/appendices/3-3-migration-guide.rst |  4 +++-
 en/development/routing.rst            | 20 +++++++++++++++++++-
 2 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/en/appendices/3-3-migration-guide.rst b/en/appendices/3-3-migration-guide.rst
index aa76a3122b..c1d84cfd8c 100644
--- a/en/appendices/3-3-migration-guide.rst
+++ b/en/appendices/3-3-migration-guide.rst
@@ -10,7 +10,9 @@ Routing
 - ``Router::parse()``, ``RouteCollection::parse()`` and ``Route::parse()`` had
   a ``$method`` argument added. It defaults to 'GET'. This new parameter reduces
   reliance on global state, and necessary for the PSR7 work integration to be done.
-
+- When building resource routes, you can now define a prefix. This is useful
+  when defining nested resources as you can create specialized controllers for
+  nested resources.
 
 ORM
 ===
diff --git a/en/development/routing.rst b/en/development/routing.rst
index c249ea0b0f..cb1af947ac 100644
--- a/en/development/routing.rst
+++ b/en/development/routing.rst
@@ -749,13 +749,31 @@ comments routes will look like::
 
 You can get the ``article_id`` in ``CommentsController`` by::
 
-    $this->request->params['article_id']
+    $this->request->param('article_id');
+
+By default resource routes map to the same prefix as the containing scope. If
+you have both nested and non-nested resource controllers you can use a different
+controller in each context by using prefixes::
+
+    Router::scope('/api', function ($routes) {
+        $routes->resources('Articles', function ($routes) {
+            $routes->resources('Comments', ['prefix' => 'articles']);
+        });
+    });
+
+The above would map the 'Comments' resource to the
+``App\Controller\Articles\CommentsController``. Having separate controllers lets
+you keep your controller logic simpler. The prefixes created this way are
+compatible with :ref:`prefix-routing`.
 
 .. note::
 
     While you can nest resources as deeply as you require, it is not recommended
     to nest more than 2 resources together.
 
+.. versionadded:: 3.3
+    The ``prefix`` option was added to ``resources()`` in 3.3.
+
 Limiting the Routes Created
 ---------------------------