docs: improve redirect() explanation

Author: kenjis

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();