refactor(http): align URI query helpers with add semantics

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

Author: memleakd

system/HTTP/URI.php

@@ -876,49 +876,37 @@ public function addQuery(string $key, $value = null)
     }
 
     /**
-     * Return an instance with one query var added, replaced, or removed.
+     * Return an instance with one query var added or replaced.
      *
      * Note: Method not in PSR-7
      *
-     * @param int|string|null $value Null removes the query var.
+     * @param int|string|null $value
      *
      * @return static
      */
-    public function withQueryVar(string $key, $value)
+    public function withAddedQueryVar(string $key, $value)
     {
         $uri = clone $this;
 
-        if ($value === null) {
-            unset($uri->query[$key]);
-
-            return $uri;
-        }
-
         $uri->query[$key] = $value;
 
         return $uri;
     }
 
     /**
-     * Return an instance with multiple query vars added, replaced, or removed.
+     * Return an instance with multiple query vars added or replaced.
      *
      * Note: Method not in PSR-7
      *
-     * @param array<string, int|string|null> $params Null values remove query vars.
+     * @param array<string, int|string|null> $params
      *
      * @return static
      */
-    public function withQueryVars(array $params)
+    public function withAddedQueryVars(array $params)
     {
         $uri = clone $this;
 
         foreach ($params as $key => $value) {
-            if ($value === null) {
-                unset($uri->query[$key]);
-
-                continue;
-            }
-
             $uri->query[$key] = $value;
         }
 

tests/system/HTTP/URITest.php

@@ -835,62 +835,50 @@ public function testAddQueryVarRespectsExistingQueryVars(): void
         $this->assertSame('http://example.com/foo?bar=baz&baz=foz', (string) $uri);
     }
 
-    public function testWithQueryVarAddsQueryVarWithoutMutatingOriginal(): void
+    public function testWithAddedQueryVarAddsQueryVarWithoutMutatingOriginal(): void
     {
         $base = 'http://example.com/foo';
         $uri  = new URI($base);
 
-        $new = $uri->withQueryVar('bar', 'baz');
+        $new = $uri->withAddedQueryVar('bar', 'baz');
 
         $this->assertSame('http://example.com/foo?bar=baz', (string) $new);
         $this->assertSame('http://example.com/foo', (string) $uri);
     }
 
-    public function testWithQueryVarReplacesQueryVarAndPreservesFragment(): void
+    public function testWithAddedQueryVarReplacesQueryVarAndPreservesFragment(): void
     {
         $base = 'http://example.com/foo?bar=baz#section';
         $uri  = new URI($base);
 
-        $new = $uri->withQueryVar('bar', 'foz');
+        $new = $uri->withAddedQueryVar('bar', 'foz');
 
         $this->assertSame('http://example.com/foo?bar=foz#section', (string) $new);
         $this->assertSame('http://example.com/foo?bar=baz#section', (string) $uri);
     }
 
-    public function testWithQueryVarRemovesQueryVarWhenValueIsNull(): void
-    {
-        $base = 'http://example.com/foo?foo=bar&bar=baz&baz=foz';
-        $uri  = new URI($base);
-
-        $new = $uri->withQueryVar('bar', null);
-
-        $this->assertSame('http://example.com/foo?foo=bar&baz=foz', (string) $new);
-        $this->assertSame('http://example.com/foo?foo=bar&bar=baz&baz=foz', (string) $uri);
-    }
-
-    public function testWithQueryVarKeepsEmptyStringQueryVar(): void
+    public function testWithAddedQueryVarKeepsEmptyStringQueryVar(): void
     {
         $base = 'http://example.com/foo?bar=baz';
         $uri  = new URI($base);
 
-        $new = $uri->withQueryVar('bar', '');
+        $new = $uri->withAddedQueryVar('bar', '');
 
         $this->assertSame('http://example.com/foo?bar=', (string) $new);
         $this->assertSame('http://example.com/foo?bar=baz', (string) $uri);
     }
 
-    public function testWithQueryVarsAddsReplacesAndRemovesWithoutMutatingOriginal(): void
+    public function testWithAddedQueryVarsAddsAndReplacesWithoutMutatingOriginal(): void
     {
         $base = 'http://example.com/foo?foo=bar&bar=baz&baz=foz#section';
         $uri  = new URI($base);
 
-        $new = $uri->withQueryVars([
-            'bar' => null,
+        $new = $uri->withAddedQueryVars([
             'baz' => 'updated',
             'new' => 'value',
         ]);
 
-        $this->assertSame('http://example.com/foo?foo=bar&baz=updated&new=value#section', (string) $new);
+        $this->assertSame('http://example.com/foo?foo=bar&bar=baz&baz=updated&new=value#section', (string) $new);
         $this->assertSame('http://example.com/foo?foo=bar&bar=baz&baz=foz#section', (string) $uri);
     }
 

user_guide_src/source/changelogs/v4.8.0.rst

@@ -276,7 +276,7 @@ HTTP
 - ``CLIRequest`` now supports options with values specified using an equals sign (e.g., ``--option=value``) in addition to the existing space-separated syntax (e.g., ``--option value``).
   This provides more flexibility in how you can pass options to CLI requests.
 - Added ``$enableStyleNonce`` and ``$enableScriptNonce`` options to ``Config\App`` to automatically add nonces to control whether to add nonces to style-* and script-* directives in the Content Security Policy (CSP) header when CSP is enabled. See :ref:`csp-control-nonce-generation` for details.
-- Added ``URI::withQueryVar()`` and ``URI::withQueryVars()`` to return a cloned URI with query variables added, replaced, or removed.
+- Added ``URI::withAddedQueryVar()`` and ``URI::withAddedQueryVars()`` to return a cloned URI with query variables added or replaced.
 - ``URI`` now accepts an optional boolean second parameter in the constructor, defaulting to ``false``, to control how the query string is parsed in instantiation.
   This is the behavior of ``->useRawQueryString()`` brought into the constructor for convenience. Previously, you need to call ``$uri->useRawQueryString(true)->setURI($uri)`` to get this behavior.
   Now you can simply do ``new URI($uri, true)``.

user_guide_src/source/libraries/uri.rst

@@ -193,9 +193,9 @@ Changing Query Values Without Mutation
 
 .. versionadded:: 4.8.0
 
-You can return a new URI instance with one or more query variables changed by using the ``withQueryVar()``
-and ``withQueryVars()`` methods. Existing query variables are preserved unless they are replaced or removed.
-Passing ``null`` removes a query variable:
+You can return a new URI instance with one or more query variables added or replaced by using the
+``withAddedQueryVar()`` and ``withAddedQueryVars()`` methods. Existing query variables are preserved unless they
+are replaced:
 
 .. literalinclude:: uri/028.php
 

user_guide_src/source/libraries/uri/028.php

@@ -2,15 +2,12 @@
 
 $uri = new \CodeIgniter\HTTP\URI('https://example.com/users?q=bob&page=1');
 
-$nextPage = $uri->withQueryVar('page', 2);
+$nextPage = $uri->withAddedQueryVar('page', 2);
 // https://example.com/users?q=bob&page=2
 
-$withoutSearch = $uri->withQueryVar('q', null);
-// https://example.com/users?page=1
-
-$filtered = $uri->withQueryVars([
-    'q'    => null,
+$filtered = $uri->withAddedQueryVars([
+    'q'    => 'alice',
     'page' => 1,
     'role' => 'admin',
 ]);
-// https://example.com/users?page=1&role=admin
+// https://example.com/users?q=alice&page=1&role=admin