Adding the Conditionable interface

components/Components/Component.php

@@ -13,6 +13,7 @@
 
 namespace League\Uri\Components;
 
+use League\Uri\Contracts\Conditionable;
 use League\Uri\Contracts\UriAccess;
 use League\Uri\Contracts\UriComponentInterface;
 use League\Uri\Contracts\UriInterface;
@@ -26,7 +27,7 @@
 use function preg_match;
 use function sprintf;
 
-abstract class Component implements UriComponentInterface
+abstract class Component implements UriComponentInterface, Conditionable
 {
     protected const REGEXP_INVALID_URI_CHARS = '/[\x00-\x1f\x7f]/';
 
@@ -84,14 +85,6 @@ final protected static function filterComponent(Stringable|int|string|null $comp
         };
     }
 
-    /**
-     * Apply the callback if the given "condition" is (or resolves to) true.
-     *
-     * @param (callable($this): bool)|bool $condition
-     * @param callable($this): (static|null) $onSuccess
-     * @param ?callable($this): (static|null) $onFail
-     *
-     */
     final public function when(callable|bool $condition, callable $onSuccess, ?callable $onFail = null): static
     {
         if (!is_bool($condition)) {

components/Components/URLSearchParams.php

@@ -19,6 +19,7 @@
 use Deprecated;
 use Iterator;
 use IteratorAggregate;
+use League\Uri\Contracts\Conditionable;
 use League\Uri\Contracts\QueryInterface;
 use League\Uri\Contracts\UriComponentInterface;
 use League\Uri\Contracts\UriException;
@@ -503,7 +504,7 @@ public function delete(?string $name): void
     /**
      * Sorts all key/value pairs contained in this object in place and returns undefined.
      *
-     * The sort order is according to unicode code points of the keys. This method
+     * The sort order is according to Unicode code points of the keys. This method
      * uses a stable sorting algorithm (i.e. the relative order between
      * key/value pairs with equal keys will be preserved).
      */
@@ -512,24 +513,17 @@ public function sort(): void
         $this->updateQuery($this->pairs->sort());
     }
 
-    /**
-     * Apply the callback if the given "condition" is (or resolves to) true.
-     *
-     * @param (callable($this): bool)|bool $condition
-     * @param callable($this): (self|null) $onSuccess
-     * @param ?callable($this): (self|null) $onFail
-     */
-    public function when(callable|bool $condition, callable $onSuccess, ?callable $onFail = null): self
+    public function when(callable|bool $condition, callable $onSuccess, ?callable $onFail = null): static
     {
         if (!is_bool($condition)) {
             $condition = $condition($this);
         }
 
         return match (true) {
-            $condition => $onSuccess($this),
-            null !== $onFail => $onFail($this),
+            $condition => $onSuccess($this) ?? $this,
+            null !== $onFail => $onFail($this) ?? $this,
             default => $this,
-        } ?? $this;
+        };
     }
 
     /**

components/Modifier.php

@@ -24,6 +24,7 @@
 use League\Uri\Components\Path;
 use League\Uri\Components\Query;
 use League\Uri\Components\UserInfo;
+use League\Uri\Contracts\Conditionable;
 use League\Uri\Contracts\PathInterface;
 use League\Uri\Contracts\UriAccess;
 use League\Uri\Contracts\UriInterface;
@@ -54,7 +55,7 @@
  * @method static withQuery(Stringable|string|null $query) returns a new instance with the specified query.
  * @method static withFragment(Stringable|string|null $fragment) returns a new instance with the specified fragment.
  */
-class Modifier implements Stringable, JsonSerializable, UriAccess
+class Modifier implements Stringable, JsonSerializable, UriAccess, Conditionable
 {
     final public function __construct(protected readonly Psr7UriInterface|UriInterface $uri)
     {
@@ -139,14 +140,7 @@ final public function __call(string $name, array $arguments): static
         };
     }
 
