docs: update user guide

Author: kenjis

user_guide_src/source/changelogs/v4.4.0.rst

@@ -72,6 +72,46 @@ CodeIgniter and exit()
 The ``CodeIgniter::run()`` method no longer calls ``exit(EXIT_SUCCESS)``. The
 exit call is moved to **public/index.php**.
 
+.. _v440-site-uri-changes:
+
+Site URI Changes
+================
+
+A new ``SiteURI`` class that extends the ``URI`` class and represents the site
+URI has been added, and now it is used in many places that need the current URI.
+
+``$this->request->getUri()`` in controllers returns the ``SiteURI`` instance.
+Also, :php:func:`site_url()`, :php:func:`base_url()`, and :php:func:`current_url()`
+use the SiteURI internally.
+
+getPath()
+---------
+
+The ``getPath()`` method now always returns the full URI path with leading ``/``.
+Therefore, when your baseURL has sub-directories and you want to get the relative
+path to baseURL, you must use the new ``getRoutePath()`` method instead.
+
+For example::
+
+            baseURL: http://localhost:8888/CodeIgniter4/
+    The current URI: http://localhost:8888/CodeIgniter4/foo/bar
+          getPath(): /CodeIgniter4/foo/bar
+     getRoutePath(): foo/bar
+
+Site URI Values
+---------------
+
+The SiteURI class normalizes site URIs more strictly than before, and some bugs
+have been fixed.
+
+As a result, the framework may return site URIs or the URI paths slightly differently
+than in previous versions.
+For example, ``/`` will be added after ``index.php``::
+
+    http://example.com/test/index.php?page=1
+    ↓
+    http://example.com/test/index.php/?page=1
+
 .. _v440-interface-changes:
 
 Interface Changes
@@ -192,6 +232,8 @@ Libraries
   the value of the `full_path` index of the file if it was uploaded via directory upload.
 - **CURLRequest:** Added a request option ``proxy``. See
   :ref:`CURLRequest Class <curlrequest-request-options-proxy>`.
+- **URI:** A new ``SiteURI`` class that extends ``URI`` and represents the site
+  URI has been added.
 
 Helpers and Functions
 =====================

user_guide_src/source/incoming/incomingrequest.rst

@@ -228,11 +228,10 @@ The object gives you full abilities to grab any part of the request on it's own:
 
 .. literalinclude:: incomingrequest/021.php
 
-You can work with the current URI string (the path relative to your baseURL) using the ``getPath()`` and ``setPath()`` methods.
-Note that this relative path on the shared instance of ``IncomingRequest`` is what the :doc:`URL Helper </helpers/url_helper>`
-functions use, so this is a helpful way to "spoof" an incoming request for testing:
+You can work with the current URI string (the path relative to your baseURL) using the ``getRoutePath()``.
 
-.. literalinclude:: incomingrequest/022.php
+.. note:: The ``getRoutePath()`` method can be used since v4.4.0. Prior to v4.4.0,
+    the ``getPath()`` method returned the path relative to your baseURL.
 
 Uploaded Files
 **************
@@ -476,15 +475,22 @@ The methods provided by the parent classes that are available are:
         :returns:        The current URI path relative to baseURL
         :rtype:    string
 
-        This is the safest method to determine the "current URI", since ``IncomingRequest::$uri``
-        may not be aware of the complete App configuration for base URLs.
+        This method returns the current URI path relative to baseURL.
+
+        .. note:: Prior to v4.4.0, this was the safest method to determine the
+            "current URI", since ``IncomingRequest::$uri`` might not be aware of
+            the complete App configuration for base URLs.
 
     .. php:method:: setPath($path)
 
+        .. deprecated:: 4.4.0
+
         :param    string    $path: The relative path to use as the current URI
         :returns:        This Incoming Request
         :rtype:    IncomingRequest
 
-        Used mostly just for testing purposes, this allows you to set the relative path
-        value for the current request instead of relying on URI detection. This will also
-        update the underlying ``URI`` instance with the new path.
+        .. note:: Prior to v4.4.0, used mostly just for testing purposes, this
+            allowed you to set the relative path value for the current request
+            instead of relying on URI detection. This also updated the
+            underlying ``URI`` instance with the new path.
+

user_guide_src/source/incoming/incomingrequest/021.php

@@ -7,7 +7,8 @@
 echo $uri->getUserInfo();       // snoopy:password
 echo $uri->getHost();           // example.com
 echo $uri->getPort();           // 88
