Closed anthonyaxenov closed 2 weeks ago
Hi @anthonyaxenov interesting find there and you are right about phpstorm not picking up on the complex array/iterable shapes for @method annotations. i would guess they are mostly used for static analysis here. So maybe that would be a nice feature requests for the jetbrains issue tracker, as i see no reason why phpstorm should not support this syntax. update: i added an issue in the jetbrains issue tracker https://youtrack.jetbrains.com/issue/WI-79045/Missing-support-for-arrayshapes-in-method-docblock-annotation feel free to give that issue an upvote
edit: just checked and phpstan does indeed support this syntax (https://phpstan.org/r/948cd893-1920-49e6-9f19-02413890e577) The same code in phpstorm does not correctly check the types:
I feel I need to explain something. PhpStorm is my main IDE and I used to believe its warnings in 95% of cases because it has very powerfull static analyzer under the hood. I met this behavior while working on my own pet-project and I had no time at that moment to check if this syntax acceptable for another static analyzers used in Flight. Such behavior is pretty annoying but I never know when I return to this pet-project next time. Also I never used such syntax myself inside of @method
s. So I created this issue just to let another developers know that something may be incorrect here.
Unfortunately, there is not standard about phpdoc, only phpDocumentor docs and PSR-5 draft which looks pretty similar (don't they?) and very inconcrete. There are no explicit descriptions about its syntax. Instead of that, php ecosystem (mostly developed by community) and 3rd-party developers' solutions becomes standard de-facto. So that increases entropy in tooling, this case shows it well.
I checked your example in psalm -- and yes, it also supports generic arguments in @method
tags: https://psalm.dev/r/b837894b7e (UPD I noticed your psalm link in youtrack too late))
I think this is good idea to create an issue in JB Youtrack, thanks for that. If I would create it they would definitely close it because of geopolitical reasons.
Thanks again for bringing this issue up and lets hope that JetBrains will fix the type discovery on their side. If not we might need to revisit this again here and look if we can improve that in flight itselt.
Some
@method
s are described incorrectly. Types here should be in native php syntax and there is no way to describe generic types in@method
s directly. Generic types are allowed in@param
,@return
and@template*
tags. Otherwise IDE will not parse such method correctly.Just a small example with
Flight::set()
:I didn't looked up closely in other files but it definitely worth to do
Reference: https://github.com/flightphp/core/blob/master/flight/Flight.php#L21-L81
Found in mikecao/flight v3.12.0