=== Eli's PHP Compatibility Scanner ===
Contributors: eliehanna
Tags: compatibility, testing, code-quality, phpcs, wordpress-development
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.2.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Scan your plugins and themes for PHP version compatibility issues using the PHPCompatibility ruleset.

== Description ==

**⚠️ Important: Development Environment Only**

This plugin is designed for development environments like LocalWP, XAMPP, or self-hosted servers. It will **not work** on most managed hosting providers (WP Engine, Kinsta, SiteGround, etc.) due to security restrictions that disable the `exec()` function and limit access to PHP binaries.

Need to scan a live site, or one on managed hosting? [PHP Compatibility Scanner Pro](https://coffeewp.dev/php-compatibility-scanner/) runs the scan on a remote service, so `exec()` is not required.



**How It Works**

This plugin uses [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) with the [PHPCompatibility](https://github.com/PHPCompatibility/PHPCompatibility) standard to perform deep static analysis of your PHP code.

**How to Use:**

1. Open **PHP Compatibility Scanner** in the WordPress admin menu
2. Review the **System Check** section to ensure your environment is compatible
3. Select the **plugins and/or themes** you want to scan by checking their boxes
4. Configure your scan options:
   - **Target PHP Version**: Choose the PHP version you want to test against (7.4 - 8.4)
   - **Batch Size**: Select how many files to process at once (default: 50 files)
   - **Skip Vendor Directory**: Keep checked to skip third-party dependencies
5. Click **Start Scan** to begin the compatibility check
6. View results in real-time as each plugin/theme is scanned
7. Review any **errors** (❌) or **warnings** (⚠️) found in your code
8. Click on any target to expand and see detailed compatibility issues

**Why It Requires Development Environments**

* **`exec()` Function**: Required to run PHPCS binary - disabled on managed hosts
* **PHP Binary Access**: Needs access to PHP executable - restricted on shared hosting
* **Composer Dependencies**: Requires vendor directory with PHPCS installation
* **File System Access**: Creates temporary files for batch processing
* **Memory/Time Limits**: Long-running scans need relaxed execution limits

**Supported Environments**

* **LocalWP** (recommended)
* **XAMPP/MAMP**
* **Docker WordPress** setups
* **Self-hosted** VPS/dedicated servers
* **Development** environments with shell access

**Unsupported Environments**

* **WP Engine** (exec() disabled)
* **Kinsta** (security restrictions)
* **SiteGround** (managed hosting limitations)
* **GoDaddy Managed WordPress** (function restrictions)
* **WordPress.com** (no plugin uploads)
* Most **shared hosting** providers

== Installation ==

**Prerequisites**

* **Development Environment**: LocalWP, XAMPP, MAMP, or self-hosted server
* **PHP 7.4+**: Required for plugin operation
* **WordPress 5.8+**: Minimum WordPress version

**Setup Instructions**

1. **Download/Install** the plugin to your `wp-content/plugins/` directory
2. **Activate Plugin** in WordPress Admin → Plugins
3. **Open the scanner** via **PHP Compatibility Scanner** in the WordPress admin menu

**Note**: All required dependencies (PHP_CodeSniffer and PHPCompatibility) are included with the plugin, no additional setup required.

== Frequently Asked Questions ==

= What is this plugin for? =

This plugin helps WordPress developers check if their custom code (plugins and themes) will work with different PHP versions. It's especially useful when planning to upgrade PHP on production servers or when developing for clients with specific PHP version requirements.

= Why won't it work on my hosting provider? =

Most managed hosting providers (WP Engine, Kinsta, SiteGround, etc.) disable the `exec()` function for security reasons. This plugin needs to run PHP commands to analyze your code, which requires this function to be enabled.

= Can I scan a site on managed hosting? =

Not with this plugin: it needs `exec()` and access to a PHP binary, and managed hosts disable both. [PHP Compatibility Scanner Pro](https://coffeewp.dev/php-compatibility-scanner/) sends the plugin or theme to a remote scan service instead, so the scan never runs on your server. It is a separate plugin, available from coffeewp.dev.

= What PHP versions can I test against? =

The plugin can test your code against PHP versions 7.4 through 8.4, helping you identify compatibility issues before upgrading.

= How accurate are the results? =

The scan runs PHP_CodeSniffer with the PHPCompatibility standard, a ruleset maintained specifically to track what changed in each PHP release.

PHP_CodeSniffer parses your code into PHP tokens instead of searching it for text patterns, so every match is judged in context. A function name that appears inside a comment or a string is not reported, and a call is only flagged against the PHP versions that actually changed it. Scanners built on pattern matching cannot make that distinction, which is where both false alarms and missed issues come from.

= Can I scan multiple plugins at once? =

Yes. You can select multiple plugins and themes to scan simultaneously. The plugin processes them in batches to manage memory usage efficiently.

= What if the scan takes too long? =

You can stop a long-running scan at any time. Lowering the batch size also helps on servers with tight memory or execution limits.

= Are my files modified during scanning? =

No, your files are never modified. The plugin only reads your code to analyze it. Any temporary files created during scanning are automatically cleaned up.

== Screenshots ==

1. Plugin dashboard displaying environment compatibility check results
2. Configuration panel with scan options and available plugins/themes selection
3. Scan results showing detected PHP compatibility errors in selected plugins
4. Clean scan results indicating no compatibility issues found

== Changelog ==

= 1.2.0 =
* New: the scanner has its own top-level admin menu, with Scan and Settings screens instead of a buried submenu.
* New: Scan Options shows a loading skeleton while the system check runs, so the screen no longer looks empty on slow hosts.
* New: when the system check fails, the screen explains what failed and what to try, instead of only reporting that scanning is unavailable.
* Improved: reworked scan page — clearer mode buttons, a results modal, and corrected summary counts.
* Improved: support links now point to the right place for free users.
* Fix: no longer fatals when another edition of the scanner is already active.
* Fix: hardened handling of admin AJAX request input.

= 1.1.3 =
* Fix: "Unable to run phpcs --version with detected PHP binary" on LocalWP/macOS. PHP_BINARY pointed to php-fpm, a server SAPI that cannot run CLI scripts; the scanner now resolves the CLI php binary from the same PHP install.
* Tested up to WordPress 7.0.

Older releases are listed in changelog.txt, included with the plugin.

== Upgrade Notice ==

= 1.2.0 =
The scanner now has its own admin menu, and a failed system check explains what to try instead of just reporting failure.

= 1.1.3 =
Fixes "Unable to run phpcs --version" on LocalWP/macOS. Tested up to WordPress 7.0.

= 1.1.1 =
Fix: scan overview tags persist after scan completes.

= 1.1.0 =
Scan Overview UI Update

= 1.0.5 =
Improved target selection with Active indicators and Select All / Select Active buttons.

= 1.0.4 =
Fixes fatal error "Namespace declaration... very first statement" on some servers (e.g. LiteSpeed). Open PHP Compatibility Scanner from the admin menu after updating.

= 1.0.3 =
Fixes scan error on macOS and PHP 8.1+ deprecation. Tested on latest WordPress and WordPress Studio for Mac.

= 1.0.2 =
Important update with WordPress.org compliance fixes, and improved documentation.

= 1.0.0 =
Initial release. Scans plugins and themes against PHP 7.4 to 8.4.

== Contributing ==

This plugin is actively developed for WordPress development environments. Contributions are welcome, especially:

* Additional PHP version compatibility rules
* Performance optimizations
* UI/UX improvements
* Hosted environment compatibility solutions

== Technical Details ==

**How the scan runs**

1. **Bundled dependencies**: PHP_CodeSniffer and the PHPCompatibility ruleset ship with the plugin
2. **Batch processing**: files are scanned in configurable batches (10 to 100) to manage memory usage
3. **Command execution**: PHPCS is invoked through PHP's `exec()` function
4. **Server-side state**: file lists are stored in WordPress options to keep AJAX requests small
5. **Progressive UI**: batch results appear in real time, with stop and start controls

**Dependencies**

* **PHP_CodeSniffer**: ^3.13 (static analysis engine)
* **PHPCompatibility**: dev-develop (compatibility ruleset)

**License**

GPLv2 or later - same as WordPress core.
