Generate array shapes for PHPStan

[johnbillion]

Work in progress. Fixes #15.

This converts the array hash notation that WordPress uses into an array shape that PHPStan understands, and appends a @phpstan-param tag for it to the docblock of the generated stub. It's fault tolerant so any incorrectly formatted array hashes should simply be ignored.

Todo:

• @param
• @return
• Investigate whether elements in @phpstan-return tags should be optional
• Investigate handling elements in @param marked as "Required"

I tried to add handling for "Required" and "Optional" elements but core isn't consistent enough with its documentation and there aren't many anyway. Not worth worrying about in my opinion.

When the stubs are generated this adds:

• 231 @phpstan-param tags
• 65 @phpstan-return tags

Example:

* @param array|string $args {
*     Optional. Array or string of arguments for installing a package. Default empty array.
*
*     @type string $source                      Required path to the package source. Default empty.
*     @type string $destination                 Required path to a folder to install the package in.
*                                               Default empty.
*     @type bool   $clear_destination           Whether to delete any files already in the destination
*                                               folder. Default false.
*     @type bool   $clear_working               Whether to delete the files form the working directory
*                                               after copying to the destination. Default false.
*     @type bool   $abort_if_destination_exists Whether to abort the installation if
*                                               the destination folder already exists. Default true.
*     @type array  $hook_extra                  Extra arguments to pass to the filter hooks called by
*                                               WP_Upgrader::install_package(). Default empty array.
* }
* @phpstan-param array{
*   source?: string,
*   destination?: string,
*   clear_destination?: bool,
*   clear_working?: bool,
*   abort_if_destination_exists?: bool,
*   hook_extra?: array,
* } $args

[szepeviktor]

Thank you for your work, John!
Please add PHPStan to test this code.

[johnbillion]

I've done that locally as part of my testing but there are several errors that need ignoring. I'll carry on with this later this week.

[szepeviktor]

there are several errors that need ignoring.

That was a misunderstanding. Check only working PHP source code :)

[johnbillion]

Ah sorry what I meant was I was using PHPStan to validate the generated array shapes (to check to syntax errors etc) and as part of that testing I had to ignore other unrelated errors.

[szepeviktor]

using PHPStan to validate the generated array shapes

That is a valid point but there is no way in PHPStan to pick-and-choose source code parts.

[szepeviktor]

This PR is about us going to WordPress but WordPress should come to its senses!
@type is an archaic remnant.

[johnbillion]

Yeah I would prefer it if WordPress used a more widely used syntax but its array hash notation does have one advantage over the syntax used by PHPStan in that each array element supports a description which is very useful when reading the code.

[szepeviktor]

each array element supports a description

I knew you support noobs!!

[szepeviktor]

Green to go 🟢 now that we have php-stubs/generator#5

[szepeviktor]

Thank you John for your work. I think it is ready to merge.
It'll be merged when WP core 5.9 will be released.

Have you tested some of your projects with these array shapes?

[johnbillion]

Yeah I've been testing this, mostly the functions with new @phpstan-param tags. As all their array elements are optional it just helps with incorrect types and not much else, so these are safe to add.

I should do some more testing of the functions that now include @phpstan-return tags because I've not tested those much.

[johnbillion]

I checked all the @phpstan-return tags and they're all good 👍