Merge pull request #1250 from WordPress/961-check-wordpress-functions-are-compatible-with-wordpress-version

Add `wp_functions_compatibility` check with generated WordPress function `@since` dataset

Co-authored-by: davidperezgar <davidperez@git.wordpress.org>
Co-authored-by: ernilambar <nilambar@git.wordpress.org>
Co-authored-by: frantorres <frantorres@git.wordpress.org>

Author: 4 people

.github/workflows/generate-wp-functions-since-data.yml

@@ -0,0 +1,46 @@
+name: Generate WP Functions Since Data
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 5 * * 1'
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout plugin-check
+        uses: actions/checkout@v4
+
+      - name: Checkout WordPress core
+        uses: actions/checkout@v4
+        with:
+          repository: WordPress/WordPress
+          path: wordpress-core
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+
+      - name: Generate dataset
+        run: |
+          php tools/generate-wp-function-since-data.php \
+            --wordpress-dir=wordpress-core \
+            --output=includes/Vars/wp-functions-since.json
+
+      - name: Create pull request with updated dataset
+        uses: peter-evans/create-pull-request@v7
+        with:
+          branch: codex/update-wp-functions-since-data
+          commit-message: 'Update WordPress function since dataset'
+          title: 'Update WordPress function since dataset'
+          body: |
+            Automated update for `includes/Vars/wp-functions-since.json`.
+          add-paths: |
+            includes/Vars/wp-functions-since.json

.typos.toml

@@ -6,6 +6,7 @@ extend-ignore-re = [
     "setted_site_transient",
     "setted_transient",
     "stati",
+    "url_is_accessable_via_ssl",
     "wheres",
 ]
 

composer.json

@@ -74,6 +74,7 @@
     "lint": "phpcs --standard=phpcs.xml.dist",
     "phpmd": "phpmd . text phpmd.xml",
     "phpstan": "phpstan analyse --memory-limit=2048M",
+    "generate-wp-functions-since-data": "php tools/generate-wp-function-since-data.php --wordpress-dir=../../../ --output=includes/Vars/wp-functions-since.json",
     "prepare-behat-tests": "install-package-tests",
     "test": "phpunit"
   },
@@ -84,7 +85,8 @@
     "lint": "Detect coding standards issues",
     "phpmd": "Run PHP mess detector",
     "phpstan": "Run static analysis",
+    "generate-wp-functions-since-data": "Generate the WordPress function @since dataset used by wp_functions_compatibility check",
     "prepare-behat-tests": "Prepare functional tests",
     "test": "Run unit tests"
   }
-}
+}

docs/README.md

@@ -4,6 +4,7 @@
 * [Creating a Static Check](creating-a-static-check.md)
 * [Creating a Runtime Check](creating-a-runtime-check.md)
 * [Available Checks](checks.md)
+* [WordPress Functions Compatibility Data](wp-functions-compatibility-data.md)
 * [CLI Commands](CLI.md)
 * [Running Unit tests](running-unit-tests.md)
 * [Releasing a New Version of Plugin](releasing.md)

docs/checks.md

@@ -15,6 +15,7 @@
 | plugin_updater | plugin_repo | Prevents altering WordPress update routines or using custom updaters, which are not allowed on WordPress.org. | [Learn more](https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/) |
 | plugin_uninstall | plugin_repo | Checks related to plugin uninstallation. | [Learn more](https://developer.wordpress.org/plugins/plugin-basics/uninstall-methods/#method-2-uninstall-php) |
 | external_admin_menu_links | plugin_repo | Detects external URLs used in top-level WordPress admin menu, which disrupts the expected user experience. | [Learn more](https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/#11-plugins-should-not-hijack-the-admin) |
+| wp_functions_compatibility | plugin_repo | Checks whether WordPress functions used by the plugin are compatible with the declared minimum supported WordPress version ("Requires at least"). | [Learn more](https://developer.wordpress.org/plugins/plugin-basics/header-requirements/#header-fields) |
 | plugin_review_phpcs | plugin_repo | Runs PHP_CodeSniffer to detect certain best practices plugins should follow for submission on WordPress.org, including heredoc usage detection. | [Learn more](https://developer.wordpress.org/plugins/plugin-basics/best-practices/) |
 | direct_db_queries | security, plugin_repo | Checks the usage of direct database queries, which should be avoided. | [Learn more](https://developer.wordpress.org/apis/database/) |
 | direct_db | security, plugin_repo | Checks the escaping in direct database queries. | [Learn more](https://developer.wordpress.org/apis/database/) |

docs/wp-functions-compatibility-data.md

@@ -0,0 +1,34 @@
+# WordPress Functions Compatibility Data
+
+The `wp_functions_compatibility` check uses a generated dataset:
+
+- `includes/Vars/wp-functions-since.json`
+
+That file maps WordPress function names to the WordPress version where they were introduced (`@since`).
+The check compares those versions with the plugin's minimum supported WordPress version (`Requires at least`).
+
+## Regenerate Locally
+
+From this plugin root:
+
+```bash
+php tools/generate-wp-function-since-data.php \
+  --wordpress-dir=/absolute/path/to/wordpress \
+  --output=includes/Vars/wp-functions-since.json
+```
+
+Example for this repository's standard local layout:
+
+```bash
+php tools/generate-wp-function-since-data.php \
+  --wordpress-dir=../../../ \
+  --output=includes/Vars/wp-functions-since.json
+```
+
+## Automation
+
+The GitHub workflow:
+
+- `.github/workflows/generate-wp-functions-since-data.yml`
+
+regenerates this file on a schedule and via manual dispatch, and opens a pull request when the dataset changes.