-    /**
-     * Apply the callback if the given "condition" is (or resolves to) true.
-     *
-     * @param (callable($this): bool)|bool $condition
-     * @param callable($this): (self|null) $onSuccess
-     * @param ?callable($this): (self|null) $onFail
-     */
-    final public function when(callable|bool $condition, callable $onSuccess, ?callable $onFail = null): self
+    final public function when(callable|bool $condition, callable $onSuccess, ?callable $onFail = null): static
     {
         if (!is_bool($condition)) {
             $condition = $condition($this);

interfaces/Contracts/Conditionable.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace League\Uri\Contracts;
+
+interface Conditionable
+{
+    /**
+     * Apply the callback if the given "condition" is (or resolves to) true.
+     *
+     * @param (callable(static): bool)|bool $condition
+     * @param callable(static): (static|null) $onSuccess
+     * @param ?callable(static): (static|null) $onFail
+     */
+    public function when(callable|bool $condition, callable $onSuccess, ?callable $onFail = null): static;
+}

interfaces/Contracts/UriInterface.php

@@ -26,7 +26,6 @@
  * @method string|null getPassword() returns the scheme-specific information about how to gain authorization to access the resource.
  * @method string toNormalizedString() returns the normalized string representation of the URI
  * @method array toComponents() returns an associative array containing all the URI components.
- * @method self when(callable|bool $condition, callable $onSuccess, ?callable $onFail = null) conditionally return a new instance
  * @method self normalize() returns a new URI instance with normalized components
  * @method self resolve(UriInterface $uri) resolves a URI against a base URI using RFC3986 rules
  * @method self relativize(UriInterface $uri) relativize a URI against a base URI using RFC3986 rules

uri/BaseUri.php

@@ -14,6 +14,7 @@
 namespace League\Uri;
 
 use JsonSerializable;
+use League\Uri\Contracts\Conditionable;
 use League\Uri\Contracts\UriAccess;
 use League\Uri\Contracts\UriInterface;
 use League\Uri\Exceptions\MissingFeature;
@@ -43,7 +44,7 @@
 /**
  * @phpstan-import-type ComponentMap from UriInterface
  */
-class BaseUri implements Stringable, JsonSerializable, UriAccess
+class BaseUri implements Stringable, JsonSerializable, UriAccess, Conditionable
 {
     /** @var array<string,int> */
     final protected const WHATWG_SPECIAL_SCHEMES = ['ftp' => 1, 'http' => 1, 'https' => 1, 'ws' => 1, 'wss' => 1];
@@ -362,14 +363,7 @@ public function relativize(Stringable|string $uri): static
         );
     }
 
-    /**
-     * Apply the callback if the given "condition" is (or resolves to) true.
-     *
-     * @param (callable($this): bool)|bool $condition
-     * @param callable($this): (self|null) $onSuccess
-     * @param ?callable($this): (self|null) $onFail
-     */
-    final public function when(callable|bool $condition, callable $onSuccess, ?callable $onFail = null): self
+    final public function when(callable|bool $condition, callable $onSuccess, ?callable $onFail = null): static
     {
         if (!is_bool($condition)) {
             $condition = $condition($this);

uri/Http.php

@@ -15,6 +15,7 @@
 
 use Deprecated;
 use JsonSerializable;
+use League\Uri\Contracts\Conditionable;
 use League\Uri\Contracts\UriException;
 use League\Uri\Contracts\UriInterface;
 use League\Uri\Exceptions\SyntaxError;
@@ -27,7 +28,7 @@
 /**
  * @phpstan-import-type InputComponentMap from UriString
  */
-final class Http implements Stringable, Psr7UriInterface, JsonSerializable
+final class Http implements Stringable, Psr7UriInterface, JsonSerializable, Conditionable
 {
     private readonly UriInterface $uri;
 
@@ -224,14 +225,7 @@ private function newInstance(UriInterface $uri): self
         };
     }
 
-    /**
-     * Apply the callback if the given "condition" is (or resolves to) true.
-     *
-     * @param (callable($this): bool)|bool $condition
-     * @param callable($this): (self|null) $onSuccess
-     * @param ?callable($this): (self|null) $onFail
-     */
-    public function when(callable|bool $condition, callable $onSuccess, ?callable $onFail = null): self
+    public function when(callable|bool $condition, callable $onSuccess, ?callable $onFail = null): static
     {
         if (!is_bool($condition)) {
             $condition = $condition($this);

uri/Uri.php

@@ -15,6 +15,7 @@
 
 use Deprecated;
 use finfo;
+use League\Uri\Contracts\Conditionable;
 use League\Uri\Contracts\UriComponentInterface;
 use League\Uri\Contracts\UriException;
 use League\Uri\Contracts\UriInterface;
@@ -74,7 +75,7 @@
  * @phpstan-import-type ComponentMap from UriString
  * @phpstan-import-type InputComponentMap from UriString
  */
-final class Uri implements UriInterface
+final class Uri implements UriInterface, Conditionable
 {
     /**
      * RFC3986 invalid characters.
@@ -1124,14 +1125,7 @@ public function getOrigin(): ?self
         return null === $this->origin ? null : Uri::new($this->origin);
     }
 
-    /**
-     * Apply the callback if the given "condition" is (or resolves to) true.
-     *
-     * @param (callable($this): bool)|bool $condition
-     * @param callable($this): (self|null) $onSuccess
-     * @param ?callable($this): (self|null) $onFail
-     */
-    public function when(callable|bool $condition, callable $onSuccess, ?callable $onFail = null): self
+    public function when(callable|bool $condition, callable $onSuccess, ?callable $onFail = null): static
     {
         if (!is_bool($condition)) {
             $condition = $condition($this);
@@ -1404,14 +1398,11 @@ public function equals(UriInterface|Stringable|string $uri, bool $excludeFragmen
             $uri = self::tryNew($uri);
         }
 
-        if (null === $uri) {
-            return false;
-        }
-
-        $stripFragment = static fn ($uri) => $uri->withFragment(null);
-
-        return $uri->when($excludeFragment, $stripFragment)->toNormalizedString()
-            === $this->when($excludeFragment, $stripFragment)->toNormalizedString();
+        return match(true) {
+            null === $uri => false,
+            $excludeFragment => $uri->withFragment(null)->toNormalizedString() === $this->withFragment(null)->toNormalizedString(),
+            default => $uri->toNormalizedString() === $this->toNormalizedString(),
+        };
     }
 
     private function normalizePath(string $path, ?string $authority): string