Support for array and object shapes

[hworld]

As shown here in the proposal for phpdoc fig standard: https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md#examples-12

Basically looks like this

/**
 * Initializes this class with the given options.
 *
 * @param array $options {
 *     @var bool   $required Whether this element is required
 *     @var string $label    The display name for this element
 * }
 */
public function __construct(array $options = array())
{
    <...>
}

Would be really cool since PHP tends to use these option arrays all over the place in libraries!

[hworld]

btw, I think it would be really helpful to initially just parse and show it properly when hovering or typing the function out with the little intellisense above for the params. Support for doing $options['required'] and having intelephense know that it should be a bool is great, but I think probably also harder and not as important as just seeing the definition initially.

[hworld]

Alternate syntax that Psalm static checker uses: /** @return array<int, array{name: string, type: string, active: bool}> */ which is arguably nicer to look at and type.

[bmewburn]

This would be useful. I agree the Psalm syntax is nicer but the fig standard might have more clout. Either way this will require a proper phpdoc parser. Currently it is very simple and just uses regex to pick out the text and tags.

[klesun]

Hi. @bmewburn, if you did not decide on format yet, would you mind taking a look on the format deep-assoc-completion plugin uses in phpstorm?

Do you accept pull requests? I could write the phpdoc parser and add support for such format in your extension if you would like that ;-).

Upd.: I somewhat ported deep-assoc-completion to vscode. It's shipped as a separate extension, should work nicely together with intelephense.

[bmewburn]

@klesun, sorry for the late reply and thank you for your offer. For now I'd rather wait until some common standard emerges.

[klesun]

oh, ok (though I guess it will take quite some time...)

[panfiva]

@bmewburn, there is no common standard for PHP; however, there is a common standard for JSDoc that works well for majority of usecases - see @typedef tag (http://usejsdoc.org/tags-typedef.html).

An example of a definition using jsdoc syntax

/**

• @typedef Object Person
• @Property string Person[name] Person's name
• @Property string Person[address] Person's address
• @Property string Person[address][city] Person's address
  */

/**

• @var Person[] $person_array with SSN as key
  */

$person_array = array (
"493-11-1111"=> array("name"=>"John Doe", "address"=>array(city=>"Chicago"))},
"493-11-2222"=> array("name"=>"Jane Doe", "address"=>array(city=>"London"))},
);

[ADmad]

The phpdoc proposed PSR no longer shows the format initially showed by @hworld.

Pslam has become quite popular now and it's format is pretty nice, so my vote goes to that 🙂. I believe even phpstan is going to add / has added support for similar format.

[KapitanOczywisty]

Seems like psalm format is only sensible despite not being in PSR. JSDoc uses similar or the same format.

https://psalm.dev/docs/annotating_code/type_syntax/array_types/#object-like-arrays

[grezniczek]

Any updates on this? Thanks!

[benhickson]

I would appreciate this feature as well.

[driskell]

I've begun to use PHPStan which supports the same syntax, and at the moment some declarations cause problems because array<int, array{0:string}> seems to get interpreted by Intelliphense very weirdly and inside a loop the error is seeing the type of the individual items as \App\: string}.

Should I raise as a separate issue the faulty parsing? I would prefer Intelliphense to ignore something it doesn't understand 👍

[KapitanOczywisty]

This format is currently supported at least by psalm, phan and phpstan.

https://psalm.dev/docs/annotating_code/type_syntax/array_types/#object-like-arrays
https://phpstan.org/writing-php-code/phpdoc-types#array-shapes
https://github.com/phan/phan#features

PhpStorm supports ArrayShape: https://blog.jetbrains.com/phpstorm/2020/12/phpstorm-2020-3-release/#arrayshape and probably will support this syntax: https://youtrack.jetbrains.com/issue/WI-56038

@bmewburn Even If you're not planning to add feature this syntax should be at least ignored.

<?php

namespace Foo;

