Merge pull request #7090 from kenjis/fix-docs-route-to-url-to

docs: improve route_to() and url_to()

Author: kenjis

system/Common.php

@@ -941,18 +941,18 @@ function response(): ResponseInterface
 
 if (! function_exists('route_to')) {
     /**
-     * Given a controller/method string and any params,
+     * Given a route name or controller/method string and any params,
      * will attempt to build the relative URL to the
      * matching route.
      *
      * NOTE: This requires the controller/method to
      * have a route defined in the routes Config file.
      *
-     * @param string     $method    Named route or Controller::method
+     * @param string     $method    Route name or Controller::method
      * @param int|string ...$params One or more parameters to be passed to the route.
      *                              The last parameter allows you to set the locale.
      *
-     * @return false|string
+     * @return false|string The route (URI path relative to baseURL) or false if not found.
      */
     function route_to(string $method, ...$params)
     {

system/HTTP/IncomingRequest.php

@@ -62,8 +62,8 @@ class IncomingRequest extends Request
      *
      * Note: This WILL NOT match the actual URL in the browser since for
      * everything this cares about (and the router, etc) is the portion
-     * AFTER the script name. So, if hosted in a sub-folder this will
-     * appear different than actual URL. If you need that use getPath().
+     * AFTER the baseURL. So, if hosted in a sub-folder this will
+     * appear different than actual URI path. If you need that use getPath().
      *
      * @deprecated Will be protected. Use getUri() instead.
      *
@@ -72,7 +72,7 @@ class IncomingRequest extends Request
     public $uri;
 
     /**
-     * The detected path (relative to SCRIPT_NAME).
+     * The detected URI path (relative to the baseURL).
      *
      * Note: current_url() uses this to build its URI,
      * so this becomes the source for the "current URL"
@@ -511,7 +511,7 @@ private function determineHost(App $config, string $baseURL): string
     }
 
     /**
-     * Returns the path relative to SCRIPT_NAME,
+     * Returns the URI path relative to baseURL,
      * running detection as necessary.
      */
     public function getPath(): string

system/HTTP/URI.php

@@ -90,7 +90,7 @@ class URI
      *
      * Note: The constructor of the IncomingRequest class changes the path of
      *      the URI object held by the IncomingRequest class to a path relative
-     *      to the SCRIPT_NAME. If the baseURL contains subfolders, this value
+     *      to the baseURL. If the baseURL contains subfolders, this value
      *      will be different from the current URI path.
      *
      * @var string

system/Helpers/url_helper.php

@@ -542,14 +542,15 @@ function mb_url_title(string $str, string $separator = '-', bool $lowercase = fa
 
 if (! function_exists('url_to')) {
     /**
-     * Get the full, absolute URL to a controller method
+     * Get the full, absolute URL to a route name or controller method
      * (with additional arguments)
      *
      * NOTE: This requires the controller/method to
      * have a route defined in the routes Config file.
      *
-     * @param string     $controller Named route or Controller::method
-     * @param int|string ...$args    One or more parameters to be passed to the route
+     * @param string     $controller Route name or Controller::method
+     * @param int|string ...$args    One or more parameters to be passed to the route.
+     *                               The last parameter allows you to set the locale.
      *
      * @throws RouterException
      */

system/Router/RouteCollection.php

@@ -1047,7 +1047,7 @@ public function environment(string $env, Closure $callback): RouteCollectionInte
      * @param int|string ...$params One or more parameters to be passed to the route.
      *                              The last parameter allows you to set the locale.
      *
-     * @return false|string
+     * @return false|string The route (URI path relative to baseURL) or false if not found.
      */
     public function reverseRoute(string $search, ...$params)
     {

system/Router/RouteCollectionInterface.php

@@ -172,7 +172,7 @@ public function getHTTPVerb();
      * @param string     $search    Named route or Controller::method
      * @param int|string ...$params
      *
-     * @return false|string
+     * @return false|string The route (URI path relative to baseURL) or false if not found.
      */
     public function reverseRoute(string $search, ...$params);
 

tests/system/Helpers/URLHelper/MiscUrlTest.php

@@ -884,4 +884,20 @@ public function urlToMissingRoutesProvider()
             ],
         ];
     }
+
+    public function testUrlToWithSupportedLocaleInRoute()
+    {
+        Services::createRequest(new App());
+        $routes = service('routes');
+        $routes->add(
+            '{locale}/path/(:segment)/to/(:num)',
+            'myController::goto/$1/$2',
+            ['as' => 'path-to']
+        );
+
+        $this->assertSame(
+            'http://example.com/index.php/en/path/string/to/13',
+            url_to('path-to', 'string', 13, 'en')
+        );
+    }
 }

user_guide_src/source/general/common_functions.rst

@@ -367,27 +367,30 @@ Miscellaneous Functions
 
 .. php:function:: route_to($method[, ...$params])
 
-    :param   string  $method: The named route alias, or name of the controller/method to match.
-    :param   int|string   $params: One or more parameters to be passed to be matched in the route. The last parameter allows you to set the locale.
+    :param   string       $method: Route name or Controller::method
+    :param   int|string   ...$params: One or more parameters to be passed to the route. The last parameter allows you to set the locale.
+    :returns: a route (URI path)
+    :rtype: string
 
     .. note:: This function requires the controller/method to have a route defined in **app/Config/routes.php**.
 
+    .. important:: ``route_to()`` returns a *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, just use :php:func:`url_to()` instead.
+        See also :ref:`urls-url-structure`.
+
     Generates a route for you based on a controller::method combination. Will take parameters into effect, if provided.
 
     .. literalinclude:: common_functions/009.php
 
-    Generates a route for you based on a named route alias.
+    Generates a route for you based on a route name.
 
     .. literalinclude:: common_functions/010.php
 
     Since v4.3.0, when you use ``{locale}`` in your route, you can optionally specify the locale value as the last parameter.
 
     .. literalinclude:: common_functions/011.php
 
-    .. note:: ``route_to()`` returns a 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, just use :php:func:`url_to()` instead.
-
 .. php:function:: service($name[, ...$params])
 
     :param   string   $name: The name of the service to load

user_guide_src/source/general/common_functions/009.php

@@ -1,7 +1,7 @@
 <?php
 
 // The route is defined as:
-$routes->get('users/(:num)/gallery(:any)', 'Galleries::showUserGallery/$1/$2');
+$routes->get('users/(:num)/gallery/(:num)', 'Galleries::showUserGallery/$1/$2');
 
 ?>
 

user_guide_src/source/general/common_functions/010.php

@@ -1,7 +1,7 @@
 <?php
 
 // The route is defined as:
-$routes->get('users/(:num)/gallery(:any)', 'Galleries::showUserGallery/$1/$2', ['as' => 'user_gallery']);
+$routes->get('users/(:num)/gallery/(:num)', 'Galleries::showUserGallery/$1/$2', ['as' => 'user_gallery']);
 
 ?>