[11.x] Add multiple method signatures for where in PHPDoc block

[shaedrich]

Looks something like this in the IDE:

[hn-seoai]

Since function overloading isn't a thing in PHP, I don't think this is the right thing to do. It messes with the IDE's ability to work with named parameters and the position of those parameters.

If I see my IDE suggesting 4 different kinds of where methods, I'd think someone messed up with duplicate names across traits.

[shaedrich]

Well, otherwise, it's impossible to know what can be passed to where() and how unless from experience, since the method signature is incredibly complex. How would you achieve that instead?

Because, only looking at

    /**
     * Add a basic where clause to the query.
     *
     * @param  \Closure|string|array|\Illuminate\Contracts\Database\Query\Expression  $column
     * @param  mixed  $operator
     * @param  mixed  $value
     * @param  string  $boolean
     * @return $this
     */
    public function where($column, $operator = null, $value = null, $boolean = 'and')

the only thing with some certainty is $column. Everything else can be literally everything. There's no way to tell unless you try it out.

Furthermore, yes, PHP doesn't natively support method overloading, but Laravel clearly does a custom implementation of exactly that, yet, it isn't well documented as such.

[AndrewMast]

Laravel clearly does a custom implementation of exactly that, yet, it isn't well documented as such.

We actually do have documentation for it. Its on the laravel website under the database query builder documentation and the syntax is very similar to the collection where method which also has its own documentation.

As mentioned earlier, overloading methods isn't possible in PHP unless you do something like what laravel is doing. Because of that, I don't think we should add this. I wouldn't mind a @see or something similar, but it would be hard to be consistent, since there are so many methods and since documentation changes often, I think its better to leave it out.

When I'm working and I don't understand a laravel method from the argument names, I open the method code to look at it, and if I still don't understand, I pull up the laravel documentation and search for the method using Cmd + K. I think adding further phpdoc blocks will take away from the simplicity of having one singular place to look up documentation. And if the documentation is out of date, we can just make a pull request to update it: laravel/docs.

[timacdonald]

Can you post screenshots of this with Intellisense hover and VSCode hover?

If it doesn't work well in both of these, this could make things worse for a large pool of Laravel developers, not better.

[timacdonald]

Last time I checked, which was around 6 months ago, a lot of tooling did not support literals / generics in @method docblocks.

Suggested change

	/**
	* @method self where(string $column, $value)
	* @method self where(string $column, string $operator, $value)
	* @method self where(string $column, string $operator, $value, 'and'|'or' $boolean)
	* @method self where(\Closure(): mixed)
	* @method self where(array<string, mixed> $column)
	* @method self where((array{string, 'and'|'or', mixed}|array{string, mixed}|array{column: string, operator?: 'and'|'or', value: mixed})[] $column)
	* @method self where(\Closure|string|array|\Illuminate\Contracts\Database\Query\Expression $column, mixed $operator null, mixed $value = null, string $boolean = 'and')
	*/
	/**
	* @method self where(string $column, $value)
	* @method self where(string $column, string $operator, $value)
	* @method self where(string $column, string $operator, $value, string $boolean)
	* @method self where(\Closure(): mixed)
	* @method self where(array $column)
	* @method self where(\Closure|string|array|\Illuminate\Contracts\Database\Query\Expression $column, mixed $operator = null, mixed $value = null, string $boolean = 'and')
	*/