docs: add docs

Author: kenjis

user_guide_src/source/changelogs/v4.3.4.rst

@@ -12,6 +12,29 @@ Release Date: Unreleased
 BREAKING
 ********
 
+Behavior Changes
+================
+
+.. _v434-redirect-status-code:
+
+Redirect Status Code
+--------------------
+
+- Due to a bug, in previous versions, when using HTTP/1.1 or later the status
+  code of the actual redirect response might be changed even if a status code was
+  specified. For example, for a GET request, 302 would change to 307; for a POST
+  request, 307 and 302 would change to 303.
+- Starting with this version, if you specify a status code in
+  :ref:`redirect <response-redirect-status-code>`, that code will always be used
+  in the response.
+- The default code for GET requests has been corrected from 307 to 302 when using
+  HTTP/1.1 or later.
+- The default code for HEAD and OPTIONS requests has been corrected from 303 to
+  307 when using HTTP/1.1 or later.
+- In ``$routes->addRedirect()``, 302 is specified by default. Therefor 302 will
+  always be used when you don't specify a status code. In previous versions,
+  302 might be changed.
+
 Message Changes
 ***************
 

user_guide_src/source/installation/upgrade_434.rst

@@ -18,6 +18,13 @@ Mandatory File Changes
 Breaking Changes
 ****************
 
+Redirect Status Code
+====================
+
+- Due to a bug fix, the status codes of redirects may be changed. See
+  :ref:`ChangeLog v4.3.4 <v434-redirect-status-code>` and if the code is not
+  what you want, :ref:`specify status codes <response-redirect-status-code>`.
+
 Breaking Enhancements
 *********************
 

user_guide_src/source/outgoing/response.rst

@@ -109,6 +109,26 @@ When you want to redirect back, use ``redirect()->back()``:
     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.
 
+.. _response-redirect-status-code:
+
+Redirect Status Code
+--------------------
+
+The default HTTP status code for GET requests is 302. However, when using HTTP/1.1
+or later, 303 is used for POST/PUT/DELETE requests and 307 for all other requests.
+
+You can specify the status code:
+
+.. literalinclude:: ./response/032.php
+    :lines: 2-
+
+.. note:: Due to a bug, in v4.3.3 or previous versions, the status code of the
+    actual redirect response might be changed even if a status code was specified.
+    See :ref:`ChangeLog v4.3.4 <v434-redirect-status-code>`.
+
+If you don't know HTTP status code for redirection, it is recommended to read
+`Redirections in HTTP <https://developer.mozilla.org/en-US/docs/Web/HTTP/Redirections>`_.
+
 .. _force-file-download:
 
 Force File Download

user_guide_src/source/outgoing/response/032.php

@@ -0,0 +1,10 @@
+<?php
+
+// Redirect to a URI path relative to baseURL with status code 301.
+return redirect()->to('admin/home', 301);
+
+// Redirect to a route with status code 308.
+return redirect()->route('user_gallery', [], 308);
+
+// Redirect back with status code 302.
+return redirect()->back(302);