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

docs: improve route_to() and url_to()

Author: kenjis

system/Common.php

@@ -905,7 +905,8 @@ function remove_invisible_characters(string $str, bool $urlEncoded = true): stri
      * NOTE: This requires the controller/method to
      * have a route defined in the routes Config file.
      *
-     * @param mixed ...$params
+     * @param string     $method    Named route or Controller::method
+     * @param int|string ...$params One or more parameters to be passed to the route
      *
      * @return false|string
      */

system/Helpers/url_helper.php

@@ -525,7 +525,8 @@ function mb_url_title(string $str, string $separator = '-', bool $lowercase = fa
      * NOTE: This requires the controller/method to
      * have a route defined in the routes Config file.
      *
-     * @param mixed ...$args
+     * @param string     $controller Named route or Controller::method
+     * @param int|string ...$args    One or more parameters to be passed to the route
      *
      * @throws RouterException
      */

system/Router/RouteCollection.php

@@ -989,7 +989,8 @@ public function environment(string $env, Closure $callback): RouteCollectionInte
      *      // Equals 'path/$param1/$param2'
      *      reverseRoute('Controller::method', $param1, $param2);
      *
-     * @param mixed ...$params
+     * @param string     $search    Named route or Controller::method
+     * @param int|string ...$params One or more parameters to be passed to the route
      *
      * @return false|string
      */

system/Router/RouteCollectionInterface.php

@@ -169,7 +169,8 @@ public function getHTTPVerb();
      *      // Equals 'path/$param1/$param2'
      *      reverseRoute('Controller::method', $param1, $param2);
      *
-     * @param array ...$params
+     * @param string     $search    Named route or Controller::method
+     * @param int|string ...$params
      *
      * @return false|string
      */

user_guide_src/source/general/common_functions.rst

@@ -65,7 +65,7 @@ Service Accessors
     values that are specific to the environment itself, like database
     settings, API keys, etc.
 
-.. php:function:: esc($data[, $context = 'html' [, $encoding]])
+.. php:function:: esc($data[, $context = 'html'[, $encoding]])
 
     :param   string|array   $data: The information to be escaped.
     :param   string   $context: The escaping context. Default is 'html'.
@@ -89,7 +89,7 @@ Service Accessors
 
     For full details, see the :doc:`helpers` page.
 
-.. php:function:: lang($line[, $args[, $locale ]])
+.. php:function:: lang($line[, $args[, $locale]])
 
     :param string $line: The line of text to retrieve
     :param array  $args: An array of data to substitute for placeholders.
@@ -99,15 +99,15 @@ Service Accessors
 
     For more information, see the :doc:`Localization </outgoing/localization>` page.
 
-.. php:function:: model($name [, $getShared = true [, &$conn = null ]])
+.. php:function:: model($name[, $getShared = true[, &$conn = null]])
 
     :param string                   $name:
     :param boolean                  $getShared:
     :param ConnectionInterface|null $conn:
     :returns: More simple way of getting model instances
     :rtype: mixed
 
-.. php:function:: old( $key[, $default = null, [, $escape = 'html' ]] )
+.. php:function:: old($key[, $default = null,[, $escape = 'html']])
 
     :param string $key: The name of the old form data to check for.
     :param mixed  $default: The default value to return if $key doesn't exist.
@@ -124,7 +124,7 @@ Service Accessors
 .. note:: If you are using the :doc:`form helper </helpers/form_helper>`, this feature is built-in. You only
         need to use this function when not using the form helper.
 
-.. php:function:: session( [$key] )
+.. php:function:: session([$key])
 
     :param string $key: The name of the session item to check for.
     :returns: An instance of the Session object if no $key, the value found in the session for $key, or null.
@@ -133,7 +133,7 @@ Service Accessors
     Provides a convenient way to access the session class and to retrieve a
     stored value. For more information, see the :doc:`Sessions </libraries/sessions>` page.
 
-.. php:function:: timer( [$name] )
+.. php:function:: timer([$name])
 
     :param string $name: The name of the benchmark point.
     :returns: The Timer instance
@@ -147,7 +147,7 @@ Service Accessors
 
     .. literalinclude:: common_functions/003.php
 
-.. php:function:: view ($name [, $data [, $options ]])
+.. php:function:: view($name[, $data[, $options]])
 
     :param   string   $name: The name of the file to load
     :param   array    $data: An array of key/value pairs to make available within the view.
@@ -175,7 +175,7 @@ Service Accessors
 
     For more details, see the :doc:`Views </outgoing/views>` page.
 
-.. php:function:: view_cell ( $library [, $params = null [, $ttl = 0 [, $cacheName = null]]] )
+.. php:function:: view_cell($library[, $params = null[, $ttl = 0[, $cacheName = null]]])
 
     :param string      $library:
     :param null        $params:
@@ -189,51 +189,51 @@ Service Accessors
 Miscellaneous Functions
 =======================
 
-.. php:function:: app_timezone ()
+.. php:function:: app_timezone()
 
     :returns: The timezone the application has been set to display dates in.
     :rtype: string
 
     Returns the timezone the application has been set to display dates in.
 
-.. php:function:: csp_script_nonce ()
+.. php:function:: csp_script_nonce()
 
     :returns: The CSP nonce attribute for script tag.
     :rtype: string
 
     Returns the nonce attribute for a script tag. For example: ``nonce="Eskdikejidojdk978Ad8jf"``.
     See :ref:`content-security-policy`.
 
-.. php:function:: csp_style_nonce ()
+.. php:function:: csp_style_nonce()
 
     :returns: The CSP nonce attribute for style tag.
     :rtype: string
 
     Returns the nonce attribute for a style tag. For example: ``nonce="Eskdikejidojdk978Ad8jf"``.
     See :ref:`content-security-policy`.
 
-.. php:function:: csrf_token ()
+.. php:function:: csrf_token()
 
     :returns: The name of the current CSRF token.
     :rtype: string
 
     Returns the name of the current CSRF token.
 
-.. php:function:: csrf_header ()
+.. php:function:: csrf_header()
 
     :returns: The name of the header for current CSRF token.
     :rtype: string
 
     The name of the header for current CSRF token.
 
-.. php:function:: csrf_hash ()
+.. php:function:: csrf_hash()
 
     :returns: The current value of the CSRF hash.
     :rtype: string
 
     Returns the current CSRF hash value.
 
-.. php:function:: csrf_field ()
+.. php:function:: csrf_field()
 
     :returns: A string with the HTML for hidden input with all required CSRF information.
     :rtype: string
@@ -242,7 +242,7 @@ Miscellaneous Functions
 
         <input type="hidden" name="{csrf_token}" value="{csrf_hash}">
 
-.. php:function:: csrf_meta ()
+.. php:function:: csrf_meta()
 
     :returns: A string with the HTML for meta tag with all required CSRF information.
     :rtype: string
@@ -251,7 +251,7 @@ Miscellaneous Functions
 
         <meta name="{csrf_header}" content="{csrf_hash}">
 
-.. php:function:: force_https ( $duration = 31536000 [, $request = null [, $response = null]] )
+.. php:function:: force_https($duration = 31536000[, $request = null[, $response = null]])
 
     :param  int  $duration: The number of seconds browsers should convert links to this resource to HTTPS.
     :param  RequestInterface $request: An instance of the current Request object.
@@ -262,24 +262,24 @@ Miscellaneous Functions
     but through HTTPS. Will set the HTTP Strict Transport Security header, which instructs
     modern browsers to automatically modify any HTTP requests to HTTPS requests for the $duration.
 
-.. php:function:: function_usable ( $function_name )
+.. php:function:: function_usable($function_name)
 
     :param string $function_name: Function to check for
     :returns: true if the function exists and is safe to call, false otherwise.
     :rtype: bool
 
-.. php:function:: is_cli ()
+.. php:function:: is_cli()
 
     :returns: true if the script is being executed from the command line or false otherwise.
     :rtype: bool
 
-.. php:function:: is_really_writable ( $file )
+.. php:function:: is_really_writable($file)
 
     :param string $file: The filename being checked.
     :returns: true if you can write to the file, false otherwise.
     :rtype: bool
 
-.. php:function:: log_message ($level, $message [, $context])
+.. php:function:: log_message($level, $message [, $context])
 
     :param   string   $level: The level of severity
     :param   string   $message: The message that is to be logged.
@@ -295,7 +295,7 @@ Miscellaneous Functions
     Context can be used to substitute values in the message string. For full details, see the
     :doc:`Logging Information <logging>` page.
 
-.. php:function:: redirect( string $route )
+.. php:function:: redirect(string $route)
 
     :param  string  $route: The reverse-routed or named route to redirect the user to.
 
@@ -326,19 +326,25 @@ Miscellaneous Functions
 
     .. literalinclude:: common_functions/007.php
 
-.. php:function:: route_to ( $method [, ...$params] )
+.. 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 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.
+    .. literalinclude:: common_functions/009.php
 
-.. php:function:: service ( $name [, ...$params] )
+    .. literalinclude:: common_functions/010.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
     :param   mixed    $params: One or more parameters to pass to the service method.
@@ -353,7 +359,7 @@ Miscellaneous Functions
 
     .. literalinclude:: common_functions/008.php
 
-.. php:function:: single_service ( $name [, ...$params] )
+.. php:function:: single_service($name [, ...$params])
 
     :param   string   $name: The name of the service to load
     :param   mixed    $params: One or more parameters to pass to the service method.
@@ -372,7 +378,7 @@ Miscellaneous Functions
 
     Fetch a config file item with slash appended (if not empty)
 
-.. php:function:: stringify_attributes ( $attributes [, $js] )
+.. php:function:: stringify_attributes($attributes [, $js])
 
     :param   mixed    $attributes: string, array of key value pairs, or object
     :param   boolean  $js: true if values do not need quotes (Javascript-style)

user_guide_src/source/general/common_functions/009.php

@@ -0,0 +1,12 @@
+<?php
+
+// The route is defined as:
+$routes->get('users/(:num)/gallery(:any)', 'Galleries::showUserGallery/$1/$2');
+
+?>
+
+<?php
+
+// Generate the route with user ID 15, gallery 12:
+route_to('Galleries::showUserGallery', 15, 12);
+// Result: '/users/15/gallery/12'

user_guide_src/source/general/common_functions/010.php

@@ -0,0 +1,12 @@
+<?php
+
+// The route is defined as:
+$routes->get('users/(:num)/gallery(:any)', 'Galleries::showUserGallery/$1/$2', ['as' => 'user_gallery']);
+
+?>
+
+<?php
+
+// Generate the route with user ID 15, gallery 12:
+route_to('user_gallery', 15, 12);
+// Result: '/users/15/gallery/12'

user_guide_src/source/general/urls.rst

@@ -9,12 +9,47 @@ CodeIgniter URLs
 By default, URLs in CodeIgniter are designed to be search-engine and human-friendly. Rather than using the standard
 "query-string" approach to URLs that is synonymous with dynamic systems, CodeIgniter uses a **segment-based** approach::
 
-    example.com/news/article/my_article
+    https://example.com/news/article/my_article
 
 Your URLs can be defined using the :doc:`URI Routing </incoming/routing>` feature with flexibility.
 
 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.
 
+URL Structure
+=============
+
+Base URL contains only the Hostname
+-----------------------------------
+
+When you have the Base URL **https://www.example.com/** and imagine the following URL::
+
+    https://www.example.com/blog/news/2022/10?page=2
+
+We use the following terms:
+
+======== ============================
+Base URL **https://www.example.com/**
+URI path /blog/news/2022/10
+Route    /blog/news/2022/10
+Query    page=2
+======== ============================
+
+Base URL contains Sub folders
+-----------------------------
+
+When you have the Base URL **https://www.example.com/ci-blog/** and imagine the following URL::
+
+    https://www.example.com/ci-blog/blog/news/2022/10?page=2
+
+We use the following terms:
+
+======== ====================================
+Base URL **https://www.example.com/ci-blog/**
+URI path /ci-blog/blog/news/2022/10
+Route    /blog/news/2022/10
+Query    page=2
+======== ====================================
+
 Removing the index.php file
 ===========================
 

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,12 +362,11 @@ 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.
 
+    For full details, see the :ref:`reverse-routing` and :ref:`using-named-routes`.
+
 .. php:function:: url_is($path)
 
     :param string $path: The path to check the current URI path against.

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' -->