Improve and fix the Modifier mechanism

Author: nyamsprod

components/CHANGELOG.md

@@ -15,7 +15,8 @@ All Notable changes to `League\Uri\Components` will be documented in this file
 - `Modifier::normalizeIp` returns the host normalized for IPv6 and IPv4 addresses
 - `Modifier::normalizeHost` returns the host as normalized by the WHATWG algorithm
 - `Modifier::with*` method from the underlying `Uri` object are proxy to improve DX.
-- `Modifier::uri` method which returns the underlying URI object used by the Modifier class.
+- `Modifier::wrap` static method which wraps the underlying URI object used by the Modifier class.
+- `Modifier::unwrap` method which returns the underlying URI object used by the Modifier class.
 - `Modifier::prefixQueryPairs` and `Modifier::prefixQueryParameters` to prefix Query using the pair key or the parameter names
 - `tryNew` named constructor added to all classes to return a new instance on success or `null` on failure.
 - `Query::decoded` the string representation of the component decoded.
@@ -39,6 +40,7 @@ All Notable changes to `League\Uri\Components` will be documented in this file
 - `Modifier::getIdnUriString` use `Modifier::toDisplayString` instead
 - `Modifier::getUriString` use  `Modifier::toString` instead
 - `Modifier::getUri` use `Modifier::uri` instead
+- `Modifier::from` use `Modifier::wrap` instead
 
 ### Removed
 

components/Components/Component.php

@@ -58,7 +58,7 @@ public function getUriComponent(): string
     final protected static function filterUri(WhatWgUrl|Rfc3986Uri|Stringable|string $uri): WhatWgUrl|Rfc3986Uri|UriInterface|Psr7UriInterface
     {
         return match (true) {
-            $uri instanceof Modifier => $uri->uri(),
+            $uri instanceof Modifier => $uri->unwrap(),
             $uri instanceof Psr7UriInterface, $uri instanceof UriInterface => $uri,
             $uri instanceof WhatWgUrl => Uri::new($uri->toAsciiString()),
             default => Uri::new($uri),

components/Components/FragmentDirectives.php

@@ -104,7 +104,7 @@ public static function tryNew(Stringable|string|null $value): ?self
     public static function fromUri(WhatWgUrl|Rfc3986Uri|Stringable|string $uri): self
     {
         if ($uri instanceof Modifier) {
-            $uri = $uri->uri();
+            $uri = $uri->unwrap();
         }
 
         if ($uri instanceof Rfc3986Uri) {

components/Modifier.php

@@ -70,23 +70,19 @@ final public function __construct(protected readonly Rfc3986Uri|WhatWgUrl|Psr7Ur
     {
     }
 
-    /**
-     * @param UriFactoryInterface|null $uriFactory deprecated, will be removed in the next major release
-     */
-    public static function from(Rfc3986Uri|WhatWgUrl|Stringable|string $uri, ?UriFactoryInterface $uriFactory = null): static
+    public static function wrap(Rfc3986Uri|WhatWgUrl|Stringable|string $uri): static
     {
         return new static(match (true) {
             $uri instanceof self => $uri->uri,
             $uri instanceof Psr7UriInterface,
             $uri instanceof UriInterface,
             $uri instanceof Rfc3986Uri,
             $uri instanceof WhatWgUrl => $uri,
-            $uriFactory instanceof UriFactoryInterface => $uriFactory->createUri((string) $uri),  // using UriFactoryInterface is deprecated
             default => Uri::new($uri),
         });
     }
 
-    public function uri(): Rfc3986Uri|WhatWgUrl|Psr7UriInterface|UriInterface
+    public function unwrap(): Rfc3986Uri|WhatWgUrl|Psr7UriInterface|UriInterface
     {
         return $this->uri;
     }
@@ -1151,32 +1147,56 @@ public function getIdnUriString(): string
 
     public function appendFragmentDirectives(FragmentDirectives|Directive|Stringable|string ...$directives): static
     {
-        return $this->withFragment(FragmentDirectives::fromUri($this->uri())->append(...$directives));
+        return $this->withFragment(FragmentDirectives::fromUri($this->unwrap())->append(...$directives));
     }
 
     public function prependFragmentDirectives(FragmentDirectives|Directive|Stringable|string ...$directives): static
     {
-        return $this->withFragment(FragmentDirectives::fromUri($this->uri())->prepend(...$directives));
+        return $this->withFragment(FragmentDirectives::fromUri($this->unwrap())->prepend(...$directives));
     }
 
     public function removeFragmentDirectives(int ...$offset): static
     {
-        return $this->withFragment(FragmentDirectives::fromUri($this->uri())->remove(...$offset));
+        return $this->withFragment(FragmentDirectives::fromUri($this->unwrap())->remove(...$offset));
     }
 
     public function replaceFragmentDirective(int $offset, Directive|Stringable|string $directive): static
     {
-        return $this->withFragment(FragmentDirectives::fromUri($this->uri())->replace($offset, $directive));
+        return $this->withFragment(FragmentDirectives::fromUri($this->unwrap())->replace($offset, $directive));
     }
 
     public function sliceFragmentDirectives(int $offset, ?int $length): static
     {
-        return $this->withFragment(FragmentDirectives::fromUri($this->uri())->slice($offset, $length));
+        return $this->withFragment(FragmentDirectives::fromUri($this->unwrap())->slice($offset, $length));
     }
 
     public function filterFragmentDirectives(callable $callback): static
     {
-        return $this->withFragment(FragmentDirectives::fromUri($this->uri())->filter($callback));
+        return $this->withFragment(FragmentDirectives::fromUri($this->unwrap())->filter($callback));
+    }
+
+
+    /**
+     * DEPRECATION WARNING! This method will be removed in the next major point release.
+     *
+     * @deprecated Since version 7.6.0
+     * @codeCoverageIgnore
+     * @see Modifier::wrap()
+     *
+     * @param UriFactoryInterface|null $uriFactory deprecated, will be removed in the next major release
+     */
+    #[Deprecated(message:'use League\Uri\Modifier::wrap() instead', since:'league/uri-components:7.6.0')]
+    public static function from(Rfc3986Uri|WhatWgUrl|Stringable|string $uri, ?UriFactoryInterface $uriFactory = null): static
+    {
+        return new static(match (true) {
+            $uri instanceof self => $uri->uri,
+            $uri instanceof Psr7UriInterface,
+            $uri instanceof UriInterface,
+            $uri instanceof Rfc3986Uri,
+            $uri instanceof WhatWgUrl => $uri,
+            $uriFactory instanceof UriFactoryInterface => $uriFactory->createUri((string) $uri),  // using UriFactoryInterface is deprecated
+            default => Uri::new($uri),
+        });
     }
 
     /**
@@ -1247,7 +1267,7 @@ public function removeQueryPairs(string ...$keys): static
      *
      * @deprecated Since version 7.6.0
      * @codeCoverageIgnore
-     * @see Modifier::uri()
+     * @see Modifier::unwrap()
      *
      * Remove query data according to their key name.
      */