Error regenerating doc pages

[ernilambar]

Bug Report

• [x] Yes, I reviewed the contribution guidelines.
• [x] Yes, more specifically, I reviewed the guidelines on how to write clear bug reports.

Describe the current, buggy behavior

When I follow the steps given in https://github.com/wp-cli/handbook#wp-clihandbook there are lots of PHP notices and warnings. All the files in the internal-api are deleted.

Describe how other contributors can replicate this bug

• wp cli update --nightly
• bin/install_packages.sh
• WP_CLI_SUPPRESS_GLOBAL_PARAMS=false WP_CLI_PACKAGES_DIR=bin/packages WP_CLI_CONFIG_PATH=/dev/null wp handbook gen-all

Describe what you would expect as the correct outcome

Pages should be regenerated properly.

Let us know what environment you are running this on

OS:     Darwin 22.6.0 Darwin Kernel Version 22.6.0: Tue Nov  7 21:48:06 PST 2023; root:xnu-8796.141.3.702.9~2/RELEASE_X86_64 x86_64
Shell:  /bin/zsh
PHP binary:     /usr/local/Cellar/php@8.2/8.2.18/bin/php
PHP version:    8.2.18
php.ini used:   /usr/local/etc/php/8.2/php.ini
MySQL binary:   /usr/local/mysql-8.0.36-macos14-x86_64/bin/mysql
MySQL version:  mysql  Ver 8.0.36 for macos14 on x86_64 (MySQL Community Server - GPL)
SQL modes:
WP-CLI root dir:        phar://wp-cli.phar/vendor/wp-cli/wp-cli
WP-CLI vendor dir:      phar://wp-cli.phar/vendor
WP_CLI phar path:       /Users/nilambarsharma/Code/kli/handbook
WP-CLI packages dir:    /Users/nilambarsharma/.wp-cli/packages/
WP-CLI cache dir:       /Users/nilambarsharma/.wp-cli/cache
WP-CLI global config:
WP-CLI project config:  /Users/nilambarsharma/Code/kli/handbook/wp-cli.yml
WP-CLI version: 2.11.0-alpha-c661c45

Provide additional context/Screenshots

...
PHP Warning:  Undefined array key 1 in /Users/nilambarsharma/Code/kli/handbook/bin/command.php on line 623
PHP Warning:  Undefined array key 1 in /Users/nilambarsharma/Code/kli/handbook/bin/command.php on line 623
PHP Warning:  Undefined array key 1 in /Users/nilambarsharma/Code/kli/handbook/bin/command.php on line 623
PHP Warning:  Undefined array key 1 in /Users/nilambarsharma/Code/kli/handbook/bin/command.php on line 623
PHP Warning:  Undefined array key 1 in /Users/nilambarsharma/Code/kli/handbook/bin/command.php on line 623
PHP Warning:  Undefined array key 1 in /Users/nilambarsharma/Code/kli/handbook/bin/command.php on line 623
PHP Warning:  Undefined array key 1 in /Users/nilambarsharma/Code/kli/handbook/bin/command.php on line 623
PHP Warning:  foreach() argument must be of type array|object, null given in /Users/nilambarsharma/Code/kli/handbook/bin/command.php on line 78

Warning: foreach() argument must be of type array|object, null given in /Users/nilambarsharma/Code/kli/handbook/bin/command.php on line 78
Removed existing contents of '/Users/nilambarsharma/Code/kli/handbook/internal-api/'
Success: Generated internal-api/
Removed existing contents of '/Users/nilambarsharma/Code/kli/handbook/commands/'
Success: Generated all command pages.
Success: Generated bin/commands-manifest.json of 423 commands
Success: Generated bin/handbook-manifest.json
Success: Generated all doc pages.

[ernilambar]

I dug little deep into this issue. Our main issue here starts from the handbook api-dump command. There are lots of PHP notices in the command output. So the result is not partiucularly valid JSON output. Output of this command is used in gen-all command. This gen-all deletes the internal-api folder and tries to regenerate all markdown file but could not due to invalid JSON result from the above function.

Error is coming around this line - https://github.com/wp-cli/handbook/blob/main/bin/command.php#L622

preg_match( '/@(\w+)/', $info, $matches );
$param_name = $matches[1];

We have assumed here that there will always be match and $matches[1] is used directly without conditional. So, I am not sure since when this error started.

I checked the git blame but it seems these lines have not been changed since 7 years.

Also in public function gen_api_docs() method, we have assumed that the output of the command is always valid JSON and used directly. May be we need some sanity check in this method also.

Aside: We really need to add some tests here in this repo.

[ernilambar]

My bad. Error was introduced in this PR https://github.com/wp-cli/handbook/pull/506

PR https://github.com/wp-cli/handbook/pull/520 should fix the issue.