Modernize parser to PHP 8.1+ with phpstan/phpdoc-parser

.github/workflows/import-test.yml

@@ -0,0 +1,90 @@
+name: Import Test
+
+on:
+  pull_request:
+  push:
+    branches: [ master ]
+  workflow_dispatch:
+
+jobs:
+  test-import:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        php:
+          - '8.1'
+          - '8.2'
+          - '8.3'
+          - '8.4'
+
+    env:
+      WP_ENV_PHP_VERSION: ${{ matrix.php }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+
+      - name: Install
+        run: npm ci
+
+      - name: Setup Environment
+        run: |
+          npm run setup
+
+      - name: Wait for WordPress to be ready
+        run: |
+          timeout 60 bash -c 'until curl -s http://localhost:8888 > /dev/null; do sleep 2; done'
+
+      - name: Activate plugins
+        run: |
+          npm run wp-env run cli -- -- wp plugin activate phpdoc-parser posts-to-posts
+
+      - name: Run sample import (subset of files)
+        run: |
+          # Import a small subset of WordPress core files for testing
+          npm run wp-env run cli -- -- wp parser create /var/www/html/wp-includes/functions.php --user=admin
+
+      - name: Verify import worked
+        run: |
+          # Check that functions were imported
+          FUNCTION_COUNT=$(npm run wp-env run cli -- -- wp post list --post_type=wp-parser-function --format=count | tail -1)
+          echo "Functions imported: $FUNCTION_COUNT"
+
+          if [ "$FUNCTION_COUNT" -lt 50 ]; then
+            echo "ERROR: Expected at least 50 functions, got $FUNCTION_COUNT"
+            exit 1
+          fi
+
+      - name: Verify taxonomy terms
+        run: |
+          # Check that taxonomy terms are properly assigned
+          FILE_TERMS=$(npm run wp-env run cli -- -- wp term list wp-parser-source-file --format=count | tail -1)
+          echo "File taxonomy terms: $FILE_TERMS"
+
+          if [ "$FILE_TERMS" -eq 0 ]; then
+            echo "ERROR: No file taxonomy terms found"
+            exit 1
+          fi
+
+      - name: Test parser command with error detection
+        run: |
+          # Run parser and capture both stdout and stderr
+          if ! npm run wp-env run cli -- -- wp parser create /var/www/html/wp-includes/class-wp.php --user=admin 2>&1 | tee import_output.log; then
+            echo "ERROR: Parser command failed"
+            exit 1
+          fi
+
+          # Check for PHP warnings or errors in output
+          if grep -i "warning\|error\|fatal" import_output.log | grep -v "WP_CLI"; then
+            echo "ERROR: PHP warnings or errors detected in parser output"
+            cat import_output.log
+            exit 1
+          fi

.github/workflows/unit-test.yml

@@ -3,6 +3,7 @@ name: Unit Tests
 on:
   pull_request:
   push:
+    branches: [ master ]
   workflow_dispatch:
 
 jobs:
@@ -12,7 +13,10 @@ jobs:
           fail-fast: false
           matrix:
               php:
-                - '7.4'
+                - '8.1'
+                - '8.2'
+                - '8.3'
+                - '8.4'
 
       env:
         WP_ENV_PHP_VERSION: ${{ matrix.php }}
@@ -21,12 +25,17 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+
       - name: Install
-        run: npm install
+        run: npm ci
 
       - name: Setup Environment
         run: |
-          rm composer.lock
           npm run setup
 
       - name: Test

.gitignore

@@ -1,3 +1,5 @@
 vendor
 coverage
 node_modules
+.phpunit.result.cache
+composer.lock

.npmrc

@@ -0,0 +1 @@
+engine-strict=true

.nvmrc

@@ -0,0 +1 @@
+20

.wp-env.json

@@ -1,5 +1,9 @@
 {
-  "phpVersion": "7.4",
+  "phpVersion": "8.3",
+  "config": {
+    "WP_DEBUG": false,
+    "WP_DEBUG_DISPLAY": false
+  },
   "plugins": [
     ".",
     "https://downloads.wordpress.org/plugin/posts-to-posts.latest-stable.zip"

CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing
+
+Thank you for your interest in contributing to WP Parser!
+
+## Setup
+
+This project uses wp-env to provide a containerised test environment. You should manage the environement and run the tests using the npm commands.
+
+```bash
+# Prerequisites: Node.js 20+, Docker Desktop
+git clone https://github.com/your-username/phpdoc-parser.git
+cd phpdoc-parser
+npm install
+npm run setup  # First time only
+npm run test   # Run tests
+```
+
+## Stop containers when done
+
+```
+npm run wp-env stop
+```
+
+## Architecture
+
+```
+lib/
+├── class-file-reflector.php  # Main AST parser
+├── class-hook-reflector.php  # WordPress hooks
+├── runner.php                # API compatibility
+└── class-importer.php        # WordPress posts
+```
+
+WP Parser uses PHPParser for AST traversal and phpstan/phpdoc-parser for PHPDoc.

README.md

@@ -7,26 +7,29 @@ We are currently looking for contributors to help us complete the work on the pa
 There is a guide to developing for developer.wordpress.org in the [WordPress documentation handbook](https://make.wordpress.org/docs/handbook/projects/devhub/)
 
 ## Requirements
-* PHP 5.4+
-* [Composer](https://getcomposer.org/)
-* [WP CLI](https://wp-cli.org/)
+
+* **PHP 8.1+**
+* **Node.js 20+** and **npm 9+** (for development environment)
+* **Docker** (for wp-env testing environment)
+* **Composer**
+
+## Quick Start
 
 Clone the repository into your WordPress plugins directory:
 
 ```bash
 git clone https://github.com/WordPress/phpdoc-parser.git
+cd phpdoc-parser
 ```
 
-After that install the dependencies using composer in the parser directory:
+After that install the dependencies:
 
 ```bash
-composer install
+npm install
+npm run setup
 ```
 
 ## Running
-Activate the plugin first:
-
-    wp plugin activate phpdoc-parser
 
 In your site's directory:
 

composer.json

@@ -20,16 +20,14 @@
 		"issues": "https://github.com/WordPress/phpdoc-parser/issues"
 	},
 	"require"    : {
-		"php"                      : ">=5.4",
-		"composer/installers"      : "~1.0",
-		"phpdocumentor/reflection" : "~3.0",
-		"erusev/parsedown"         : "~1.7",
-		"scribu/lib-posts-to-posts": "dev-master@dev",
-		"scribu/scb-framework"     : "dev-master@dev",
-		"psr/log"                  : "~1.0"
+		"php"                      : ">=8.1",
+		"composer/installers"      : "~2.0",
+		"phpstan/phpdoc-parser"    : "^2.0",
+		"nikic/php-parser"         : "^5.0",
+		"psr/log"                  : "^2.0|^3.0"
 	},
 	"require-dev" : {
-		"phpunit/phpunit": "^7",
+		"phpunit/phpunit": "^9",
 		"spatie/phpunit-watcher": "^1.23",
 		"yoast/phpunit-polyfills": "^1.0"
 	},