Compatibility updates required

[dd32]

This package / library / plugin is severely outdated, and no longer operates correctly on PHP 8.1.
I believe this library needs a fundamental rewrite.

Unfortunately the main dependency of it, "phpdocumentor/reflection" : "~3.0", (PHP 5.3.3+) has made several rewrites of the library in v4, v5, and v6. https://github.com/phpDocumentor/Reflection/releases
Additionally, v5.2 supported PHP >=7.2 (PHP8 support unknown), but v5.3 requires PHP 7.4/8.x, and v6 is PHP 8.1+ only.

I have previously gone done this path, and there's some changes here, but I have no recollection of the status or whether it worked / etc. master...dd32:phpdoc-parser:try/upgrade-phpdocumentor

If you incorrectly run the parser on the develop.svn checkout without specifying the src/ folder as the base to parse, it'll run into this error on PHP 7.4 + WP 6.5+, which I'm assuming is newer PHP syntax that the parser doesn't understand in the tests/ folder.

[28-Apr-2025 03:14:29 UTC] PHP Fatal error: Uncaught Error: Object of class PhpParser\Node\Stmt\Class_ could not be converted to string in /var/www/html/wp-content/plugins/phpdoc-parser/vendor/phpdocumentor/reflection/src/phpDocumentor/Reflection/BaseReflector.php:172

But even without tests/ included, parsing will often throw errors like Parse Error: Syntax error, unexpected '?', expecting T_VARIABLE on line 62 Parse Error: Syntax error, unexpected '?', expecting T_VARIABLE on line 127 and I have no idea what impact that is having :)

ref https://meta.trac.wordpress.org/ticket/7963 https://meta.trac.wordpress.org/ticket/7964

[dd32]

But even without tests/ included, parsing will often throw errors like Parse Error: Syntax error, unexpected '?', expecting T_VARIABLE on line 62 Parse Error: Syntax error, unexpected '?', expecting T_VARIABLE on line 127 and I have no idea what impact that is having :)

This does indeed cause an issue :)

As noted in https://meta.trac.wordpress.org/ticket/7963#comment:3 this is causing it to skip entire files, causing the documentation for any functions/classes/hooks/args in that file not to be updated. The source code listing also then becomes outdated linking to the improper code.

For example, parsing the entire checkout results in this:

{
     "file": {
        "description": "",
       "long_description": "",
       "tags": []
    },
  "path": "wp-includes\/media.php",
   "root": "\/core\/src"
},

Parsing just that file reveals the fatal:

npm run wp-env run cli wp parser export core/src/wp-includes/media.php export.json

Parse Error: Syntax error, unexpected '?', expecting T_VARIABLE on line 5710

That's this line: function wp_getimagesize( $filename, ?array &$image_info = null ) { - so PHP Nullable types, which was a PHP 7.1 feature, so it's not surprising that the PHP5.3-era parser is choking on it.

[johnbillion]

I think this is a dupe of #228.

See also wp-hooks/generator#19 for my implementation and some more thoughts (only handles hooks though).

It looks like a rewrite would be easier than trying to update phpDocumentor in place.

[dd32]

I think this is a dupe of #228.

I think you're right.

It looks like a rewrite would be easier than trying to update phpDocumentor in place.

That's more or less what I came to when I started updating it, I think, based on the history in the branch mentioned above.
It required fundamental changes to the parser which resulted in less than ideal implementation, since the basics of how the phpDocumentor library worked changed and no longer really matched our usage of it.