From ce8942456ae28e8f6f5768fb2dac587abc8bbb0c Mon Sep 17 00:00:00 2001 From: kenjis Date: Wed, 11 Jan 2023 21:33:18 +0900 Subject: [PATCH 01/11] docs: update PHPDoc --- system/Common.php | 4 ++-- system/Helpers/url_helper.php | 7 ++++--- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/system/Common.php b/system/Common.php index ab148e5d66d1..1b36545ee3f2 100644 --- a/system/Common.php +++ b/system/Common.php @@ -941,14 +941,14 @@ 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. * diff --git a/system/Helpers/url_helper.php b/system/Helpers/url_helper.php index 45fd5ad110e6..45addcc1fb22 100644 --- a/system/Helpers/url_helper.php +++ b/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 named 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 */ From e91af1cfbe2bc450c5aaab2a7044f3096ed7e921 Mon Sep 17 00:00:00 2001 From: kenjis Date: Wed, 11 Jan 2023 21:42:18 +0900 Subject: [PATCH 02/11] test: add test for url_to() with locale --- tests/system/Helpers/URLHelper/MiscUrlTest.php | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/tests/system/Helpers/URLHelper/MiscUrlTest.php b/tests/system/Helpers/URLHelper/MiscUrlTest.php index fb949f2e9ecc..7f5d9667501a 100644 --- a/tests/system/Helpers/URLHelper/MiscUrlTest.php +++ b/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') + ); + } } From e145c197c2ca932416b6072a8a5fd2b3bb83a5a5 Mon Sep 17 00:00:00 2001 From: kenjis Date: Wed, 11 Jan 2023 21:43:07 +0900 Subject: [PATCH 03/11] docs: update user guide --- user_guide_src/source/general/common_functions.rst | 8 +++++--- user_guide_src/source/helpers/url_helper.rst | 8 ++++++-- user_guide_src/source/helpers/url_helper/025.php | 13 +++++++++++++ 3 files changed, 24 insertions(+), 5 deletions(-) create mode 100644 user_guide_src/source/helpers/url_helper/025.php diff --git a/user_guide_src/source/general/common_functions.rst b/user_guide_src/source/general/common_functions.rst index 02cc8c5924a1..2c358b89fb51 100755 --- a/user_guide_src/source/general/common_functions.rst +++ b/user_guide_src/source/general/common_functions.rst @@ -367,8 +367,10 @@ 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**. @@ -376,7 +378,7 @@ Miscellaneous Functions .. 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 diff --git a/user_guide_src/source/helpers/url_helper.rst b/user_guide_src/source/helpers/url_helper.rst index 8cb19251888d..7607610d64a5 100644 --- a/user_guide_src/source/helpers/url_helper.rst +++ b/user_guide_src/source/helpers/url_helper.rst @@ -361,8 +361,8 @@ The following functions are available: .. php:function:: url_to($controller[, ...$args]) - :param string $controller: Named route or Controller::method - :param mixed ...$args: One or more parameters to be passed to the route + :param string $controller: Route name or Controller::method + :param mixed ...$args: One or more parameters to be passed to the route. The last parameter allows you to set the locale. :returns: Absolute URL :rtype: string @@ -380,6 +380,10 @@ The following functions are available: This is useful because you can still change your routes after putting links into your views. + Since v4.3.0, when you use ``{locale}`` in your route, you can optionally specify the locale value as the last parameter. + + .. literalinclude:: url_helper/025.php + For full details, see the :ref:`reverse-routing` and :ref:`using-named-routes`. .. php:function:: url_is($path) diff --git a/user_guide_src/source/helpers/url_helper/025.php b/user_guide_src/source/helpers/url_helper/025.php new file mode 100644 index 000000000000..6cabfff15bc1 --- /dev/null +++ b/user_guide_src/source/helpers/url_helper/025.php @@ -0,0 +1,13 @@ +add( + '{locale}/users/(:num)/gallery/(:num)', + 'Galleries::showUserGallery/$1/$2', + ['as' => 'user_gallery'] +); + +?> + +View Gallery + From e9778bcae0205885482bfe68a08e2a321d603389 Mon Sep 17 00:00:00 2001 From: kenjis Date: Wed, 11 Jan 2023 21:44:46 +0900 Subject: [PATCH 04/11] docs: fix sample code / was missing. (:any) matches multiple URI segments, so (:num) is better in this case. --- user_guide_src/source/general/common_functions/009.php | 2 +- user_guide_src/source/general/common_functions/010.php | 2 +- user_guide_src/source/general/common_functions/011.php | 2 +- user_guide_src/source/incoming/routing/029.php | 2 +- user_guide_src/source/incoming/routing/030.php | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/user_guide_src/source/general/common_functions/009.php b/user_guide_src/source/general/common_functions/009.php index 41c725478d3f..5b8f7ff505d9 100644 --- a/user_guide_src/source/general/common_functions/009.php +++ b/user_guide_src/source/general/common_functions/009.php @@ -1,7 +1,7 @@ get('users/(:num)/gallery(:any)', 'Galleries::showUserGallery/$1/$2'); +$routes->get('users/(:num)/gallery/(:num)', 'Galleries::showUserGallery/$1/$2'); ?> diff --git a/user_guide_src/source/general/common_functions/010.php b/user_guide_src/source/general/common_functions/010.php index 82df6a7dd714..16280ab7b9a9 100644 --- a/user_guide_src/source/general/common_functions/010.php +++ b/user_guide_src/source/general/common_functions/010.php @@ -1,7 +1,7 @@ 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']); ?> diff --git a/user_guide_src/source/general/common_functions/011.php b/user_guide_src/source/general/common_functions/011.php index 3d354cec2533..0bea6d6d3293 100644 --- a/user_guide_src/source/general/common_functions/011.php +++ b/user_guide_src/source/general/common_functions/011.php @@ -2,7 +2,7 @@ // The route is defined as: $routes->add( - '{locale}/users/(:num)/gallery(:any)', + '{locale}/users/(:num)/gallery/(:num)', 'Galleries::showUserGallery/$1/$2', ['as' => 'user_gallery'] ); diff --git a/user_guide_src/source/incoming/routing/029.php b/user_guide_src/source/incoming/routing/029.php index 58a0e81e25f3..793a93588475 100644 --- a/user_guide_src/source/incoming/routing/029.php +++ b/user_guide_src/source/incoming/routing/029.php @@ -1,7 +1,7 @@ get('users/(:num)/gallery(:any)', 'Galleries::showUserGallery/$1/$2'); +$routes->get('users/(:num)/gallery/(:num)', 'Galleries::showUserGallery/$1/$2'); ?> diff --git a/user_guide_src/source/incoming/routing/030.php b/user_guide_src/source/incoming/routing/030.php index b17465e4f88b..e98bdef8e441 100644 --- a/user_guide_src/source/incoming/routing/030.php +++ b/user_guide_src/source/incoming/routing/030.php @@ -1,7 +1,7 @@ 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']); ?> From 6ed8314dd2ef185172f56e5bd3a1f581f1ff6601 Mon Sep 17 00:00:00 2001 From: kenjis Date: Wed, 11 Jan 2023 21:46:09 +0900 Subject: [PATCH 05/11] docs: make a function name linkable --- user_guide_src/source/incoming/routing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user_guide_src/source/incoming/routing.rst b/user_guide_src/source/incoming/routing.rst index 9dbe274b0a0f..efd3f82313db 100644 --- a/user_guide_src/source/incoming/routing.rst +++ b/user_guide_src/source/incoming/routing.rst @@ -316,7 +316,7 @@ Reverse routing allows you to define the controller and method, as well as any p to, and have the router lookup the current route to it. This allows route definitions to change without you having 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 ``url_to()`` helper +For example, if you have a route to a photo gallery that you want to link to, you can use the :php:func:`url_to()` helper function to get the 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: From e5a3bb936611b1c1e693a05d10f05ef806245026 Mon Sep 17 00:00:00 2001 From: kenjis Date: Wed, 11 Jan 2023 21:46:31 +0900 Subject: [PATCH 06/11] docs: fix function name --- user_guide_src/source/incoming/routing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user_guide_src/source/incoming/routing.rst b/user_guide_src/source/incoming/routing.rst index efd3f82313db..fffa5cb1bdb8 100644 --- a/user_guide_src/source/incoming/routing.rst +++ b/user_guide_src/source/incoming/routing.rst @@ -329,7 +329,7 @@ Using Named Routes ================== You can name routes to make your application less fragile. This applies a name to a route that can be called -later, and even if the route definition changes, all of the links in your application built with ``route_to()`` +later, and even if the route definition changes, all of the links in your application built with :php:func:`url_to()` will still work without you having to make any changes. A route is named by passing in the ``as`` option with the name of the route: From c9552e4ef0dd9f96e765c3f108e2443f185a566e Mon Sep 17 00:00:00 2001 From: kenjis Date: Sat, 14 Jan 2023 09:13:37 +0900 Subject: [PATCH 07/11] docs: make Note more prominent --- user_guide_src/source/general/common_functions.rst | 9 +++++---- user_guide_src/source/general/urls.rst | 2 ++ 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/user_guide_src/source/general/common_functions.rst b/user_guide_src/source/general/common_functions.rst index 2c358b89fb51..b63ee020d380 100755 --- a/user_guide_src/source/general/common_functions.rst +++ b/user_guide_src/source/general/common_functions.rst @@ -374,6 +374,11 @@ Miscellaneous Functions .. 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 @@ -386,10 +391,6 @@ Miscellaneous Functions .. 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 diff --git a/user_guide_src/source/general/urls.rst b/user_guide_src/source/general/urls.rst index 25d7b577d977..965328ce817c 100644 --- a/user_guide_src/source/general/urls.rst +++ b/user_guide_src/source/general/urls.rst @@ -15,6 +15,8 @@ Your URLs can be defined using the :doc:`URI Routing ` featur The :doc:`URI Library <../libraries/uri>` and the :doc:`URL Helper <../helpers/url_helper>` contain functions that make it easy to work with your URI data. +.. _urls-url-structure: + URL Structure ============= From 56ef12181fcdd67b85081ec39128455c8a419216 Mon Sep 17 00:00:00 2001 From: kenjis Date: Fri, 20 Jan 2023 11:30:24 +0900 Subject: [PATCH 08/11] docs: replace SCRIPT_NAME with baseURL It is easier to understand. --- system/HTTP/IncomingRequest.php | 8 ++++---- system/HTTP/URI.php | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/system/HTTP/IncomingRequest.php b/system/HTTP/IncomingRequest.php index ef69a08996f6..3304f4664a76 100755 --- a/system/HTTP/IncomingRequest.php +++ b/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 diff --git a/system/HTTP/URI.php b/system/HTTP/URI.php index 23227e98d0f2..009bfdea0f1a 100644 --- a/system/HTTP/URI.php +++ b/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 From c455f5e084eb4c5320c3bd725f522de848541dfd Mon Sep 17 00:00:00 2001 From: kenjis Date: Fri, 20 Jan 2023 11:32:09 +0900 Subject: [PATCH 09/11] docs: add @return explanations --- system/Common.php | 2 +- system/Router/RouteCollection.php | 2 +- system/Router/RouteCollectionInterface.php | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/system/Common.php b/system/Common.php index 1b36545ee3f2..f73a4d4d78d8 100644 --- a/system/Common.php +++ b/system/Common.php @@ -952,7 +952,7 @@ function response(): ResponseInterface * @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) { diff --git a/system/Router/RouteCollection.php b/system/Router/RouteCollection.php index 30be78a2bce5..9df41b0a8588 100644 --- a/system/Router/RouteCollection.php +++ b/system/Router/RouteCollection.php @@ -1044,7 +1044,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) { diff --git a/system/Router/RouteCollectionInterface.php b/system/Router/RouteCollectionInterface.php index 7044459899c2..00ac88f4b7e2 100644 --- a/system/Router/RouteCollectionInterface.php +++ b/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); From 76d53d631e57cb4f1623ffe05c7115ae2921addb Mon Sep 17 00:00:00 2001 From: kenjis Date: Fri, 20 Jan 2023 11:32:54 +0900 Subject: [PATCH 10/11] docs: fix typo --- system/Helpers/url_helper.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system/Helpers/url_helper.php b/system/Helpers/url_helper.php index 45addcc1fb22..1a3b78de5c91 100644 --- a/system/Helpers/url_helper.php +++ b/system/Helpers/url_helper.php @@ -542,7 +542,7 @@ function mb_url_title(string $str, string $separator = '-', bool $lowercase = fa if (! function_exists('url_to')) { /** - * Get the full, absolute URL to a route named or controller method + * Get the full, absolute URL to a route name or controller method * (with additional arguments) * * NOTE: This requires the controller/method to From 243531150004820dd27cb8d0440228ad7de61614 Mon Sep 17 00:00:00 2001 From: kenjis Date: Fri, 20 Jan 2023 11:37:41 +0900 Subject: [PATCH 11/11] docs: replace SCRIPT_NAME with baseURL --- user_guide_src/source/incoming/incomingrequest.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user_guide_src/source/incoming/incomingrequest.rst b/user_guide_src/source/incoming/incomingrequest.rst index 163a0b46b68a..f54b1f9ff741 100644 --- a/user_guide_src/source/incoming/incomingrequest.rst +++ b/user_guide_src/source/incoming/incomingrequest.rst @@ -473,7 +473,7 @@ The methods provided by the parent classes that are available are: .. php:method:: getPath() - :returns: The current URI path relative to ``$_SERVER['SCRIPT_NAME']`` + :returns: The current URI path relative to baseURL :rtype: string This is the safest method to determine the "current URI", since ``IncomingRequest::$uri``