Enhance PHP compatibility and structure for WP_REST_Blocks

[spacedmonkey]

Overview

This PR modernizes the WP REST Blocks plugin with significant improvements to PHP compatibility, code structure, development tooling, and CI/CD workflows. It updates the minimum PHP version, refactors the codebase to use modern OOP practices, and enhances the development and testing infrastructure.

🔄 Breaking Changes

PHP Version Requirements

• Minimum PHP version increased from 7.0 to 7.4
• WordPress minimum version updated from 5.5 to 5.9
• Updated compatibility testing to PHP 8.0-8.4 (with 8.5 experimental support)
• PHPCS now checks for PHP 7.3+ compatibility

Dependency Changes

• Replaced tburry/pquery with imangazaliev/didom for better HTML parsing
• This change provides more robust DOM manipulation and better error handling

🏗️ Code Structure Improvements

Refactored to Object-Oriented Architecture

• Converted from functional to class-based architecture
• Added namespace: WP_REST_Blocks
• Introduced three main classes:
  • Data - Core block data processing and attribute extraction
  • Posts - REST API fields for post types with block editor support
  • Widgets - REST API fields for widgets with block content
• Added PSR-4 autoloading in composer.json

File Reorganization

• Renamed files to follow PSR-4 conventions:
  • src/data.php → src/Data.php
  • src/posts.php → src/Posts.php
  • src/widgets.php → src/Widgets.php
• Added PHP strict types declarations to all new classes

🧪 Testing & Development Infrastructure

Modern Testing Environment

• Migrated from custom bash scripts to @wordpress/env for local development
• Added .wp-env.json configuration file
• Removed deprecated bin/install-wp-tests.sh script
• Tests now run in Docker containers with proper WordPress setup
• Added Node.js 20.19.0 as the standard version (.nvmrc)

Enhanced Test Configuration

• Updated phpunit.xml.dist with coverage reporting
• Added coverage HTML output directory
• Improved test suite naming and organization
• Tests now support both single-site and multisite configurations

New npm Scripts

• npm run env:start - Start WordPress development environment
• npm run env:stop - Stop the environment
• npm run env:reset - Clean and restart environment
• npm run env:destroy - Completely remove environment
• npm run test:php - Run PHPUnit tests in wp-env
• npm run test:php:multisite - Run multisite tests
• npm run test:php:watch - Watch mode for tests
• npm run make-pot - Generate translation files
• npm run wp / npm run wp:tests - Run WP-CLI commands

🔍 Code Quality Tools

New Development Tools

• PHPStan (Level 5) - Static analysis with WordPress extensions
  • Added phpstan.neon.dist configuration
  • Includes strict rules and deprecation checks
  • WordPress-specific rules via szepeviktor/phpstan-wordpress
• PHPMD (PHP Mess Detector)
  • Added phpmd.xml.dist configuration
  • Checks for code smells, complexity, and unused code
• Composer Normalize - Ensures consistent composer.json formatting

New Composer Scripts

• composer phpstan - Run static analysis
• composer phpmd - Run mess detector
• composer normalize - Normalize composer.json

🚀 CI/CD Workflow Improvements

New GitHub Actions Workflows

1. Reusable PHP Lint Workflow (.github/workflows/reusable-php-lint.yml)

• Centralized linting logic for consistency
• Configurable checks: PHPCS, PHPStan, PHPMD, Composer normalize
• Can be called from other workflows

2. Security Scanning (.github/workflows/security.yml)

• Dependency vulnerability scanning with GitHub's Dependency Review
• Composer security audit
• Runs weekly and on pull requests

3. Workflow Validation (.github/workflows/validate-workflows.yml)

• Validates GitHub Actions workflows using actionlint
• Catches syntax errors and best practice violations

Updated Workflows

PHP Lint (continuous-integration-lint-php.yml)

• Now uses reusable workflow
• Simplified from 32 lines to 11 lines
• Added concurrency control to cancel outdated runs

