Modernize the parser onto php-parser 5 + reflection-docblock 6 (PHP 8.2)

.github/workflows/unit-test.yml

@@ -12,7 +12,9 @@ jobs:
           fail-fast: false
           matrix:
               php:
-                - '7.4'
+                - '8.2'
+                - '8.3'
+                - '8.4'
 
       env:
         WP_ENV_PHP_VERSION: ${{ matrix.php }}
@@ -25,9 +27,7 @@ jobs:
         run: npm install
 
       - name: Setup Environment
-        run: |
-          rm composer.lock
-          npm run setup
+        run: npm run setup
 
       - name: Test
         run: npm run test

.gitignore

@@ -1,3 +1,4 @@
 vendor
 coverage
 node_modules
+.phpunit.result.cache

.wp-env.json

@@ -1,7 +1,6 @@
 {
-  "phpVersion": "7.4",
+  "phpVersion": "8.2",
   "plugins": [
-    ".",
-    "https://downloads.wordpress.org/plugin/posts-to-posts.latest-stable.zip"
+    "."
   ]
 }

bin/generate-golden-docker.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+#
+# Regenerate the golden-master snapshots on PHP 7.4 — the last PHP version the old
+# parser (phpdocumentor/reflection ~3.0 + nikic/php-parser 1.x) runs on cleanly.
+# On PHP 8.x that stack emits a flood of deprecations/warnings and produces
+# unreliable output, so the baseline MUST be captured on 7.4.
+#
+# Reuses the host's already-installed vendor/ (pure PHP, version-agnostic), so no
+# Composer or build tooling is needed inside the container.
+#
+# Prereq:  composer install --no-dev      # installs the OLD locked parser stack
+# Usage:   bin/generate-golden-docker.sh
+#
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+if [ ! -f vendor/phpdocumentor/reflection/composer.json ]; then
+	echo "ERROR: old parser not installed. Run: composer install --no-dev" >&2
+	exit 1
+fi
+
+exec docker run --rm \
+	-u "$(id -u):$(id -g)" -e HOME=/tmp \
+	-v "$PWD":/app -w /app \
+	php:7.4-cli php bin/generate-golden.php

bin/generate-golden.php

@@ -0,0 +1,50 @@
+<?php
+/**
+ * Generate golden-master snapshots from the CURRENT parser.
+ *
+ * Run this ONCE on the OLD stack (PHP 7.4 + phpdocumentor/reflection ~3.0) to
+ * capture the baseline oracle, then commit tests/golden/snapshots/. After the
+ * rewrite, the PHPUnit golden test (tests/golden/test-golden-master.php) replays
+ * the same corpus through the modern parser and asserts it still matches.
+ *
+ * Do NOT regenerate against the new parser — that would defeat the oracle. The
+ * snapshots are a frozen record of the old behavior. See tests/golden/README.md
+ * for the Docker recipe that produces a clean PHP 7.4 environment.
+ *
+ * Usage:  php bin/generate-golden.php
+ *
+ * @package WP_Parser\Golden
+ */
+
+$repo = dirname( __DIR__ );
+
+if ( ! file_exists( $repo . '/vendor/autoload.php' ) ) {
+	fwrite( STDERR, "ERROR: vendor/ is not installed. Run `composer install` first.\n" );
+	exit( 1 );
+}
+
+require $repo . '/vendor/autoload.php';
+require $repo . '/tests/golden/golden.php';
+
+$snapshots = \WP_Parser\Golden\snapshots_dir();
+if ( ! is_dir( $snapshots ) && ! mkdir( $snapshots, 0777, true ) && ! is_dir( $snapshots ) ) {
+	fwrite( STDERR, "ERROR: could not create {$snapshots}\n" );
+	exit( 1 );
+}
+
+$corpus = \WP_Parser\Golden\corpus();
+if ( ! $corpus ) {
+	fwrite( STDERR, "ERROR: empty corpus — no fixtures found under tests/.\n" );
+	exit( 1 );
+}
+
+$count = 0;
+foreach ( $corpus as $slug => $entry ) {
+	$json = \WP_Parser\Golden\to_json( \WP_Parser\Golden\parse_entry( $entry ) );
+	file_put_contents( \WP_Parser\Golden\snapshot_path( $slug ), $json );
+	printf( "  wrote %-32s %6d bytes\n", $slug, strlen( $json ) );
+	$count++;
+}
+
+printf( "\nDone. %d snapshot(s) written to %s\n", $count, $snapshots );
+printf( "PHP %s | php-parser/reflection as installed in vendor/\n", PHP_VERSION );

composer.json

@@ -20,18 +20,21 @@
 		"issues": "https://github.com/WordPress/phpdoc-parser/issues"
 	},
 	"require"    : {
-		"php"                      : ">=5.4",
-		"composer/installers"      : "~1.0",
-		"phpdocumentor/reflection" : "~3.0",
+		"php"                      : ">=8.2",
+		"composer/installers"      : "^1.0 || ^2.0",
+		"nikic/php-parser"         : "^5.0",
+		"phpstan/phpdoc-parser"    : "^2.0",
+		"phpdocumentor/reflection-docblock": "^6.0",
+		"phpdocumentor/type-resolver"      : "^2.0",
 		"erusev/parsedown"         : "~1.7",
 		"scribu/lib-posts-to-posts": "dev-master@dev",
 		"scribu/scb-framework"     : "dev-master@dev",
 		"psr/log"                  : "~1.0"
 	},
 	"require-dev" : {
-		"phpunit/phpunit": "^7",
+		"phpunit/phpunit": "^9",
 		"spatie/phpunit-watcher": "^1.23",
-		"yoast/phpunit-polyfills": "^1.0"
+		"yoast/phpunit-polyfills": "^2.0"
 	},
 	"scripts"    : {
 		"test": "phpunit",
@@ -43,6 +46,9 @@
 		"files"   : ["lib/runner.php", "lib/template.php"]
 	},
 	"config": {
+		"platform": {
+			"php": "8.2"
+		},
 		"allow-plugins": {
 			"composer/installers": true
 		},