/** @var array<int, array{0:string}> */
$bar = [];
$x = $bar[0]; // @var \Foo\array{0:string} $x

@driskell can you provide minimal example to reproduce problem with loops?

[KapitanOczywisty]

And looks like ArrayShape from PhpStorm will not be pursued by mentioned tools:
https://psalm.dev/articles/php-8-attributes#not-currently-supported
phpstan/phpstan#4790 (comment)

Thus PHPDoc version will be probably the only one supported everywhere.

[KapitanOczywisty]

@driskell And I totally forgot about that, but PHPStan also supports own annotations like: @phpstan-return, so for now you need to add both original and prefixed one.

https://phpstan.org/writing-php-code/phpdocs-basics#prefixed-tags
https://github.com/phan/phan/wiki/Annotating-Your-Source-Code#aliases-of-phpdoc-annotations
https://psalm.dev/docs/annotating_code/supported_annotations/#psalm-var-psalm-param-psalm-return-psalm-property-psalm-property-read-psalm-property-write-psalm-method

[dmitrach]

Now array shapes are supported by PHPStorm: https://blog.jetbrains.com/phpstorm/2021/07/phpstorm-2021-2-release/#array_shapes_phpdoc_syntax_support

/**
  * @return array{foo: int, bar: string, typedObject: \Any\Type}
  */

 /**
   * @return array{ids: array, search_results: array}[]
   */

[kariae]

Any updates on this? Thanks!

[alielmajdaoui]

Any updates on this? Thanks!

[callmeteus]

Any updates on this? Thanks!

[DimNS]

the deep-assoc-completion-vscode plugin is no longer working ((

[klesun]

the deep-assoc-completion-vscode plugin is no longer working ((

Released a fix: v0.8.1

deep-assoc-completion now works in the latest vscode!

[callmeteus]

Definitely not working yet, even with the update :/
Even if hitting ctrl + space only gives me keywords from the document, not from the documentation comment itself

[klesun]

Definitely not working yet, even with the update :/ Even if hitting ctrl + space only gives me keywords from the document, not from the documentation comment itself

@theprometeus thanks for bringing that up, I released one more patch: v0.9.0 to address missing support for class functions.

The plugin is far from perfect, but I hope it still can be helpful.

[callmeteus]

Definitely not working yet, even with the update :/ Even if hitting ctrl + space only gives me keywords from the document, not from the documentation comment itself

@theprometeus thanks for bringing that up, I released one more patch: v0.9.0 to address missing support for class functions.

The plugin is far from perfect, but I hope it still can be helpful.

Don't say that, it's perfect as it is, and we all know the effort that is being putted in there.
It is working fine right now, thank you for the fix! This will save a lot of coding time :)

I'll also try to contribute with the development of the plugin when I have some free time.

[imReallyUnoriginal]

Any updates on this? Thanks!

[alielmajdaoui]

@theprometeus I think you can't contribute with the dev since Intelephense language server is proprietary! https://github.com/bmewburn/vscode-intelephense/#licence

You really can do nothing with open source client :p

[santigarcor]

I have a license of vscode-intelephense but this is not working even in that premium version. Any updates on this?

[Braunson]

Another license holder, any updates on this?

[kczx3]

Version 1.10 looks like it could be a good one!

[isaac-souza]

Looks like this won't get implemented :(

[kczx3]

@isaac-souza what makes you say that?

[isaac-souza]

@isaac-souza what makes you say that?

@kczx3 the original issue is from 2017, from the latest comments looks like it still didn't get implemented.

Please let me know if I'm wrong.

It would help me tremendous if it was available.

[alielmajdaoui]

@bmewburn as long as it's completed, any documentation how to use this feature?

[kczx3]

@alielmajdaoui

bmewburn as long as it's completed, any documentation how to use this feature?

The changelog has an example.

[WebCimes]

@bmewburnI just test like the example in the changelog, autocompletion seems to work inside the function:

But not outside the function:

It would be great if we can have some autocompletion when calling the function.

[seebeen]

+1