Unit Tests (test-unit-php.yml)

• Complete rewrite using wp-env and Docker
• Removed MariaDB service configuration
• Added PHP matrix: 7.4, 8.0, 8.1, 8.2, 8.3, 8.4
• Experimental PHP 8.5 support
• Tests against WordPress 5.9.1 (stable) and master (experimental)
• Proper cleanup with npm run env:stop

Deploy to WordPress.org (deploytowp.yml)

• Uses new shared setup-php-composer action
• Updated checkout action to v4
• Improved output variable handling

Upload Release Assets (upload-asset-on-release.yml)

• Switched to softprops/action-gh-release@v2
• Simplified asset upload process
• Better error handling with fail_on_unmatched_files

Update Assets (upateassets.yml)

• Updated checkout action to v4
• Added explicit permissions

New Composite Action

• .github/actions/setup-php-composer/action.yml
  • Reusable action for PHP and Composer setup
  • Handles Composer cache automatically
  • Configurable PHP version, tools, extensions
  • Used across multiple workflows for consistency

Workflow Enhancements

• Added concurrency groups to prevent multiple runs
• Added explicit permissions declarations for security
• All workflows use actions/checkout@v4
• Better caching strategies with actions/cache@v4

Dependabot Configuration

• Enhanced with GitHub Actions monitoring
• Added scheduled updates for all ecosystems (weekly on Mondays)
• Consistent commit message prefixes: chore(deps)
• Better organization with proper scoping

📚 Documentation

Updated README

• Added comprehensive Development section with:
  • Prerequisites (Node.js, Docker)
  • Setup instructions
  • Available commands reference
  • Testing instructions
  • Local environment access details
• Updated minimum requirements (PHP 7.4, WordPress 5.9)
• Better structured with clear sections

🛠️ Composer Dependencies

Added Development Dependencies

• ergebnis/composer-normalize ^2.48
• imangazaliev/didom ^2.0
• phpmd/phpmd ^2.15
• phpstan/extension-installer ^1.4
• phpstan/phpstan ^2.1
• phpstan/phpstan-deprecation-rules ^2.0
• phpstan/phpstan-strict-rules ^2.0
• swissspidy/phpstan-no-private ^1.0
• szepeviktor/phpstan-wordpress ^2.0

Updated Configuration

• Added PSR-4 autoloading for WP_REST_Blocks namespace
• Allowed new Composer plugins (normalize, PHPStan installer)

📦 Build & Distribution

Updated .distignore

• Added wp-env files: .wp-env.json, .wp-env.override.json, .wp-env-home

Updated .gitignore

• Added coverage-html/ for PHPUnit coverage reports
• Added .wp-env-home/ for local wp-env data
• Added .wp-env.override.json for local overrides
• Added .phpunit.result.cache for faster test runs

🗑️ Removed Files

• Gruntfile.js - Replaced with npm scripts and wp-env
• bin/install-wp-tests.sh - Replaced with wp-env

🔧 Configuration Updates

PHPCS (.phpcs.xml.dist)

• Updated text domain configuration format
• Changed PHP compatibility check from 7.0+ to 7.3+
• Better XML structure for properties

PHPUnit (phpunit.xml.dist)

• Added test suite name: "Plugin"
• Added coverage configuration with HTML and text reports
• Better coverage inclusion/exclusion patterns

📈 Impact Summary

• 35 files changed: 23,225 additions, 12,125 deletions
• Modern development workflow with Docker
• Improved code quality with static analysis
• Enhanced security with automated scanning
• Better CI/CD with reusable workflows
• Cleaner, more maintainable codebase

🧪 Testing

All tests pass with the new structure:

• ✅ Single-site tests
• ✅ Multisite tests
• ✅ PHPCS checks
• ✅ PHPStan analysis
• ✅ PHPMD checks
• ✅ Security audits