[12.x] add generics to QueryBuilder’s column related methods (#55663)

* [12.x] add generics to QueryBuilder’s column related methods

* fix styling

* more detailed types

* narrow types

* more narrowing

* not at this time

* fix test

* use type alias

* more use of alias

* not now

* fix styling

* use covariant

* fixed

* fix styling

* dont include string in SubQueryBuilderTypes

* reorder

* add generics to callback

* fix styling

* remove type alias

* fix singlular name

* replace all aliases

* revert

Author: taka-oyama

src/Illuminate/Database/Query/Builder.php

@@ -100,7 +100,7 @@ class Builder implements BuilderContract
     /**
      * The columns that should be returned.
      *
-     * @var array|null
+     * @var array<string|\Illuminate\Contracts\Database\Query\Expression>|null
      */
     public $columns;
 
@@ -278,7 +278,7 @@ public function __construct(
     /**
      * Set the columns to be selected.
      *
-     * @param  array|mixed  $columns
+     * @param  mixed  $columns
      * @return $this
      */
     public function select($columns = ['*'])
@@ -432,7 +432,7 @@ protected function prependDatabaseNameIfCrossDatabaseQuery($query)
     /**
      * Add a new select column to the query.
      *
-     * @param  array|mixed  $column
+     * @param  mixed  $column
      * @return $this
      */
     public function addSelect($column)
@@ -3019,7 +3019,7 @@ public function toRawSql()
      * Execute a query for a single record by ID.
      *
      * @param  int|string  $id
-     * @param  array|string  $columns
+     * @param  string|\Illuminate\Contracts\Database\Query\Expression|array<string|\Illuminate\Contracts\Database\Query\Expression>  $columns
      * @return object|null
      */
     public function find($id, $columns = ['*'])
@@ -3033,7 +3033,7 @@ public function find($id, $columns = ['*'])
      * @template TValue
      *
      * @param  mixed  $id
-     * @param  (\Closure(): TValue)|list<string>|string  $columns
+     * @param  (\Closure(): TValue)|string|\Illuminate\Contracts\Database\Query\Expression|array<string|\Illuminate\Contracts\Database\Query\Expression>  $columns
      * @param  (\Closure(): TValue)|null  $callback
      * @return object|TValue
      */
@@ -3096,7 +3096,7 @@ public function soleValue($column)
     /**
      * Execute the query as a "select" statement.
      *
-     * @param  array|string  $columns
+     * @param  string|\Illuminate\Contracts\Database\Query\Expression|array<string|\Illuminate\Contracts\Database\Query\Expression>  $columns
      * @return \Illuminate\Support\Collection<int, \stdClass>
      */
     public function get($columns = ['*'])
@@ -3152,7 +3152,7 @@ protected function withoutGroupLimitKeys($items)
      * Paginate the given query into a simple paginator.
      *
      * @param  int|\Closure  $perPage
-     * @param  array|string  $columns
+     * @param  string|\Illuminate\Contracts\Database\Query\Expression|array<string|\Illuminate\Contracts\Database\Query\Expression>  $columns
      * @param  string  $pageName
      * @param  int|null  $page
      * @param  \Closure|int|null  $total
@@ -3180,7 +3180,7 @@ public function paginate($perPage = 15, $columns = ['*'], $pageName = 'page', $p
      * This is more efficient on larger data-sets, etc.
      *
      * @param  int  $perPage
-     * @param  array|string  $columns
+     * @param  string|\Illuminate\Contracts\Database\Query\Expression|array<string|\Illuminate\Contracts\Database\Query\Expression>  $columns
      * @param  string  $pageName
      * @param  int|null  $page
      * @return \Illuminate\Contracts\Pagination\Paginator
@@ -3203,7 +3203,7 @@ public function simplePaginate($perPage = 15, $columns = ['*'], $pageName = 'pag
      * This is more efficient on larger data-sets, etc.
      *
      * @param  int|null  $perPage
-     * @param  array|string  $columns
+     * @param  string|\Illuminate\Contracts\Database\Query\Expression|array<string|\Illuminate\Contracts\Database\Query\Expression>  $columns
      * @param  string  $cursorName
      * @param  \Illuminate\Pagination\Cursor|string|null  $cursor
      * @return \Illuminate\Contracts\Pagination\CursorPaginator
@@ -3250,7 +3250,7 @@ protected function ensureOrderForCursorPagination($shouldReverse = false)
     /**
      * Get the count of the total records for the paginator.
      *
-     * @param  array  $columns
+     * @param  array<string|\Illuminate\Contracts\Database\Query\Expression>  $columns
      * @return int
      */
     public function getCountForPagination($columns = ['*'])
@@ -3272,8 +3272,8 @@ public function getCountForPagination($columns = ['*'])
     /**
      * Run a pagination count query.
      *
-     * @param  array  $columns
-     * @return array
+     * @param  array<string|\Illuminate\Contracts\Database\Query\Expression>  $columns
+     * @return array<mixed>
      */
     protected function runPaginationCountQuery($columns = ['*'])
     {
@@ -3313,7 +3313,8 @@ protected function cloneForPaginationCount()
     /**
      * Remove the column aliases since they will break count queries.
      *
-     * @return array
+     * @param  array<string|\Illuminate\Contracts\Database\Query\Expression>  $columns
+     * @return array<string|\Illuminate\Contracts\Database\Query\Expression>
      */
     protected function withoutSelectAliases(array $columns)
     {
@@ -3677,9 +3678,11 @@ protected function setAggregate($function, $columns)
      *
      * After running the callback, the columns are reset to the original value.
      *
-     * @param  array  $columns
-     * @param  callable  $callback
-     * @return mixed
+     * @template TResult
+     *
+     * @param  array<string|\Illuminate\Contracts\Database\Query\Expression>  $columns
+     * @param  callable(): TResult  $callback
+     * @return TResult
      */
     protected function onceWithColumns($columns, $callback)
     {
@@ -4081,7 +4084,7 @@ protected function forSubQuery()
     /**
      * Get all of the query builder's columns in a text-only array with all expressions evaluated.
      *
-     * @return array
+     * @return list<string>
      */
     public function getColumns()
     {