[12.x] Add until to tap

src/Illuminate/Support/HigherOrderTapProxy.php

@@ -2,36 +2,36 @@
 
 namespace Illuminate\Support;
 
+use Closure;
+
+/**
+ * @template Target
+ */
 class HigherOrderTapProxy
 {
-    /**
-     * The target being tapped.
-     *
-     * @var mixed
-     */
-    public $target;
-
     /**
      * Create a new tap proxy instance.
      *
-     * @param  mixed  $target
+     * @param  Target  $target  The target being tapped.
+     * @param  (\Closure(): bool)|null  $until
      */
-    public function __construct($target)
+    public function __construct(public $target, public ?Closure $until = null)
     {
-        $this->target = $target;
     }
 
     /**
      * Dynamically pass method calls to the target.
      *
      * @param  string  $method
      * @param  array  $parameters
-     * @return mixed
+     * @return ($until is null ? Target : mixed)
      */
     public function __call($method, $parameters)
     {
         $this->target->{$method}(...$parameters);
 
-        return $this->target;
+        return $this->until !== null && ($this->until)()
+            ? $this
+            : $this->target;
     }
 }

src/Illuminate/Support/Traits/Tappable.php

@@ -7,11 +7,24 @@ trait Tappable
     /**
      * Call the given Closure with this instance then return the instance.
      *
-     * @param  (callable($this): mixed)|null  $callback
-     * @return ($callback is null ? \Illuminate\Support\HigherOrderTapProxy : $this)
+     * @param  (callable($this): mixed)|int|null  $callback
+     * @return ($callback is null ? \Illuminate\Support\HigherOrderTapProxy : ($callback is int ? \Illuminate\Support\HigherOrderTapProxy : $this))
      */
     public function tap($callback = null)
     {
         return tap($this, $callback);
     }
+
+    /**
+     * Call the given Closure with this instance until the given condition returns false
+     * then return the instance.
+     *
+     * @param  (callable(): bool)  $until
+     * @param  (\Closure($this): mixed)|null  $callback
+     * @return ($callback is null ? \Illuminate\Support\HigherOrderTapProxy : $this)
+     */
+    public function tapUntil($until, $callback = null)
+    {
+        return tap_until($this, $until, $callback);
+    }
 }

src/Illuminate/Support/helpers.php

@@ -378,7 +378,7 @@ public function __toString()
      * @template TValue
      *
      * @param  TValue  $value
-     * @param  (callable(TValue): mixed)|null  $callback
+     * @param  (callable(TValue): mixed)|int|null  $callback
      * @return ($callback is null ? \Illuminate\Support\HigherOrderTapProxy : TValue)
      */
     function tap($value, $callback = null)
@@ -387,6 +387,35 @@ function tap($value, $callback = null)
             return new HigherOrderTapProxy($value);
         }
 
+        if (is_int($callback)) {
+            return tap_until($value, function () use (&$callback) {
+                return $callback-- !== 0;
+            });
+        }
+
+        $callback($value);
+
+        return $value;
+    }
+}
+
+if (! function_exists('tap_until')) {
+    /**
+     * Call the given Closure with the given value then return the value.
+     *
+     * @template TValue
+     *
+     * @param  TValue  $value
+     * @param  callable(): bool  $until
+     * @param  (\Closure(TValue): mixed)|null  $callback
+     * @return ($callback is null ? \Illuminate\Support\HigherOrderTapProxy : TValue)
+     */
+    function tap_until($value, $until, $callback = null)
+    {
+        if (is_null($callback)) {
+            return new HigherOrderTapProxy($value, $until);
+        }
+
         $callback($value);
 
         return $value;

tests/Support/SupportHelpersTest.php

@@ -834,6 +834,10 @@ public function testTap()
         $mock = m::mock();
         $mock->shouldReceive('foo')->once()->andReturn('bar');
         $this->assertEquals($mock, tap($mock)->foo());
+
+        $mock = m::mock();
+        $mock->shouldReceive('increment')->twice()->andReturn(1, 2);
+        $this->assertEquals($mock, tap($mock, 2)->increment()->increment());
     }
 
     public function testThrow()