NFC - Introduce array shape annotations in docblocks #21675
Conversation
First docblock to use the new array shapes annotation
|
(Standard links)
|
| @@ -259,7 +260,7 @@ protected function formatCustomParams(&$params, $entityId) { | |||
| * | |||
| * @param string $fieldExpr | |||
| * Field identifier with possible suffix, e.g. MyCustomGroup.MyField1:label | |||
| * @return array|NULL | |||
| * @return array{id: int, name: string, entity: string, suffix: string, html_type: string, data_type: string}|NULL | |||
There was a problem hiding this comment.
This makes PhpStorm actually understand what the returned array contains!
There was a problem hiding this comment.
Vim doesn't care but this confuses vscode a little bit. It now thinks the return var is \Civi\Api4\Generic\Traits\array. It doesn't personally bother me too much - not sure who else uses vscode.
There was a problem hiding this comment.
I do think a few people use VSCode.
FWIW, there's some discussion on bmewburn/vscode-intelephense#249 about adding support for "array shapes". They point out that a few tools (psalm, phpstan, phan, phpstorm) now support the notation. There's a link to https://marketplace.visualstudio.com/items?itemName=klesun.deep-assoc-completion-vscode
FWIW, PHPStorm 2019.3 seems happy with the current snippet.
Verbalizing, some options:
- Press forward with array-shape. The world will adjust!
- Hold off on array-shape
- Use for some clever in-between for a transitional period. (Maybe
array|array{id: int...}|NULL? It seems OK on PHPStorm 2019.3?) - Leave it in ambiguity
FWIW, I'm OK with 1 or 2 or 3 - but 👎 on 4.
There was a problem hiding this comment.
Based on that issue it sounds like something will happen with intelliphense eventually, even if it's just the comment earlier in the thread "Even If you're not planning to add feature this syntax should be at least ignored."
By the way I did try to see what happens if the function also has a php type hint : array. It then thinks the return value is exit. (Yep.) And that doesn't work anyway here because it can be null. If I remove the null from the phpdoc and use the typehint : array, then it thinks the return value is never. (Yep.)
There is another php plugin for vscode but it causes the whole computer to grind to a halt if you try to open a drupal 8 folder, so it probably doesn't handle this either.
Your option 3 sort of works. It thinks it's array|\Civi\Api4\Generic\Traits\array{id:. But either way none of this changes what you can do with it in terms of code-completion for vscode because it's an array anyway not an object. So for arrays it's just a visual hint in vscode, so also combined with that github issue me personally I'm fine with option 1. It doesn't prevent you typing $x[0] or something.
There was a problem hiding this comment.
Sounds like we're all fine with option 1.
Overview
First docblock to use the new array shapes annotation 🎉