docs: improve route_to() and url_to()

Author: kenjis

user_guide_src/source/general/common_functions.rst

@@ -329,14 +329,14 @@ Miscellaneous Functions
 .. php:function:: route_to($method[, ...$params])
 
     :param   string  $method: The named route alias, or name of the controller/method to match.
-    :param   mixed   $params: One or more parameters to be passed to be matched in the route.
+    :param   int|string   $params: One or more parameters to be passed to be matched in the route.
 
     .. note:: This function requires the controller/method to have a route defined in **app/Config/routes.php**.
 
-    Generates a URI relative to the domain name (not **baseUrl**) for you based on either a named route alias,
+    Generates a URI path (route) for you based on either a named route alias,
     or a controller::method combination. Will take parameters into effect, if provided.
 
-    For full details, see the :doc:`/incoming/routing` page.
+    For full details, see the :ref:`reverse-routing` and :ref:`using-named-routes`.
 
 .. php:function:: service($name[, ...$params])
 

user_guide_src/source/helpers/url_helper.rst

@@ -346,8 +346,8 @@ The following functions are available:
 
 .. php:function:: url_to($controller[, ...$args])
 
-    :param  string  $controller: The controller class and method
-    :param  mixed   ...$args: Additional arguments to be injected into the route
+    :param  string  $controller: Named route or Controller::method
+    :param  mixed   ...$args:    One or more parameters to be passed to the route
     :returns: Absolute URL
     :rtype: string
 
@@ -362,9 +362,6 @@ The following functions are available:
 
     .. literalinclude:: url_helper/022.php
 
-    The above example would return something like:
-    *http://example.com/page/home*
-
     This is useful because you can still change your routes after putting links
     into your views.
 

user_guide_src/source/helpers/url_helper/021.php

@@ -1,3 +1,10 @@
 <?php
 
-echo url_to('Home::index');
+// The route is defined as:
+$routes->get('/', 'Home::index');
+
+?>
+
+<a href="<?= url_to('Home::index') ?>">Home</a>
+<!-- Result: 'http://example.com/' -->
+

user_guide_src/source/helpers/url_helper/022.php

@@ -1,3 +1,9 @@
 <?php
 
-echo url_to('Page::index', 'home');
+// The route is defined as:
+$routes->get('pages/(:segment)', 'Page::index/$1');
+
+?>
+
+<a href="<?= url_to('Page::index', 'home') ?>">Home</a>
+<!-- Result: 'http://example.com/pages/home' -->

user_guide_src/source/incoming/routing.rst

@@ -269,6 +269,8 @@ routes defined within this closure are only accessible from the given environmen
 
 .. literalinclude:: routing/028.php
 
+.. _reverse-routing:
+
 Reverse Routing
 ===============
 
@@ -277,12 +279,19 @@ to, and have the router lookup the current route to it. This allows route defini
 to update your application code. This is typically used within views to create links.
 
 For example, if you have a route to a photo gallery that you want to link to, you can use the ``route_to()`` helper
-function to get the current route that should be used. The first parameter is the fully qualified Controller and method,
+function to get the URI path (route) that should be used. The first parameter is the fully qualified Controller and method,
 separated by a double colon (``::``), much like you would use when writing the initial route itself. Any parameters that
 should be passed to the route are passed in next:
 
 .. literalinclude:: routing/029.php
 
+.. note:: ``route_to()`` returns a URI path for the route, not a full URI path
+    for your site. If your **baseURL** contains sub folders, the return value is
+    not the same as the URI to link. In that case, you need to use :php:func:`site_url`
+    like ``site_url(route_to(...))``, or just use :php:func:`url_to` instead.
+
+.. _using-named-routes:
+
 Using Named Routes
 ==================
 
@@ -295,6 +304,11 @@ with the name of the route:
 
 This has the added benefit of making the views more readable, too.
 
+.. note:: ``route_to()`` returns a URI path for the route, not a full URI path
+    for your site. If your **baseURL** contains sub folders, the return value is
+    not the same as the URI to link. In that case, you need to use :php:func:`site_url`
+    like ``site_url(route_to(...))``, or just use :php:func:`url_to` instead.
+
 Routes with any HTTP verbs
 ==========================
 

user_guide_src/source/incoming/routing/029.php

@@ -5,6 +5,6 @@
 
 ?>
 
-<!-- Generate the relative URL to link to user ID 15, gallery 12: -->
+<!-- Generate the URI path (route) to link to user ID 15, gallery 12: -->
 <a href="<?= route_to('Galleries::showUserGallery', 15, 12) ?>">View Gallery</a>
 <!-- Result: '/users/15/gallery/12' -->

user_guide_src/source/incoming/routing/030.php

@@ -5,6 +5,6 @@
 
 ?>
 
-<!-- Generate the relative URL to link to user ID 15, gallery 12: -->
+<!-- Generate the URI path (route) to link to user ID 15, gallery 12: -->
 <a href="<?= route_to('user_gallery', 15, 12) ?>">View Gallery</a>
 <!-- Result: '/users/15/gallery/12' -->