Merge pull request #7201 from kenjis/docs-improve-redirect

docs: improve `redirect()` explanation

Author: kenjis

system/Common.php

@@ -863,7 +863,7 @@ function old(string $key, $default = null, $escape = 'html')
      *
      * If more control is needed, you must use $response->redirect explicitly.
      *
-     * @param string $route
+     * @param string|null $route Route name or Controller::method
      */
     function redirect(?string $route = null): RedirectResponse
     {

system/HTTP/RedirectResponse.php

@@ -24,7 +24,7 @@ class RedirectResponse extends Response
      * Sets the URI to redirect to and, optionally, the HTTP status code to use.
      * If no code is provided it will be automatically determined.
      *
-     * @param string   $uri  The URI to redirect to
+     * @param string   $uri  The URI path (relative to baseURL) to redirect to
      * @param int|null $code HTTP status code
      *
      * @return $this
@@ -44,7 +44,7 @@ public function to(string $uri, ?int $code = null, string $method = 'auto')
      * Sets the URI to redirect to but as a reverse-routed or named route
      * instead of a raw URI.
      *
-     * @param string $route Named route or Controller::method
+     * @param string $route Route name or Controller::method
      *
      * @return $this
      *

system/Router/RouteCollection.php

@@ -1043,7 +1043,7 @@ public function environment(string $env, Closure $callback): RouteCollectionInte
      *      // Equals 'path/$param1/$param2'
      *      reverseRoute('Controller::method', $param1, $param2);
      *
-     * @param string     $search    Named route or Controller::method
+     * @param string     $search    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.
      *

user_guide_src/source/general/common_functions.rst

@@ -317,26 +317,48 @@ Miscellaneous Functions
 
 .. php:function:: redirect(string $route)
 
-    :param  string  $route: The reverse-routed or named route to redirect the user to.
+    :param  string  $route: The route name or Controller::method to redirect the user to.
     :rtype: RedirectResponse
 
     .. important:: When you use this function, an instance of ``RedirectResponse`` must be returned
         in the method of the :doc:`Controller <../incoming/controllers>` or
         the :doc:`Controller Filter <../incoming/filters>`. If you forget to return it,
         no redirection will occur.
 
-    Returns a RedirectResponse instance allowing you to easily create redirects:
+    Returns a RedirectResponse instance allowing you to easily create redirects.
+
+    **Redirect to a URI path**
+
+    When you want to pass a URI path (relative to baseURL), use ``redirect()->to()``:
 
     .. literalinclude:: common_functions/005.php
+        :lines: 2-
 
-    .. note:: ``redirect()->back()`` is not the same as browser "back" button.
-        It takes a visitor to "the last page viewed during the Session" when the Session is available.
-        If the Session hasn’t been loaded, or is otherwise unavailable, then a sanitized version of HTTP_REFERER will be used.
+    **Redirect to a Defined Route**
+
+    When you want to pass a :ref:`route name <using-named-routes>` or Controller::method
+    for :ref:`reverse routing <reverse-routing>`, use ``redirect()->route()``:
+
+    .. literalinclude:: common_functions/013.php
+        :lines: 2-
 
-    When passing an argument into the function, it is treated as a named/reverse-routed route, not a relative/full URI,
+    When passing an argument into the function, it is treated as a route name or
+    Controller::method for reverse routing, not a relative/full URI,
     treating it the same as using ``redirect()->route()``:
 
     .. literalinclude:: common_functions/006.php
+        :lines: 2-
+
+    **Redirect Back**
+
+    When you want to redirect back, use ``redirect()->back()``:
+
+    .. literalinclude:: common_functions/014.php
+        :lines: 2-
+
+    .. note:: ``redirect()->back()`` is not the same as browser "back" button.
+        It takes a visitor to "the last page viewed during the Session" when the Session is available.
+        If the Session hasn’t been loaded, or is otherwise unavailable, then a sanitized version of HTTP_REFERER will be used.
 
 .. php:function:: remove_invisible_characters($str[, $urlEncoded = true])
 

user_guide_src/source/general/common_functions/005.php

@@ -1,22 +1,4 @@
 <?php
 
-// Go back to the previous page
-return redirect()->back();
-
-// Go to specific URI
-return redirect()->to('/admin');
-
-// Go to a named route
-return redirect()->route('named_route');
-
-// Keep the old input values upon redirect so they can be used by the `old()` function
-return redirect()->back()->withInput();
-
-// Set a flash message
-return redirect()->back()->with('foo', 'message');
-
-// Copies all cookies from global response instance
-return redirect()->back()->withCookies();
-
-// Copies all headers from the global response instance
-return redirect()->back()->withHeaders();
+// Go to specific URI path. "admin/home" is the URI path relative to baseURL.
+return redirect()->to('admin/home');

user_guide_src/source/general/common_functions/006.php

@@ -1,4 +1,4 @@
 <?php
 
-// Go to a named/reverse-routed URI
+// Go to a named/reverse-routed URI.
 return redirect('named_route');

user_guide_src/source/general/common_functions/013.php

@@ -0,0 +1,4 @@
+<?php
+
+// Go to a named route. "user_gallery" is the route name, not a URI path.
+return redirect()->route('user_gallery');

user_guide_src/source/general/common_functions/014.php

@@ -0,0 +1,16 @@
+<?php
+
+// Go back to the previous page.
+return redirect()->back();
+
+// Keep the old input values upon redirect so they can be used by the `old()` function.
+return redirect()->back()->withInput();
+
+// Set a flash message.
+return redirect()->back()->with('foo', 'message');
+
+// Copies all cookies from global response instance.
+return redirect()->back()->withCookies();
+
+// Copies all headers from the global response instance.
+return redirect()->back()->withHeaders();

user_guide_src/source/installation/upgrade_4xx.rst

@@ -131,9 +131,11 @@ Helpers
   will be :doc:`../helpers/filesystem_helper` in CI4.
 - `String Helper <https://www.codeigniter.com/userguide3/helpers/string_helper.html>`_ functions
   in CI3 are included in :doc:`../helpers/text_helper` in CI4.
-- In CI4, ``redirect()`` returns a ``RedirectResponse`` instance instead of redirecting and terminating script execution. You must return it.
+- In CI4, ``redirect()`` is completely changed from CI3's.
     - `redirect() Documentation CodeIgniter 3.X <https://codeigniter.com/userguide3/helpers/url_helper.html#redirect>`_
     - `redirect() Documentation CodeIgniter 4.X <../general/common_functions.html#redirect>`_
+    - In CI4, ``redirect()`` returns a ``RedirectResponse`` instance instead of redirecting and terminating script execution. You must return it.
+    - You need to change CI3's ``redirect('login/form')`` to ``return redirect()->to('login/form')``.
 
 Hooks
 =====