Introduce TFetchMode generic to enhance PHPDoc support for differen…

…t PDO fetch modes in Query Builder
laravel · Nov 12, 2024 · 5b34eac · 5b34eac
1 parent 4cd413b
commit 5b34eac
Show file tree

Hide file tree

Showing 21 changed files with 146 additions and 71 deletions.
diff --git a/src/Illuminate/Auth/Passwords/DatabaseTokenRepository.php b/src/Illuminate/Auth/Passwords/DatabaseTokenRepository.php
@@ -227,7 +227,7 @@ public function getConnection()
     /**
      * Begin a new database query against the table.
      *
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     protected function getTable()
     {

diff --git a/src/Illuminate/Cache/DatabaseStore.php b/src/Illuminate/Cache/DatabaseStore.php
@@ -424,7 +424,7 @@ public function flush()
     /**
      * Get a query builder for the cache table.
      *
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     protected function table()
     {

diff --git a/src/Illuminate/Database/Capsule/Manager.php b/src/Illuminate/Database/Capsule/Manager.php
@@ -80,7 +80,7 @@ public static function connection($connection = null)
      * @param  \Closure|\Illuminate\Database\Query\Builder|string  $table
      * @param  string|null  $as
      * @param  string|null  $connection
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     public static function table($table, $as = null, $connection = null)
     {

diff --git a/src/Illuminate/Database/Concerns/BuildsQueries.php b/src/Illuminate/Database/Concerns/BuildsQueries.php
@@ -21,6 +21,7 @@
 
 /**
  * @template TValue
+ * @template TFetchMode of \PDO::FETCH_*|false
  *
  * @mixin \Illuminate\Database\Eloquent\Builder
  * @mixin \Illuminate\Database\Query\Builder
@@ -337,7 +338,7 @@ protected function orderedLazyById($chunkSize = 1000, $column = null, $alias = n
      * Execute the query and get the first result.
      *
      * @param  array|string  $columns
-     * @return TValue|null
+     * @return (TFetchMode is false ? TValue : (TFetchMode is 1|5|8|9 ? object : array))|null
      */
     public function first($columns = ['*'])
     {
@@ -349,7 +350,7 @@ public function first($columns = ['*'])
      *
      * @param  array|string  $columns
      * @param  string|null  $message
-     * @return TValue
+     * @return (TFetchMode is false ? TValue : (TFetchMode is 1|5|8|9 ? object : array))
      *
      * @throws \Illuminate\Database\RecordNotFoundException
      */
@@ -366,7 +367,7 @@ public function firstOrFail($columns = ['*'], $message = null)
      * Execute the query and get the first result if it's the sole matching record.
      *
      * @param  array|string  $columns
-     * @return TValue
+     * @return (TFetchMode is false ? TValue : (TFetchMode is 1|5|8|9 ? object : array))
      *
      * @throws \Illuminate\Database\RecordsNotFoundException
      * @throws \Illuminate\Database\MultipleRecordsFoundException

diff --git a/src/Illuminate/Database/Connection.php b/src/Illuminate/Database/Connection.php
@@ -312,7 +312,7 @@ public function getSchemaBuilder()
      *
      * @param  \Closure|\Illuminate\Database\Query\Builder|\Illuminate\Contracts\Database\Query\Expression|string  $table
      * @param  string|null  $as
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     public function table($table, $as = null)
     {
@@ -322,7 +322,7 @@ public function table($table, $as = null)
     /**
      * Get a new query builder instance.
      *
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     public function query()
     {
@@ -661,8 +661,10 @@ public function pretend(Closure $callback)
     /**
      * Execute the given callback without "pretending".
      *
-     * @param  \Closure  $callback
-     * @return mixed
+     * @template TResult
+     *
+     * @param  \Closure():TResult  $callback
+     * @return TResult
      */
     public function withoutPretending(Closure $callback)
     {
@@ -682,8 +684,10 @@ public function withoutPretending(Closure $callback)
     /**
      * Execute the given callback in "dry run" mode.
      *
-     * @param  \Closure  $callback
-     * @return array
+     * @template TResult of array
+     *
+     * @param  \Closure():TResult  $callback
+     * @return TResult
      */
     protected function withFreshQueryLog($callback)
     {

diff --git a/src/Illuminate/Database/ConnectionInterface.php b/src/Illuminate/Database/ConnectionInterface.php
@@ -11,7 +11,7 @@ interface ConnectionInterface
      *
      * @param  \Closure|\Illuminate\Database\Query\Builder|string  $table
      * @param  string|null  $as
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     public function table($table, $as = null);
 

diff --git a/src/Illuminate/Database/Eloquent/Builder.php b/src/Illuminate/Database/Eloquent/Builder.php
@@ -33,7 +33,7 @@
  */
 class Builder implements BuilderContract
 {
-    /** @use \Illuminate\Database\Concerns\BuildsQueries<TModel> */
+    /** @use \Illuminate\Database\Concerns\BuildsQueries<TModel,false> */
     use BuildsQueries, ForwardsCalls, QueriesRelationships {
         BuildsQueries::sole as baseSole;
     }
@@ -1797,7 +1797,7 @@ protected function getUnionBuilders()
     /**
      * Get the underlying query builder instance.
      *
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     public function getQuery()
     {
@@ -1820,7 +1820,7 @@ public function setQuery($query)
     /**
      * Get a base query builder instance.
      *
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     public function toBase()
     {

diff --git a/src/Illuminate/Database/Eloquent/Model.php b/src/Illuminate/Database/Eloquent/Model.php
@@ -1607,7 +1607,7 @@ public function newEloquentBuilder($query)
     /**
      * Get a new query builder instance for the connection.
      *
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     protected function newBaseQueryBuilder()
     {

diff --git a/src/Illuminate/Database/Eloquent/Relations/Concerns/InteractsWithPivotTable.php b/src/Illuminate/Database/Eloquent/Relations/Concerns/InteractsWithPivotTable.php
@@ -538,7 +538,7 @@ public function newExistingPivot(array $attributes = [])
     /**
      * Get a new plain query builder for the pivot table.
      *
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     public function newPivotStatement()
     {
@@ -549,7 +549,7 @@ public function newPivotStatement()
      * Get a new pivot statement for a given "other" ID.
      *
      * @param  mixed  $id
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     public function newPivotStatementForId($id)
     {
@@ -559,7 +559,7 @@ public function newPivotStatementForId($id)
     /**
      * Create a new query builder for the pivot table.
      *
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     public function newPivotQuery()
     {

diff --git a/src/Illuminate/Database/Eloquent/Relations/MorphToMany.php b/src/Illuminate/Database/Eloquent/Relations/MorphToMany.php
@@ -127,7 +127,7 @@ protected function getCurrentlyAttachedPivots()
     /**
      * Create a new query builder for the pivot table.
      *
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     public function newPivotQuery()
     {

diff --git a/src/Illuminate/Database/Eloquent/Relations/Relation.php b/src/Illuminate/Database/Eloquent/Relations/Relation.php
@@ -316,7 +316,7 @@ public function getQuery()
     /**
      * Get the base query builder driving the Eloquent builder.
      *
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     public function getBaseQuery()
     {
@@ -326,7 +326,7 @@ public function getBaseQuery()
     /**
      * Get a base query builder instance.
      *
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     public function toBase()
     {

diff --git a/src/Illuminate/Database/Migrations/DatabaseMigrationRepository.php b/src/Illuminate/Database/Migrations/DatabaseMigrationRepository.php
@@ -199,7 +199,7 @@ public function deleteRepository()
     /**
      * Get a query builder for the migration table.
      *
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     protected function table()
     {

diff --git a/src/Illuminate/Database/Query/Builder.php b/src/Illuminate/Database/Query/Builder.php
@@ -31,9 +31,12 @@
 
 use function Illuminate\Support\enum_value;
 
+/**
+ * @template TFetchMode of \PDO::FETCH_*
+ */
 class Builder implements BuilderContract
 {
-    /** @use \Illuminate\Database\Concerns\BuildsQueries<object> */
+    /** @use \Illuminate\Database\Concerns\BuildsQueries<array|object,TFetchMode> */
     use BuildsQueries, ExplainsQueries, ForwardsCalls, Macroable {
         __call as macroCall;
     }
@@ -1790,7 +1793,7 @@ public function whereNested(Closure $callback, $boolean = 'and')
     /**
      * Create a new query instance for nested where condition.
      *
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     public function forNestedWhere()
     {
@@ -3030,7 +3033,7 @@ public function toRawSql()
      *
      * @param  int|string  $id
      * @param  array|string  $columns
-     * @return object|null
+     * @return (TFetchMode is 1|5|8|9 ? object : array)|null
      */
     public function find($id, $columns = ['*'])
     {
@@ -3045,7 +3048,7 @@ public function find($id, $columns = ['*'])
      * @param  mixed  $id
      * @param  (\Closure(): TValue)|list<string>|string  $columns
      * @param  (\Closure(): TValue)|null  $callback
-     * @return object|TValue
+     * @return ($columns is Closure ? TValue|(TFetchMode is 1|5|8|9 ? object : array) : ($callback is Closure ? TValue|(TFetchMode is 1|5|8|9 ? object : array) : (TFetchMode is 1|5|8|9 ? object : array)))
      */
     public function findOr($id, $columns = ['*'], ?Closure $callback = null)
     {
@@ -3530,8 +3533,10 @@ public function doesntExist()
     /**
      * Execute the given callback if no rows exist for the current query.
      *
-     * @param  \Closure  $callback
-     * @return mixed
+     * @template TResult
+     *
+     * @param  \Closure():TResult  $callback
+     * @return true|TResult
      */
     public function existsOr(Closure $callback)
     {
@@ -3541,8 +3546,10 @@ public function existsOr(Closure $callback)
     /**
      * Execute the given callback if rows exist for the current query.
      *
-     * @param  \Closure  $callback
-     * @return mixed
+     * @template TResult
+     *
+     * @param  \Closure():TResult  $callback
+     * @return true|TResult
      */
     public function doesntExistOr(Closure $callback)
     {
@@ -3690,9 +3697,11 @@ protected function setAggregate($function, $columns)
      *
      * After running the callback, the columns are reset to the original value.
      *
+     * @template TResult
+     *
      * @param  array  $columns
-     * @param  callable  $callback
-     * @return mixed
+     * @param  callable():TResult  $callback
+     * @return TResult
      */
     protected function onceWithColumns($columns, $callback)
     {
@@ -4086,7 +4095,7 @@ public function truncate()
     /**
      * Get a new instance of the query builder.
      *
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     public function newQuery()
     {
@@ -4096,7 +4105,7 @@ public function newQuery()
     /**
      * Create a new query instance for a sub-query.
      *
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     protected function forSubQuery()
     {

diff --git a/src/Illuminate/Database/Query/JoinClause.php b/src/Illuminate/Database/Query/JoinClause.php
@@ -125,7 +125,7 @@ public function newQuery()
     /**
      * Create a new query instance for sub-query.
      *
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     protected function forSubQuery()
     {
@@ -135,7 +135,7 @@ protected function forSubQuery()
     /**
      * Create a new parent query instance.
      *
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     protected function newParentQuery()
     {

diff --git a/src/Illuminate/Notifications/HasDatabaseNotifications.php b/src/Illuminate/Notifications/HasDatabaseNotifications.php
@@ -17,7 +17,7 @@ public function notifications()
     /**
      * Get the entity's read notifications.
      *
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     public function readNotifications()
     {
@@ -27,7 +27,7 @@ public function readNotifications()
     /**
      * Get the entity's unread notifications.
      *
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     public function unreadNotifications()
     {

diff --git a/src/Illuminate/Queue/Failed/DatabaseFailedJobProvider.php b/src/Illuminate/Queue/Failed/DatabaseFailedJobProvider.php
@@ -163,7 +163,7 @@ public function count($connection = null, $queue = null)
     /**
      * Get a new query builder instance for the table.
      *
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     protected function getTable()
     {

diff --git a/src/Illuminate/Queue/Failed/DatabaseUuidFailedJobProvider.php b/src/Illuminate/Queue/Failed/DatabaseUuidFailedJobProvider.php
@@ -176,7 +176,7 @@ public function count($connection = null, $queue = null)
     /**
      * Get a new query builder instance for the table.
      *
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     protected function getTable()
     {

diff --git a/src/Illuminate/Session/DatabaseSessionHandler.php b/src/Illuminate/Session/DatabaseSessionHandler.php
@@ -284,7 +284,7 @@ public function gc($lifetime): int
     /**
      * Get a fresh query builder instance for the table.
      *
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     protected function getQuery()
     {

diff --git a/src/Illuminate/Validation/DatabasePresenceVerifier.php b/src/Illuminate/Validation/DatabasePresenceVerifier.php
@@ -75,7 +75,7 @@ public function getMultiCount($collection, $column, array $values, array $extra
      *
      * @param  \Illuminate\Database\Query\Builder  $query
      * @param  array  $conditions
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     protected function addConditions($query, $conditions)
     {
@@ -117,7 +117,7 @@ protected function addWhere($query, $key, $extraValue)
      * Get a query builder for the given table.
      *
      * @param  string  $table
-     * @return \Illuminate\Database\Query\Builder
+     * @return \Illuminate\Database\Query\Builder<\PDO::FETCH_OBJ>
      */
     protected function table($table)
     {