Consider the method \Illuminate\Database\Eloquent\Builder::where.

It can be invoked as where('name', 'John Doe') and where('name', '<>', 'John Doe') but its signature is where($column, $operator = null, $value = null, $boolean = 'and').

So in the first call, it looks like 'John Doe' is an operator, but by semantics, it's a value. For the IDE, it's impossible to figure out this change of the meaning, so it shows an incorrect hint:

Since PHP doesn't support overloading in the userland, there is no way to define a second method with the correct signature, so the only way to do this is via PHPDoc. Since there is no unique tag for such a situation, I suggest using @method.

So for the where method, we can add the following annotation:
@method where(\Closure|array|string|\Illuminate\Database\Query\Expression $column, mixed $value, string $boolean='and')

The annotation will clearly specify the semantics of the second argument for the where method.

The original request in PhpStorm issue tracker: https://youtrack.jetbrains.com/issue/WI-67614

PhpStorm Team