feat: add generics to tap() helper (#51881)

src/Illuminate/Database/Concerns/BuildsQueries.php

@@ -540,7 +540,7 @@ protected function cursorPaginator($items, $perPage, $cursor, $options)
     /**
      * Pass the query to a given callback.
      *
-     * @param  callable  $callback
+     * @param  callable($this): mixed  $callback
      * @return $this
      */
     public function tap($callback)

src/Illuminate/Support/Traits/Tappable.php

@@ -7,8 +7,8 @@ trait Tappable
     /**
      * Call the given Closure with this instance then return the instance.
      *
-     * @param  callable|null  $callback
-     * @return $this|\Illuminate\Support\HigherOrderTapProxy
+     * @param  (callable($this): mixed)|null  $callback
+     * @return ($callback is null ? \Illuminate\Support\HigherOrderTapProxy : $this)
      */
     public function tap($callback = null)
     {

src/Illuminate/Support/helpers.php

@@ -350,9 +350,11 @@ public function __toString()
     /**
      * Call the given Closure with the given value then return the value.
      *
-     * @param  mixed  $value
-     * @param  callable|null  $callback
-     * @return mixed
+     * @template TValue
+     *
+     * @param  TValue  $value
+     * @param  (callable(TValue): mixed)|null  $callback
+     * @return ($callback is null ? \Illuminate\Support\HigherOrderTapProxy : TValue)
      */
     function tap($value, $callback = null)
     {

types/Support/Helpers.php

@@ -67,3 +67,8 @@
 assertType('int|null', rescue(fn () => 123));
 assertType('int', rescue(fn () => 123, 345));
 assertType('int', rescue(fn () => 123, fn () => 345));
+
+assertType('User', tap(new User(), function ($user) {
+    assertType('User', $user);
+}));
+assertType('Illuminate\Support\HigherOrderTapProxy', tap(new User()));