[12.x] Add until to tap

[shaedrich]

Changes

• Adds new tap_until() helper with callback that returns the HigherOrderTapProxy as long as the given condition is met, otherwise it returns the value as usual
• Adds option to tap() to allow the HigherOrderTapProxy to be called a given number of times before returning the value (as shortcut for tap_until())

Examples

Tap n times

class Foo
{
    public function __construct(private int $counter = 0) {}

    public function increment(): void
    {
        $this->counter++;
    }

    public function decrement(): void
    {
        $this->counter--;
    }

    public function getCounter(): int
    {
        return $this->counter;
    }
}

tap(new Foo, 3)->increment()->decrement()->increment()->getCounter(); // 4

Tap until arbitrary condition is met

class Dice
{
    public function __construct(
        private int $spots,
        private int $rolls = 0,
        private array $seed = [5, 1, 4, 3, 6, 2];
    ) {}

    public function roll()
    {
        $this->spots = array_shift($this->seed);
        $this->rolls++;
    }

    public function getSpots(): int
    {
        return $this->spots;
    }

    public function getRolls(): int
    {
        return $this->rolls;
    }
}

tap(new Dice, fn (Dice $dice) => $dice->getSpots() === 3)->roll()->roll()->roll()->roll()->getRolls(); // 4

Infinite tap/unlimited tap (essentially @DarkGhostHunter's multi tap)

class User
{
    use Conditionable;

    private string $givenName;
    private string $familyName;
    private ?int $age;

    public function setGivenName(string $givenName): void
    {
        $this->givenName = $givenName;
    }

    public function setFamilyName(string $familyName): void
    {
        $this->familyName = $familyName;
    }

    public function setAge(int $age): void
    {
        $this->age = $age;
    }

    public function getLabel(): string
    {
        return $this->age !== null
            ? sprintf('%s, %s (%d)', $this->familyName, $this->givenName, $this->age)
            : implode(', ', $this->familyName, $this->givenName);
    }
}

class UserController
{
    public function update(Request $request)
    {
        tap(new User, fn () => true)
            ->setGivenName($request->input('given_name'))
            ->setFamilyName($request->input('family_name'))
            ->when($request->has('birthday'), fn () => $user->setAge($request->date('birthday')->diffInYears()))
            ->target
            ->getLabel(); // "John Doe (58)"
    }
}

Previous art

• [5.6] Add optional condition to tap() #23452 – also wanted to add a condition to tap() but instead of a callback, it was a simple boolean which made it inflexible and not much different to the when() helper as pointed out in the comments of said PR ([5.6] Add optional condition to tap() #23452 (comment))
• [6.x] Extends tap helper function to continually return instances #30540 – also wanted to continuously return the HigherOrderTapProxy but with no limit, which would have been a breaking change
• "Laravel: Multitap, Multitap, Multitap" by @DarkGhostHunter on medium – I love the idea and we probably still need this as well, it comes with the downside that you have to explicitly end the chain (granted, until also does this, but in another way), which might look inconvenient

[github-actions]

Thanks for submitting a PR!

Note that draft PRs are not reviewed. If you would like a review, please mark your pull request as ready for review in the GitHub user interface.

Pull requests that are abandoned in draft may be closed due to inactivity.

[shaedrich]

The tests are constantly timing out for reasons I don't understand

[Rizky92]

I was thinking something like this is much clearer than having to specify arbitrary number, albeit class must be tappable.

$obj = new Object();
$obj->tap->requestRecords()
    ->tap->applyChanges()
    ->tap->commit()
    ->all();

[shaedrich]

That works for classes, but not so much for the plain helper on non-tappable objects:

$obj = new Object();
tap(tap(tap($obj->requestRecords())->applyChanges())->commit()->all();

[DarkGhostHunter]

What about this:

$tappable = tap($object);

$results = $tappable->tap->requestRecords()
    ->tap->applyChanges()
    ->tap->commit()
    ->all();

Basically, extend the original proxy object to allow tapping into the object and returning the same tap instance regardless of the result, or getting the tapped object using $tap->object.

public static __call(string $name, array $arguments)
{
    if ($name === 'tap') {
        return new static($this);
    }

    if ($name === 'object') {
        return $this->value;
    }

    // ...
}