feat: add URI::withScheme() and deprecate URI::setScheme()

Author: kenjis

system/HTTP/URI.php

@@ -14,6 +14,7 @@
 use BadMethodCallException;
 use CodeIgniter\HTTP\Exceptions\HTTPException;
 use Config\App;
+use InvalidArgumentException;
 
 /**
  * Abstraction for a uniform resource identifier (URI).
@@ -709,7 +710,7 @@ public function setAuthority(string $str)
      *
      * @return $this
      *
-     * @TODO PSR-7: Should be `withScheme($scheme)`.
+     * @deprecated Use `withScheme()` instead.
      */
     public function setScheme(string $str)
     {
@@ -719,6 +720,34 @@ public function setScheme(string $str)
         return $this;
     }
 
+    /**
+     * Return an instance with the specified scheme.
+     *
+     * This method MUST retain the state of the current instance, and return
+     * an instance that contains the specified scheme.
+     *
+     * Implementations MUST support the schemes "http" and "https" case
+     * insensitively, and MAY accommodate other schemes if required.
+     *
+     * An empty scheme is equivalent to removing the scheme.
+     *
+     * @param string $scheme The scheme to use with the new instance.
+     *
+     * @return static A new instance with the specified scheme.
+     *
+     * @throws InvalidArgumentException for invalid or unsupported schemes.
+     */
+    public function withScheme(string $scheme)
+    {
+        $uri = clone $this;
+
+        $scheme = strtolower($scheme);
+
+        $uri->scheme = preg_replace('#:(//)?$#', '', $scheme);
+
+        return $uri;
+    }
+
     /**
      * Sets the userInfo/Authority portion of the URI.
      *

tests/system/HTTP/URITest.php

@@ -240,6 +240,44 @@ public function testSetSchemeSetsValue()
         $this->assertSame($expected, (string) $uri);
     }
 
+    public function testWithScheme()
+    {
+        $url = 'example.com';
+        $uri = new URI('http://' . $url);
+
+        $new = $uri->withScheme('x');
+
+        $this->assertSame('x://' . $url, (string) $new);
+        $this->assertSame('http://' . $url, (string) $uri);
+    }
+
+    public function testWithSchemeSetsHttps()
+    {
+        $url = 'http://example.com/path';
+        $uri = new URI($url);
+
+        $new = $uri->withScheme('https');
+
+        $this->assertSame('https', $new->getScheme());
+        $this->assertSame('http', $uri->getScheme());
+
+        $expected = 'https://example.com/path';
+        $this->assertSame($expected, (string) $new);
+        $expected = 'http://example.com/path';
+        $this->assertSame($expected, (string) $uri);
+    }
+
+    public function testWithSchemeSetsEmpty()
+    {
+        $url = 'example.com';
+        $uri = new URI('http://' . $url);
+
+        $new = $uri->withScheme('');
+
+        $this->assertSame($url, (string) $new);
+        $this->assertSame('http://' . $url, (string) $uri);
+    }
+
     public function testSetUserInfoSetsValue()
     {
         $url = 'http://example.com/path';

user_guide_src/source/changelogs/v4.4.0.rst

@@ -216,7 +216,9 @@ Deprecations
   ``$tokenName``, ``$headerName``, ``$expires``, ``$regenerate``, and
   ``$redirect`` in ``Security`` are deprecated, and no longer used. Use
   ``$config`` instead.
-- **URI:** ``URI::setSilent()`` is deprecated.
+- **URI:**
+    - ``URI::setSilent()`` is deprecated.
+    - ``URI::setScheme()`` is deprecated. Use ``withScheme()`` instead.
 
 Bugs Fixed
 **********