Eloquent Builder generic annotations

[localusercamp]

Hello.

Some time ago, the framework got generic annotations for collections. This drastically improved type-hinting.

So, why didn't Eloquent Builder get such improvements?

For example in Eloquent Builder class we can add TModel and TCollection templates as following:

/**
 * @template TModel of \Illuminate\Database\Eloquent\Model
 * @template TCollection of \Illuminate\Database\Eloquent\Collection
 * 
 * @property-read HigherOrderBuilderProxy $orWhere
 * @property-read HigherOrderBuilderProxy $whereNot
 * @property-read HigherOrderBuilderProxy $orWhereNot
 *
 * @mixin \Illuminate\Database\Query\Builder
 */
class Builder implements BuilderContract

firstWhere() and get() methods could look something like this then:

/**
 * Add a basic where clause to the query, and return the first result.
 *
 * @param  \Closure|string|array|\Illuminate\Contracts\Database\Query\Expression  $column
 * @param  mixed  $operator
 * @param  mixed  $value
 * @param  string  $boolean
 * @return TModel|static|null
 */
public function firstWhere($column, $operator = null, $value = null, $boolean = 'and')
{
    return $this->where(...func_get_args())->first();
}

/**
 * Execute the query as a "select" statement.
 *
 * @param  array|string  $columns
 * @return TCollection|static[]
 */
public function get($columns = ['*'])
{
    $builder = $this->applyScopes();

    // If we actually found models we will also eager load any relationships that
    // have been specified as needing to be eager loaded, which will solve the
    // n+1 query issue for the developers to avoid running a lot of queries.
    if (count($models = $builder->getModels($columns)) > 0) {
        $models = $builder->eagerLoadRelations($models);
    }

    return $builder->getModel()->newCollection($models);
}

[JeRabix]

++

[shaedrich]

Nice catch! 👍🏻

• Would it make sense to give optional arguments a type within the doc block, even though they can't have a type hint in the actual code? If so, $operator could be typed as string, couldn't it?
• Does a finite list for $boolean exist? It usually is 'and' or 'or', but could also be 'xor' 🤔
• Probably, the list of possible options is too big and schema-dependent for $operator, so I guess, type-hinting it like this '='|'!='|'<>'|'<'|'>'|'LIKE'|… is off the table—but there might be the possibility to add descriptions after it 🤔
• Shouldn't $columns be string[]|string?