[12.x] Add pipe method query builders (#55171)

* Update tap description

* Add pipe method to query builder

* Add eloquent query builder tests

* Fix builder return type in type tests

* Add eloquent builder type tests

* Reorganise type tests

* Fix broken return syntax

* Improve types

Author: timacdonald

src/Illuminate/Database/Concerns/BuildsQueries.php

@@ -587,7 +587,7 @@ protected function cursorPaginator($items, $perPage, $cursor, $options)
     }
 
     /**
-     * Pass the query to a given callback.
+     * Pass the query to a given callback and then return it.
      *
      * @param  callable($this): mixed  $callback
      * @return $this
@@ -598,4 +598,17 @@ public function tap($callback)
 
         return $this;
     }
+
+    /**
+     * Pass the query to a given callback and return the result.
+     *
+     * @template TReturn
+     *
+     * @param  (callable($this): TReturn)  $callback
+     * @return (TReturn is null|void ? $this : TReturn)
+     */
+    public function pipe($callback)
+    {
+        return $callback($this) ?? $this;
+    }
 }

tests/Database/DatabaseEloquentBuilderTest.php

@@ -21,6 +21,7 @@
 use Illuminate\Support\Carbon;
 use Illuminate\Support\Collection as BaseCollection;
 use Mockery as m;
+use PDO;
 use PHPUnit\Framework\TestCase;
 use stdClass;
 
@@ -2615,6 +2616,31 @@ public function getPassthru(): array
         }
     }
 
+    public function testPipeCallback()
+    {
+        $query = new Builder(new BaseBuilder(
+            $connection = new Connection(new PDO('sqlite::memory:')),
+            new Grammar($connection),
+            new Processor,
+        ));
+
+        $result = $query->pipe(fn (Builder $query) => 5);
+        $this->assertSame(5, $result);
+
+        $result = $query->pipe(fn (Builder $query) => null);
+        $this->assertSame($query, $result);
+
+        $result = $query->pipe(function (Builder $query) {
+            //
+        });
+        $this->assertSame($query, $result);
+
+        $this->assertCount(0, $query->getQuery()->wheres);
+        $result = $query->pipe(fn (Builder $query) => $query->where('foo', 'bar'));
+        $this->assertSame($query, $result);
+        $this->assertCount(1, $query->getQuery()->wheres);
+    }
+
     protected function mockConnectionForModel($model, $database)
     {
         $grammarClass = 'Illuminate\Database\Query\Grammars\\'.$database.'Grammar';

tests/Database/DatabaseQueryBuilderTest.php

@@ -301,6 +301,27 @@ public function testTapCallback()
         $this->assertSame('select * from "users" where "id" = ? and "email" = ?', $builder->toSql());
     }
 
+    public function testPipeCallback()
+    {
+        $query = $this->getBuilder();
+
+        $result = $query->pipe(fn (Builder $query) => 5);
+        $this->assertSame(5, $result);
+
+        $result = $query->pipe(fn (Builder $query) => null);
+        $this->assertSame($query, $result);
+
+        $result = $query->pipe(function (Builder $query) {
+            //
+        });
+        $this->assertSame($query, $result);
+
+        $this->assertCount(0, $query->wheres);
+        $result = $query->pipe(fn (Builder $query) => $query->where('foo', 'bar'));
+        $this->assertSame($query, $result);
+        $this->assertCount(1, $query->wheres);
+    }
+
     public function testBasicWheres()
     {
         $builder = $this->getBuilder();

types/Database/Eloquent/Builder.php

@@ -223,6 +223,12 @@ function test(
     assertType('Illuminate\Types\Builder\CommentBuilder', $comment->newQuery()->where('foo', 'bar'));
     assertType('Illuminate\Types\Builder\CommentBuilder', $comment->newQuery()->foo());
     assertType('Illuminate\Types\Builder\Comment', $comment->newQuery()->create(['name' => 'John']));
+    assertType('Illuminate\Database\Eloquent\Builder<Illuminate\Types\Builder\User>', $query->pipe(function () {
+        //
+    }));
+    assertType('Illuminate\Database\Eloquent\Builder<Illuminate\Types\Builder\User>', $query->pipe(fn () => null));
+    assertType('Illuminate\Database\Eloquent\Builder<Illuminate\Types\Builder\User>', $query->pipe(fn ($query) => $query));
+    assertType('5', $query->pipe(fn ($query) => 5));
 }
 
 class User extends Model

types/Database/Query/Builder.php

@@ -60,4 +60,10 @@ function test(Builder $query, EloquentBuilder $userQuery): void
         assertType('object', $users);
         assertType('int', $page);
     });
+    assertType('Illuminate\Database\Query\Builder', $query->pipe(function () {
+        //
+    }));
+    assertType('Illuminate\Database\Query\Builder', $query->pipe(fn () => null));
+    assertType('Illuminate\Database\Query\Builder', $query->pipe(fn ($query) => $query));
+    assertType('5', $query->pipe(fn ($query) => 5));
 }