Any good solution for WP array shapes not being recognized by PHPStan?

[mundschenk-at]

Is there currently any good solution (other than disabling the warning) for PHPStan not recognizing WordPress Documentation Standards array shape definitions?

@param array {
    Some description.

   @type int    $foo Some parameter description.
   @type string $bar Some other parameter description.
}

[szepeviktor]

Guten Tag @mundschenk-at!! 👋🏻

We are doing that over at WordPress core stubs. https://github.com/php-stubs/wordpress-stubs/blob/df4eef79b6a7f835e9c31a75e7ef1f513a0cb03d/visitor.php#L814-L821 But it works during parsing with nikic/php-parser.

So

1. parse original WP-style code
2. insert @phpstan-param array{ ... } tags
3. use it in static analysis

That's it!

[szepeviktor]

💡 BTW "WordPress Documentation Standards" is not a standard. (no one else in the World follows it)

[mundschenk-at]

💡 BTW "WordPress Documentation Standards" is not a standard. (no one else in the World follows it)

Please don't preach. It is a standard within the WordPress ecosystem, which as far WordPress plugins are concerned, matters more than adoption in the wider PHP community.

[szepeviktor]

Okay-okay. Sorry. I'm just very angry for me being part of this ecosystem.

[mundschenk-at]

So

1. parse original WP-style code
2. insert @phpstan-param array{ ... } tags
3. use it in static analysis

That's it!

How would I integrate this solution into a PHStan check? I really don't want to statically insert additional tags that simply mirror existing information in another format. I'm fine with an additional preprocessing step that can be automated from e.g. a composer script (or a GitHub action, though I'd prefer being able to continue to run all checks locally).

[mundschenk-at]

Okay-okay. Sorry. I'm just very angry for me being part of this ecosystem.

That I can understand very well. It's why I have been neglecting my plugins, because project leadership & lack of governance continues to disappoint.

[szepeviktor]

Yes! Develop a tiny tool that inserts @phpstan-param tags based on the above linked file then run it just before static analysis in your CI workflow.

[mundschenk-at]

OK, I see. So there is no existing tooling. I fear that creating that will be beyond the time I am currently willing to spare on WordPress stuff.

[szepeviktor]

creating that

I would very much star ⭐ that project of yours!

[mundschenk-at]

Come to think about this, wouldn't this be a good addition for this extension? It already does something similar for hook @param tags, no?

[szepeviktor]

I think that phpstan-wordpress in its current form is a space 👨🏻‍🚀 age tool for WordPress developers.

[johnbillion]

The php-stubs/wordpress-stubs package converts WordPress syntax into PHPStan syntax here: https://github.com/php-stubs/wordpress-stubs/blob/df4eef79b6a7f835e9c31a75e7ef1f513a0cb03d/visitor.php#L641-L645 . Ideally that code should be moved from php-stubs/wordpress-stubs to php-stubs/generator so it can be used by packages other than WordPress core.