Skip to content

Commit

Permalink
Merge pull request #7090 from kenjis/fix-docs-route-to-url-to
Browse files Browse the repository at this point in the history
docs: improve route_to() and url_to()
  • Loading branch information
kenjis authored Jan 25, 2023
2 parents c58889b + 2435311 commit ecef7f7
Show file tree
Hide file tree
Showing 18 changed files with 69 additions and 30 deletions.
6 changes: 3 additions & 3 deletions system/Common.php
Original file line number Diff line number Diff line change
Expand Up @@ -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)
{
Expand Down
8 changes: 4 additions & 4 deletions system/HTTP/IncomingRequest.php
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
Expand All @@ -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"
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion system/HTTP/URI.php
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 4 additions & 3 deletions system/Helpers/url_helper.php
Original file line number Diff line number Diff line change
Expand Up @@ -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
*/
Expand Down
2 changes: 1 addition & 1 deletion system/Router/RouteCollection.php
Original file line number Diff line number Diff line change
Expand Up @@ -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)
{
Expand Down
2 changes: 1 addition & 1 deletion system/Router/RouteCollectionInterface.php
Original file line number Diff line number Diff line change
Expand Up @@ -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);

Expand Down
16 changes: 16 additions & 0 deletions tests/system/Helpers/URLHelper/MiscUrlTest.php
Original file line number Diff line number Diff line change
Expand Up @@ -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')
);
}
}
17 changes: 10 additions & 7 deletions user_guide_src/source/general/common_functions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion user_guide_src/source/general/common_functions/009.php
Original file line number Diff line number Diff line change
@@ -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');

?>

Expand Down
2 changes: 1 addition & 1 deletion user_guide_src/source/general/common_functions/010.php
Original file line number Diff line number Diff line change
@@ -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']);

?>

Expand Down
2 changes: 1 addition & 1 deletion user_guide_src/source/general/common_functions/011.php
Original file line number Diff line number Diff line change
Expand Up @@ -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']
);
Expand Down
2 changes: 2 additions & 0 deletions user_guide_src/source/general/urls.rst
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ Your URLs can be defined using the :doc:`URI Routing </incoming/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
=============

Expand Down
8 changes: 6 additions & 2 deletions user_guide_src/source/helpers/url_helper.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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)
Expand Down
13 changes: 13 additions & 0 deletions user_guide_src/source/helpers/url_helper/025.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
<?php

// The route is defined as:
$routes->add(
'{locale}/users/(:num)/gallery/(:num)',
'Galleries::showUserGallery/$1/$2',
['as' => 'user_gallery']
);

?>

<a href="<?= url_to('user_gallery', 15, 12, 'en') ?>">View Gallery</a>
<!-- Result: 'http://example.com/en/users/15/gallery/12' -->
2 changes: 1 addition & 1 deletion user_guide_src/source/incoming/incomingrequest.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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``
Expand Down
4 changes: 2 additions & 2 deletions user_guide_src/source/incoming/routing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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:

Expand Down
2 changes: 1 addition & 1 deletion user_guide_src/source/incoming/routing/029.php
Original file line number Diff line number Diff line change
@@ -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');

?>

Expand Down
2 changes: 1 addition & 1 deletion user_guide_src/source/incoming/routing/030.php
Original file line number Diff line number Diff line change
@@ -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']);

?>

Expand Down

0 comments on commit ecef7f7

Please sign in to comment.