Addition of @method annotation for methods with "overloading"

[MaXal]

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

[henzeb]

I think it's a great Idea but, PhpStorm for example does handle it correctly, but also shows an error in the second @method definition with the same name. Not sure if that's wise, using an unsupported way of documentation?

[MaXal]

If the usage is accepted, we will support it fully on the PhpStorm side so there will be no errors and a proper multi-resolve.

The point about the unsupported way of using the documentation is fully correct. In PHPDocumentator @method attribute should be used for methods implemented via __call and __callStatic, but this way still looks like the best way to handle the situation.

[oprypkhantc]

This does sound like a good idea, but there are a few caveats:

• what about generics? Currently @method annotations don't have a way of specifying generics unlike regular functions with @template annotations. This is important because some overloads might have generics while others might not.
• PHPStan currently does not handle this correctly. If there's an effort to support that, we should definitely bring support for that to static analysers too. This shouldn't be complicated, as internally PHPStan does support overloads: https://phpstan.org/r/722ad97f-0358-4782-a375-540f0a7a3413

[curruwilla]

In php 8 it is possible to use named arguments.

->where(column: 'name', value: 'John Doe')

[autaut03]

These serve a completely different function.