-echo $uri->getPath();           // path/to/page
+echo $uri->getPath();           // /path/to/page
+echo $uri->getRoutePath();      // path/to/page
 echo $uri->getQuery();          // foo=bar&bar=baz
 print_r($uri->getSegments());   // Array ( [0] => path [1] => to [2] => page )
 echo $uri->getSegment(1);       // path

user_guide_src/source/incoming/incomingrequest/022.php

@@ -47,6 +47,15 @@ If your code depends on this bug, fix the segment number.
 .. literalinclude:: upgrade_440/002.php
    :lines: 2-
 
+Site URI Changes
+================
+
+When your baseURL has sub-directories and you get the relative path to baseURL of
+the current URI by the ``URI::getPath()`` method, you must use the new
+``SiteURI::getRoutePath()`` method instead.
+
+See :ref:`v440-site-uri-changes` for details.
+
 When You Extend Exceptions
 ==========================
 

user_guide_src/source/installation/upgrade_440.rst

@@ -14,34 +14,47 @@ relative URI to an existing one and have it resolved safely and correctly.
 Creating URI instances
 ======================
 
-Creating a URI instance is as simple as creating a new class instance:
+Creating a URI instance is as simple as creating a new class instance.
+
+When you create the new instance, you can pass a full or partial URL in the constructor and it will be parsed
+into its appropriate sections:
 
 .. literalinclude:: uri/001.php
+    :lines: 2-
 
-Alternatively, you can use the ``service()`` function to return an instance for you:
+Alternatively, you can use the :php:func:`service()` function to return an instance for you:
 
-.. literalinclude:: uri/002.php
+.. literalinclude:: uri/003.php
+    :lines: 2-
 
-When you create the new instance, you can pass a full or partial URL in the constructor and it will be parsed
-into its appropriate sections:
+Since v4.4.0, if you don't pass a URL, it returns the current URI:
 
-.. literalinclude:: uri/003.php
+.. literalinclude:: uri/002.php
+    :lines: 2-
+
+.. note:: The above code returns the ``SiteURI`` instance, that extends the ``URI``
+    class. The ``URI`` class is for general URIs, but the ``SiteURI`` class is
+    for your site URIs.
 
 The Current URI
 ---------------
 
 Many times, all you really want is an object representing the current URL of this request.
-You can use one of the functions available in the :doc:`../helpers/url_helper`:
+You can use the :php:func:`current_url()` function available in the :doc:`../helpers/url_helper`:
 
 .. literalinclude:: uri/004.php
+    :lines: 2-
 
 You must pass ``true`` as the first parameter, otherwise, it will return the string representation of the current URL.
 
 This URI is based on the path (relative to your ``baseURL``) as determined by the current request object and
 your settings in ``Config\App`` (``baseURL``, ``indexPage``, and ``forceGlobalSecureRequests``).
-Assuming that you're in a controller that extends ``CodeIgniter\Controller`` you can get this relative path:
+
+Assuming that you're in a controller that extends ``CodeIgniter\Controller``, you
+can also get the current SiteURI instance:
 
 .. literalinclude:: uri/005.php
+    :lines: 2-
 
 ===========
 URI Strings
@@ -136,6 +149,10 @@ can be used to manipulate it:
 .. note:: When setting the path this way, or any other way the class allows, it is sanitized to encode any dangerous
     characters, and remove dot segments for safety.
 
+.. note:: Since v4.4.0, the ``SiteURI::getRoutePath()`` method,
+    returns the URI path relative to baseURL, and the ``SiteURI::getPath()``
+    method always returns the full URI path with leading ``/``.
+
 Query
 -----
 

user_guide_src/source/libraries/uri.rst

@@ -1,3 +1,3 @@
 <?php
 
-$uri = new \CodeIgniter\HTTP\URI();
+$uri = new \CodeIgniter\HTTP\URI('http://www.example.com/some/path');

user_guide_src/source/libraries/uri/001.php

@@ -1,3 +1,3 @@
 <?php
 
-$uri = service('uri');
+$uri = service('uri'); // returns the current SiteURI instance.

user_guide_src/source/libraries/uri/002.php

@@ -1,4 +1,3 @@
 <?php
 
-$uri = new \CodeIgniter\HTTP\URI('http://www.example.com/some/path');
 $uri = service('uri', 'http://www.example.com/some/path');

user_guide_src/source/libraries/uri/003.php

@@ -1,3 +1,3 @@
 <?php
 
-$path = $this->request->getPath();
+$uri = $this->request->getUri();