docs(uri): clarify mutable query alternatives (#10348)

- add a user guide table mapping mutable query methods to immutable helpers
- note that immutable query helpers clone the URI instead of mutating it
- add TODO notes for future mutable query method deprecations

Signed-off-by: memleakd <121398829+memleakd@users.noreply.github.com>

Author: memleakd

system/HTTP/URI.php

@@ -817,6 +817,8 @@ protected function refreshPath(): self
      * to clean the various parts of the query keys and values.
      *
      * @return $this
+     *
+     * @TODO Deprecated in the next major version. Use withQuery() instead for immutability.
      */
     public function setQuery(string $query)
     {
@@ -859,6 +861,8 @@ public function withQuery(string $query): static
      * portion of the URI.
      *
      * @return $this
+     *
+     * @TODO Deprecated in the next major version. Use withQueryArray() instead for immutability.
      */
     public function setQueryArray(array $query)
     {
@@ -891,6 +895,8 @@ public function withQueryArray(array $query): static
      * @param int|string|null $value
      *
      * @return $this
+     *
+     * @TODO Deprecated in the next major version. Use withQueryVar() or withQueryVars() instead for immutability.
      */
     public function addQuery(string $key, $value = null)
     {
@@ -939,6 +945,8 @@ public function withQueryVars(array $params): static
      * @param string ...$params
      *
      * @return $this
+     *
+     * @TODO Deprecated in the next major version. Use withoutQueryVars() instead for immutability.
      */
     public function stripQuery(...$params)
     {
@@ -972,6 +980,8 @@ public function withoutQueryVars(string ...$params): static
      * @param string ...$params
      *
      * @return $this
+     *
+     * @TODO Deprecated in the next major version. Use withOnlyQueryVars() instead for immutability.
      */
     public function keepQuery(...$params)
     {

user_guide_src/source/libraries/uri.rst

@@ -193,6 +193,25 @@ Changing Query Values Without Mutation
 
 .. versionadded:: 4.8.0
 
+The immutable query methods provide alternatives to the older mutable methods:
+
++-----------------------+--------------------------------------------+
+| Mutable method        | Immutable alternative                      |
++=======================+============================================+
+| ``setQuery()``        | ``withQuery()``                            |
++-----------------------+--------------------------------------------+
+| ``setQueryArray()``   | ``withQueryArray()``                       |
++-----------------------+--------------------------------------------+
+| ``addQuery()``        | ``withQueryVar()`` / ``withQueryVars()``   |
++-----------------------+--------------------------------------------+
+| ``stripQuery()``      | ``withoutQueryVars()``                     |
++-----------------------+--------------------------------------------+
+| ``keepQuery()``       | ``withOnlyQueryVars()``                    |
++-----------------------+--------------------------------------------+
+
+The ``with*()`` methods return a cloned URI instance and do not modify the original URI.
+The older mutable methods change the current URI instance.
+
 You can return a new URI instance with its query variables replaced by using the
 ``withQuery()`` and ``withQueryArray()`` methods:
 
@@ -204,13 +223,11 @@ are replaced:
 
 .. literalinclude:: uri/028.php
 
-You can also return a new URI instance with query variables removed or filtered by using the
+You can return a new URI instance with query variables removed or filtered by using the
 ``withoutQueryVars()`` and ``withOnlyQueryVars()`` methods:
 
 .. literalinclude:: uri/030.php
 
-The original URI instance is not modified.
-
 Filtering Query Values
 ^^^^^^^^^^^^^^^^^^^^^^