From c770ccb2c28da24ce027c6450e241b2a92ce02f7 Mon Sep 17 00:00:00 2001 From: kenjis Date: Tue, 5 Jul 2022 16:25:30 +0900 Subject: [PATCH 1/5] docs: remove unnecessary spaces --- .../source/general/common_functions.rst | 52 +++++++++---------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/user_guide_src/source/general/common_functions.rst b/user_guide_src/source/general/common_functions.rst index 4b8ef4e92cc2..89a4b8183565 100755 --- a/user_guide_src/source/general/common_functions.rst +++ b/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,7 +99,7 @@ Service Accessors For more information, see the :doc:`Localization ` page. -.. php:function:: model($name [, $getShared = true [, &$conn = null ]]) +.. php:function:: model($name[, $getShared = true[, &$conn = null]]) :param string $name: :param boolean $getShared: @@ -107,7 +107,7 @@ Service Accessors :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 `, 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 ` 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 ` 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,14 +189,14 @@ 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 @@ -204,7 +204,7 @@ Miscellaneous Functions 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 @@ -212,28 +212,28 @@ Miscellaneous Functions 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 -.. 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 -.. 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 ` 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,7 +326,7 @@ 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. @@ -338,7 +338,7 @@ Miscellaneous Functions For full details, see the :doc:`/incoming/routing` page. -.. php:function:: service ( $name [, ...$params] ) +.. 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 +353,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 +372,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) From 6b12ab82c45d1094b1f69fcd45b8c3b5721e712a Mon Sep 17 00:00:00 2001 From: kenjis Date: Tue, 5 Jul 2022 16:36:28 +0900 Subject: [PATCH 2/5] docs: fix PHPDocs --- system/Common.php | 3 ++- system/Helpers/url_helper.php | 3 ++- system/Router/RouteCollection.php | 3 ++- system/Router/RouteCollectionInterface.php | 3 ++- 4 files changed, 8 insertions(+), 4 deletions(-) diff --git a/system/Common.php b/system/Common.php index 140dd750d5dc..962483bb68b2 100644 --- a/system/Common.php +++ b/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 */ diff --git a/system/Helpers/url_helper.php b/system/Helpers/url_helper.php index 8efd11c1ea6a..a533f5240f7a 100644 --- a/system/Helpers/url_helper.php +++ b/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 */ diff --git a/system/Router/RouteCollection.php b/system/Router/RouteCollection.php index c1e093c2380f..66a950e72fee 100644 --- a/system/Router/RouteCollection.php +++ b/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 */ diff --git a/system/Router/RouteCollectionInterface.php b/system/Router/RouteCollectionInterface.php index e5e4350a5db6..b12de34b5d94 100644 --- a/system/Router/RouteCollectionInterface.php +++ b/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 */ From b2524392494d9171ec15473709741ee0a8c3ab47 Mon Sep 17 00:00:00 2001 From: kenjis Date: Tue, 5 Jul 2022 17:48:32 +0900 Subject: [PATCH 3/5] docs: improve route_to() and url_to() --- .../source/general/common_functions.rst | 6 +++--- user_guide_src/source/helpers/url_helper.rst | 7 ++----- user_guide_src/source/helpers/url_helper/021.php | 9 ++++++++- user_guide_src/source/helpers/url_helper/022.php | 8 +++++++- user_guide_src/source/incoming/routing.rst | 16 +++++++++++++++- user_guide_src/source/incoming/routing/029.php | 2 +- user_guide_src/source/incoming/routing/030.php | 2 +- 7 files changed, 37 insertions(+), 13 deletions(-) diff --git a/user_guide_src/source/general/common_functions.rst b/user_guide_src/source/general/common_functions.rst index 89a4b8183565..70be37346c75 100755 --- a/user_guide_src/source/general/common_functions.rst +++ b/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]) diff --git a/user_guide_src/source/helpers/url_helper.rst b/user_guide_src/source/helpers/url_helper.rst index c7aff69cb86a..76265f1196e0 100644 --- a/user_guide_src/source/helpers/url_helper.rst +++ b/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. diff --git a/user_guide_src/source/helpers/url_helper/021.php b/user_guide_src/source/helpers/url_helper/021.php index 64f4916d018e..80a8db751da1 100644 --- a/user_guide_src/source/helpers/url_helper/021.php +++ b/user_guide_src/source/helpers/url_helper/021.php @@ -1,3 +1,10 @@ get('/', 'Home::index'); + +?> + +Home + + diff --git a/user_guide_src/source/helpers/url_helper/022.php b/user_guide_src/source/helpers/url_helper/022.php index ec799947ec72..53bef5e55232 100644 --- a/user_guide_src/source/helpers/url_helper/022.php +++ b/user_guide_src/source/helpers/url_helper/022.php @@ -1,3 +1,9 @@ get('pages/(:segment)', 'Page::index/$1'); + +?> + +Home + diff --git a/user_guide_src/source/incoming/routing.rst b/user_guide_src/source/incoming/routing.rst index 4496057a5247..0f51ae4abe82 100644 --- a/user_guide_src/source/incoming/routing.rst +++ b/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 ========================== diff --git a/user_guide_src/source/incoming/routing/029.php b/user_guide_src/source/incoming/routing/029.php index c1a8d5947cd8..a35ef16016ae 100644 --- a/user_guide_src/source/incoming/routing/029.php +++ b/user_guide_src/source/incoming/routing/029.php @@ -5,6 +5,6 @@ ?> - + View Gallery diff --git a/user_guide_src/source/incoming/routing/030.php b/user_guide_src/source/incoming/routing/030.php index 1c1c629893e3..877dc68195b3 100644 --- a/user_guide_src/source/incoming/routing/030.php +++ b/user_guide_src/source/incoming/routing/030.php @@ -5,6 +5,6 @@ ?> - + View Gallery From 6414095588bcda87135e989bf5cfcccedabd4867 Mon Sep 17 00:00:00 2001 From: kenjis Date: Wed, 6 Jul 2022 08:45:14 +0900 Subject: [PATCH 4/5] docs: add URL Structure and terms --- user_guide_src/source/general/urls.rst | 37 +++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/user_guide_src/source/general/urls.rst b/user_guide_src/source/general/urls.rst index 252a907358dd..56a57fcc51a6 100644 --- a/user_guide_src/source/general/urls.rst +++ b/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 ` 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 =========================== From c068a79b6d2b2cad9d76fd733e2d7c91ef426600 Mon Sep 17 00:00:00 2001 From: kenjis Date: Wed, 6 Jul 2022 09:18:03 +0900 Subject: [PATCH 5/5] docs: update explanation about route_to() and url_to() --- user_guide_src/source/general/common_functions.rst | 10 ++++++++-- .../source/general/common_functions/009.php | 12 ++++++++++++ .../source/general/common_functions/010.php | 12 ++++++++++++ user_guide_src/source/helpers/url_helper.rst | 2 ++ user_guide_src/source/incoming/routing.rst | 14 ++------------ user_guide_src/source/incoming/routing/029.php | 6 +++--- user_guide_src/source/incoming/routing/030.php | 6 +++--- 7 files changed, 42 insertions(+), 20 deletions(-) create mode 100644 user_guide_src/source/general/common_functions/009.php create mode 100644 user_guide_src/source/general/common_functions/010.php diff --git a/user_guide_src/source/general/common_functions.rst b/user_guide_src/source/general/common_functions.rst index 70be37346c75..c73b8f72bf37 100755 --- a/user_guide_src/source/general/common_functions.rst +++ b/user_guide_src/source/general/common_functions.rst @@ -333,10 +333,16 @@ Miscellaneous Functions .. note:: This function requires the controller/method to have a route defined in **app/Config/routes.php**. - Generates a URI path (route) 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 :ref:`reverse-routing` and :ref:`using-named-routes`. + .. literalinclude:: common_functions/009.php + + .. 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]) diff --git a/user_guide_src/source/general/common_functions/009.php b/user_guide_src/source/general/common_functions/009.php new file mode 100644 index 000000000000..41c725478d3f --- /dev/null +++ b/user_guide_src/source/general/common_functions/009.php @@ -0,0 +1,12 @@ +get('users/(:num)/gallery(:any)', 'Galleries::showUserGallery/$1/$2'); + +?> + +get('users/(:num)/gallery(:any)', 'Galleries::showUserGallery/$1/$2', ['as' => 'user_gallery']); + +?> + + - -View Gallery - + +View Gallery + diff --git a/user_guide_src/source/incoming/routing/030.php b/user_guide_src/source/incoming/routing/030.php index 877dc68195b3..b17465e4f88b 100644 --- a/user_guide_src/source/incoming/routing/030.php +++ b/user_guide_src/source/incoming/routing/030.php @@ -5,6 +5,6 @@ ?> - -View Gallery - + +View Gallery +