This commit is contained in:
Javier Casares 2026-01-30 18:51:40 +00:00
commit 443dceb8ca
48 changed files with 566609 additions and 230 deletions

View file

@ -0,0 +1,26 @@
# EditorConfig: https://editorconfig.org
root = true
[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
indent_style = space
indent_size = 4
trim_trailing_whitespace = true
[*.php]
indent_style = space
indent_size = 4
max_line_length = 120
[*.{json,yml,yaml,xml}]
indent_style = space
indent_size = 2
[Makefile]
indent_style = tab
[*.md]
trim_trailing_whitespace = false

View file

@ -0,0 +1 @@
* @eduardovillao

View file

@ -0,0 +1,27 @@
name: Lint & Test PHP Project
on: [pull_request]
jobs:
quality-checks:
name: Code Quality & Tests
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: "8.2"
tools: composer, phpunit, phpcs
- name: Install dependencies
run: composer install --no-interaction --prefer-dist
- name: Run PHPCS (PSR-12)
run: composer lint
- name: Run PHPUnit tests
run: composer tests:unit

View file

@ -0,0 +1,68 @@
name: Generate WP Since Map
on:
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout project
uses: actions/checkout@v4
- name: Install PHP depencencies
run: |
sudo apt-get update
sudo apt-get install -y php php-cli php-mbstring unzip curl
- name: Install Composer
run: |
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
- name: Install Composer dependencies
run: composer install
- name: Download WordPress
run: |
curl -O https://wordpress.org/latest.zip
unzip latest.zip -d wp-source
mv wp-source/wordpress/* wp-source/
- name: Generate wp-since.json
run: php generate-since-json.php
- name: Remove temporary files
run: rm -rf wp.tar.gz wp-source
- name: Install GitHub CLI
run: sudo apt install gh -y
- name: Authenticate GitHub CLI
env:
GH_TOKEN: ${{ secrets.WP_SINCE_ACTION }}
run: echo "${GH_TOKEN}" | gh auth login --with-token
- name: Create new branch
run: |
BRANCH_NAME=update-since-map-${{ github.run_number }}
git checkout -b $BRANCH_NAME
echo "BRANCH_NAME=$BRANCH_NAME" >> $GITHUB_ENV
- name: Commit changes
run: |
git config --global user.email "github-actions[bot]@users.noreply.github.com"
git config --global user.name "GitHub Actions"
git add wp-since.json
DATE=$(date +"%Y-%m-%d")
git commit -m "chore(data): update since map on $DATE" || echo "Nada pra commitar"
git push origin $BRANCH_NAME
- name: Create Pull Request
env:
GH_TOKEN: ${{ secrets.WP_SINCE_ACTION }}
run: |
gh pr create --head "$BRANCH_NAME" --base main \
--title "chore(data): update since map" \
--body "This PR was automatically generated by a GitHub Action. It updates the \`wp-since.json\` file with the latest WordPress version and its release date."

View file

@ -0,0 +1,2 @@
/vendor
.DS_Store

131
vendor/eduardovillao/wp-since/README.md vendored Normal file
View file

@ -0,0 +1,131 @@
# WP Since
![License](https://img.shields.io/badge/license-MIT-blue.svg)
[![Code Style: PSR-12](https://img.shields.io/badge/code%20style-PSR--12-blue)](https://www.php-fig.org/psr/psr-12/)
[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](./tests)
**Make sure your plugin works with the right WordPress version — automatically.**
Scans your WordPress plugin to detect all used core symbols and validates them against their official @since versions for accurate compatibility checks.
## ✨ How It Works
Ever struggled to define the correct minimum WordPress version for your plugin?
Worried about accidentally using functions or APIs that don’t exist in declared minimum WP version?
`wp-since` helps you avoid those headaches by automatically analyzing your plugin’s code and checking compatibility against real WordPress versions.
### Here’s what it does:
- 🧠 Scans your plugin for used:
- Functions
- Classes
- Class methods (static and instance)
- Action and filter hooks
- 📖 Reads the declared Requires at least: version from your `readme.txt`
- 🗂️ Compares those symbols with a version map built from WordPress core using `@since` tags
- 🚨 Reports any used symbols that require a newer WP version than what’s declared
### Example Output
Let’s say your plugin uses `register_setting()` (introduced in WP `5.5`), but your `readme.txt` declares compatibility with WordPress `5.4`:
```bash
🔍 Scanning plugin files...
✅ Found readme.txt → Minimum version declared: 5.4
🚨 Compatibility issues found:
┌──────────────────────┬──────────────────┐
│ Symbol │ Introduced in WP │
├──────────────────────┼──────────────────┤
│ register_setting │ 5.5.0 │
└──────────────────────┴──────────────────┘
📌 Suggested version required: 5.5.0
```
Now imagine your code is fully aligned with your declared version:
```bash
🔍 Scanning plugin files...
✅ Found readme.txt → Minimum version declared: 5.5
🎉 No compatibility issues found!
```
Simple. Powerful. Automatic.
Because your plugin deserves reliable compatibility.
## 🚀 Usage
**Requirements**
- PHP 7.4+
- Composer
🛠️ Install via Composer (recommended)
```bash
composer require --dev eduardovillao/wp-since
```
▶️ Run the compatibility check
```bash
./vendor/bin/wp-since check ./path-to-your-plugin
```
### 🧹 Ignore Files & Folders
By default, wp-since scans all `.php` files in your plugin directory.
But what about files that don’t make it into your final plugin zip — like tests or dev tools? No worries — wp-since respects your ignore rules.
**Supported ignore sources:**
- `.distignore`
- `.gitattributes` with `export-ignore`
If any of those files are present, wp-since will automatically ignore the listed files or folders during analysis — just like svn export or plugin deployment.
Example: .gitattributes
```txt
/tests/ export-ignore
/tools/debug.php export-ignore
```
Example: .distignore
```txt
/tests
/tools/debug.php
```
> These paths will be excluded from compatibility checks. This helps avoid false positives caused by test or development files.
### 📝 Inline Ignore
You can ignore specific lines from the scan by adding a special inline comment.
This is useful when you conditionally use a newer function but know it’s safe, like:
```php
if (function_exists('wp_some_new_func')) {
return wp_some_new_func(); // @wp-since ignore
}
```
> Only inline comments on the same line will be considered — comments above the line won’t trigger ignores.
## 🛠️ Coming Soon
- GitHub Action integration
- HTML/Markdown reports
- Export for CI/CD pipelines
## 📜 License
MIT © [Eduardo Villão](https://github.com/eduardovillao)
Use freely, contribute gladly.

View file

@ -0,0 +1,21 @@
#!/usr/bin/env php
<?php
foreach ([__DIR__ . '/../../../autoload.php', __DIR__ . '/../vendor/autoload.php'] as $file) {
if (file_exists($file)) {
require $file;
break;
}
}
use WP_Since\Runner\PluginCheckCommand;
if ($argc < 2 || $argv[1] !== 'check') {
echo "🛠 Usage: wp-since check /path/to/plugin\n";
exit(0);
}
$pluginPath = $argv[2] ?? getcwd();
$sinceMapPath = __DIR__ . '/../wp-since.json';
exit(PluginCheckCommand::run($pluginPath, $sinceMapPath));

View file

@ -0,0 +1,10 @@
<?php
require_once __DIR__ . '/vendor/autoload.php';
use WP_Since\Runner\PluginCheckCommand;
$pluginPath = $argv[1] ?? getcwd();
$sinceMapPath = __DIR__ . '/wp-since.json';
exit(PluginCheckCommand::run($pluginPath, $sinceMapPath));

View file

@ -0,0 +1,35 @@
{
"name": "eduardovillao/wp-since",
"description": "Check WordPress plugin compatibility by analyzing used functions, classes, hooks and comparing against the minimum required WP version.",
"type": "library",
"license": "MIT",
"require": {
"php": ">=7.4",
"nikic/php-parser": "^4.15"
},
"require-dev": {
"phpunit/phpunit": "^10.5",
"squizlabs/php_codesniffer": "^3.12"
},
"autoload": {
"psr-4": {
"WP_Since\\": "src/"
}
},
"bin": [
"bin/wp-since"
],
"scripts": {
"check": "php bin/wp-since check ./tests/fixtures/plugin-full-test",
"generate-since": "php generate-since-json.php",
"tests:unit": "phpunit tests --testdox --colors",
"lint": "phpcs",
"lint:fix": "phpcbf"
},
"minimum-stability": "stable",
"prefer-stable": true,
"support": {
"issues": "https://github.com/eduardovillao/wp-since/issues",
"source": "https://github.com/eduardovillao/wp-since"
}
}

1728
vendor/eduardovillao/wp-since/composer.lock generated vendored Normal file

File diff suppressed because it is too large Load diff

View file

@ -0,0 +1,133 @@
<?php
require __DIR__ . '/vendor/autoload.php';
use PhpParser\Error;
use PhpParser\Node;
use PhpParser\NodeTraverser;
use PhpParser\NodeVisitorAbstract;
use PhpParser\ParserFactory;
use PhpParser\NodeVisitor\ParentConnectingVisitor;
$sourceDir = __DIR__ . '/wp-source';
$outputPath = __DIR__ . '/wp-since.json';
$excludedPaths = [
'wp-content/',
'wp-admin/includes/class-pclzip.php',
'wp-admin/includes/noop.php',
'wp-includes/ID3/',
'wp-includes/IXR/',
'wp-includes/PHPMailer/',
'wp-includes/pomo/',
'wp-includes/Requests/',
'wp-includes/SimplePie/',
'wp-includes/Text/',
'wp-includes/sodium_compat/',
'wp-includes/js/tinymce',
'wp-includes/class-simplepie.php',
'wp-includes/atomlib.php',
'wp-includes/class-avif-info.php',
'wp-includes/class-json.php',
'wp-includes/class-pop3.php',
'wp-includes/class-requests.php',
'wp-includes/class-snoopy.php',
'wp-includes/compat.php',
'wp-includes/rss.php',
];
$parser = (new ParserFactory)->create(ParserFactory::PREFER_PHP7);
$result = [];
class SinceExtractor extends NodeVisitorAbstract
{
private $file;
private $result;
public function __construct($file, &$result)
{
$this->file = $file;
$this->result = &$result;
}
public function enterNode(Node $node)
{
$doc = $node->getDocComment();
$docText = $doc ? $doc->getText() : null;
$since = $this->extractTag($docText, '@since');
$deprecated = $this->extractTag($docText, '@deprecated');
if ($node instanceof Node\Stmt\Function_) {
$this->addResult($node->name->toString(), 'function', $since, $deprecated);
} elseif ($node instanceof Node\Stmt\Class_ || $node instanceof Node\Stmt\Interface_ || $node instanceof Node\Stmt\Trait_) {
$type = $node instanceof Node\Stmt\Class_ ? 'class' : ($node instanceof Node\Stmt\Interface_ ? 'interface' : 'trait');
$this->addResult($node->name->toString(), $type, $since, $deprecated);
} elseif ($node instanceof Node\Stmt\ClassMethod && !$node->isPrivate()) {
$class = $node->getAttribute('parent');
$className = $class instanceof Node\Stmt\Class_ && $class->name ? $class->name->toString() : 'Anonymous';
$methodName = $node->name->toString();
$methodSince = $since ?: ($class && $class->getDocComment() ? $this->extractTag($class->getDocComment()->getText(), '@since') : null);
if ($className !== 'Anonymous' && $methodSince) {
$this->addResult("$className::$methodName", 'method', $methodSince, $deprecated);
}
} elseif (
$node instanceof Node\Expr\FuncCall &&
$node->name instanceof Node\Name &&
in_array($node->name->toString(), ['do_action', 'apply_filters'], true)
) {
$hookNameNode = $node->args[0]->value ?? null;
if ($hookNameNode instanceof Node\Scalar\String_) {
$hookName = $hookNameNode->value;
$this->addResult($hookName, 'hook', $since, $deprecated);
}
}
}
private function extractTag($docText, $tag)
{
if ($docText && preg_match('/' . preg_quote($tag) . '\s+([0-9.]+)/', $docText, $matches)) {
$version = $matches[1];
if ($version === 'MU') return '3.0.0';
if (preg_match('/^\d+\.\d+(\.\d+)?$/', $version)) return $version;
}
return null;
}
private function addResult($name, $type, $since, $deprecated)
{
if ($since) {
$this->result[$name] = array_filter([
'type' => $type,
'since' => $since,
'deprecated' => $deprecated,
'file' => $this->file
]);
}
}
}
$rii = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($sourceDir));
foreach ($rii as $file) {
if ($file->isDir() || $file->getExtension() !== 'php') continue;
$relativePath = str_replace($sourceDir . '/', '', $file->getPathname());
foreach ($excludedPaths as $excluded) {
if (strpos($relativePath, $excluded) === 0) continue 2;
}
try {
$code = file_get_contents($file->getPathname());
$ast = $parser->parse($code);
$traverser = new NodeTraverser();
$traverser->addVisitor(new ParentConnectingVisitor());
$traverser->addVisitor(new SinceExtractor($relativePath, $result));
$traverser->traverse($ast);
} catch (Error $e) {
echo "Processing error {$relativePath}: {$e->getMessage()}\n";
}
}
file_put_contents($outputPath, json_encode($result, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES));
echo "✅ File generated in: {$outputPath}\n";

17
vendor/eduardovillao/wp-since/phpcs.xml vendored Normal file
View file

@ -0,0 +1,17 @@
<?xml version="1.0"?>
<ruleset name="WP-Since Ruleset">
<description>PHP_CodeSniffer configuration for WP-Since</description>
<!-- Only PSR-12 -->
<rule ref="PSR12"/>
<!-- To check -->
<file>src</file>
<file>tests</file>
<!-- To ignore -->
<exclude-pattern>vendor/*</exclude-pattern>
<exclude-pattern>tests/fixtures/*</exclude-pattern>
<arg name="report-width" value="120"/>
</ruleset>

View file

@ -0,0 +1,31 @@
<?php
namespace WP_Since\Checker;
use WP_Since\Utils\VersionHelper;
class CompatibilityChecker
{
private array $sinceMap;
public function __construct(array $sinceMap)
{
$this->sinceMap = $sinceMap;
}
public function check(array $symbols, string $declaredVersion): array
{
$incompatible = [];
foreach ($symbols as $symbol) {
if (
isset($this->sinceMap[$symbol]) &&
VersionHelper::compare($declaredVersion, $this->sinceMap[$symbol]['since']) < 0
) {
$incompatible[$symbol] = $this->sinceMap[$symbol]['since'];
}
}
return $incompatible;
}
}

View file

@ -0,0 +1,61 @@
<?php
namespace WP_Since\Resolver;
class IgnoreRulesResolver
{
public static function getIgnoredPaths(string $pluginPath): array
{
$ignorePatterns = [];
$distignore = $pluginPath . '/.distignore';
if (file_exists($distignore)) {
$ignorePatterns = array_merge($ignorePatterns, self::parseIgnoreFile($distignore));
}
$gitattributes = $pluginPath . '/.gitattributes';
if (file_exists($gitattributes)) {
$ignorePatterns = array_merge($ignorePatterns, self::parseGitAttributes($gitattributes));
}
return array_map(function ($pattern) {
return ltrim(rtrim($pattern, '/'), '/');
}, $ignorePatterns);
}
private static function parseIgnoreFile(string $file): array
{
return array_filter(array_map('trim', file($file)), fn($line) => $line !== '' && $line[0] !== '#');
}
private static function parseGitAttributes(string $file): array
{
$lines = file($file);
$ignores = [];
foreach ($lines as $line) {
if (strpos($line, 'export-ignore') !== false) {
$parts = preg_split('/\s+/', trim($line));
if (!empty($parts[0])) {
$ignores[] = $parts[0];
}
}
}
return $ignores;
}
public static function shouldIgnore(string $relativePath, array $ignorePaths): bool
{
foreach ($ignorePaths as $ignored) {
$normalized = ltrim($ignored, '/');
if (
$relativePath === $normalized ||
str_starts_with($relativePath, rtrim($normalized, '/') . '/')
) {
return true;
}
}
return false;
}
}

View file

@ -0,0 +1,26 @@
<?php
namespace WP_Since\Resolver;
use PhpParser\Lexer\Emulative;
class InlineIgnoreResolver
{
public static function extractIgnoredLines(string $code): array
{
$lexer = new Emulative(['usedAttributes' => ['startLine']]);
$lexer->startLexing($code);
$ignoredLines = [];
foreach ($lexer->getTokens() as $token) {
if (is_array($token) && in_array($token[0], [T_COMMENT, T_DOC_COMMENT], true)) {
if (strpos($token[1], '@wp-since ignore') !== false) {
$ignoredLines[] = $token[2];
}
}
}
return $ignoredLines;
}
}

View file

@ -0,0 +1,77 @@
<?php
namespace WP_Since\Resolver;
class VersionResolver
{
public static function resolve(string $pluginPath): ?array
{
$pluginFile = self::findMainPluginFile($pluginPath);
if ($pluginFile) {
$version = self::extractVersionFromPluginHeader($pluginFile);
if ($version) {
return ['version' => $version, 'source' => 'main plugin file header'];
}
}
$readme = self::findReadmeFile($pluginPath);
if ($readme) {
$version = self::extractVersionFromReadme($readme);
if ($version) {
return ['version' => $version, 'source' => 'readme'];
}
}
return null;
}
private static function findMainPluginFile(string $pluginPath): ?string
{
$basename = basename($pluginPath);
$candidate = "{$pluginPath}/{$basename}.php";
if (file_exists($candidate)) {
return $candidate;
}
return null;
}
private static function extractVersionFromPluginHeader(string $file): ?string
{
$contents = file_get_contents($file);
if (!$contents) {
return null;
}
if (preg_match('/^\s*\*\s+Requires at least:\s*([0-9.]+)/mi', $contents, $matches)) {
return $matches[1];
}
return null;
}
private static function findReadmeFile(string $pluginPath): ?string
{
foreach (['readme.txt', 'README.txt'] as $filename) {
$full = "{$pluginPath}/{$filename}";
if (file_exists($full)) {
return $full;
}
}
return null;
}
private static function extractVersionFromReadme(string $file): ?string
{
$lines = file($file);
foreach ($lines as $line) {
if (stripos($line, 'Requires at least:') === 0) {
if (preg_match('/Requires at least:\s*([0-9.]+)/i', $line, $matches)) {
return $matches[1];
}
}
}
return null;
}
}

View file

@ -0,0 +1,57 @@
<?php
namespace WP_Since\Runner;
use WP_Since\Resolver\VersionResolver;
use WP_Since\Scanner\PluginScanner;
use WP_Since\Checker\CompatibilityChecker;
use WP_Since\Utils\TablePrinter;
use WP_Since\Utils\VersionHelper;
class PluginCheckCommand
{
public static function run(string $pluginPath, string $sinceMapPath): int
{
if (!file_exists($sinceMapPath)) {
echo "❌ wp-since.json not found. Run composer generate-since first.\n";
return 1;
}
$versionResolver = VersionResolver::resolve($pluginPath);
if (!$versionResolver['version']) {
echo "❌ Could not determine the minimum required WP version.\n";
return 1;
}
$source = $versionResolver['source'] ?? '';
$declaredVersion = $versionResolver['version'];
echo "✅ Minimum version declared: {$declaredVersion} (from {$source})\n\n";
$usedSymbols = PluginScanner::scan($pluginPath);
$sinceMap = json_decode(file_get_contents($sinceMapPath), true);
$checker = new CompatibilityChecker($sinceMap);
$incompatible = $checker->check($usedSymbols, $declaredVersion);
if (count($incompatible)) {
echo "🚨 Compatibility issues found:\n\n";
$rows = [];
foreach ($incompatible as $symbol => $version) {
$rows[] = [$symbol, $version];
}
TablePrinter::render($rows, ['Symbol', 'Introduced in WP']);
$versions = array_values($incompatible);
$maxVersion = array_reduce($versions, function ($carry, $v) {
return VersionHelper::compare($carry, $v) < 0 ? $v : $carry;
}, $declaredVersion);
echo "📌 Suggested version required: {$maxVersion}\n";
return 1;
}
echo "✅ All good! Your plugin is compatible with WP {$declaredVersion}.\n";
return 0;
}
}

View file

@ -0,0 +1,55 @@
<?php
namespace WP_Since\Scanner;
use PhpParser\NodeTraverser;
use PhpParser\ParserFactory;
use PhpParser\NodeVisitor\ParentConnectingVisitor;
use WP_Since\Resolver\IgnoreRulesResolver;
use WP_Since\Scanner\SymbolExtractorVisitor;
use WP_Since\Resolver\InlineIgnoreResolver;
class PluginScanner
{
public static function scan(string $path): array
{
$parser = (new ParserFactory())->create(ParserFactory::PREFER_PHP7);
$traverser = new NodeTraverser();
$usedSymbols = [];
$varMap = [];
$traverser->addVisitor(new ParentConnectingVisitor());
$ignorePaths = IgnoreRulesResolver::getIgnoredPaths($path);
$rii = new \RecursiveIteratorIterator(new \RecursiveDirectoryIterator($path));
foreach ($rii as $file) {
$relativePath = str_replace($path . '/', '', $file->getPathname());
if (
$file->isDir() ||
$file->getExtension() !== 'php' ||
IgnoreRulesResolver::shouldIgnore($relativePath, $ignorePaths)
) {
continue;
}
$code = file_get_contents($file->getPathname());
$ignoredLines = InlineIgnoreResolver::extractIgnoredLines($code);
$visitor = new SymbolExtractorVisitor($usedSymbols, $varMap, $ignoredLines);
$traverser->addVisitor($visitor);
try {
$stmts = $parser->parse($code);
$traverser->traverse($stmts);
} catch (\Exception $e) {
// Add error handling
}
$traverser->removeVisitor($visitor);
}
return array_unique($usedSymbols);
}
}

View file

@ -0,0 +1,48 @@
<?php
namespace WP_Since\Scanner;
use PhpParser\Node;
use PhpParser\NodeVisitorAbstract;
use WP_Since\Scanner\SymbolHandlers\SymbolHandlerInterface;
class SymbolExtractorVisitor extends NodeVisitorAbstract
{
private array $usedSymbols;
private array $varMap;
private array $ignoredLines;
/** @var SymbolHandlerInterface[] */
private array $handlers;
public function __construct(array &$usedSymbols, array &$varMap, array $ignoredLines = [])
{
$this->usedSymbols = &$usedSymbols;
$this->varMap = &$varMap;
$this->ignoredLines = $ignoredLines;
$this->handlers = [
new SymbolHandlers\FunctionCallHandler(),
new SymbolHandlers\NewClassHandler(),
new SymbolHandlers\StaticCallHandler(),
new SymbolHandlers\MethodCallHandler(),
];
}
public function enterNode(Node $node)
{
if (in_array($node->getStartLine(), $this->ignoredLines, true)) {
return null;
}
foreach ($this->handlers as $handler) {
if ($handler->supports($node)) {
$symbols = $handler->extract($node, $this->varMap);
foreach ($symbols as $symbol) {
$this->usedSymbols[] = $symbol;
}
break;
}
}
}
}

View file

@ -0,0 +1,27 @@
<?php
namespace WP_Since\Scanner\SymbolHandlers;
use PhpParser\Node;
class FunctionCallHandler implements SymbolHandlerInterface
{
public function supports(Node $node): bool
{
return $node instanceof Node\Expr\FuncCall && $node->name instanceof Node\Name;
}
public function extract(Node $node, array &$varMap = []): array
{
$symbols = [(string) $node->name];
if (in_array((string) $node->name, ['do_action', 'apply_filters'], true)) {
$hookNameNode = $node->args[0]->value ?? null;
if ($hookNameNode instanceof Node\Scalar\String_) {
$symbols[] = $hookNameNode->value;
}
}
return $symbols;
}
}

Some files were not shown because too many files have changed in this diff Show more