Overview
PreFlight Scanner is a free WordPress plugin that lets you upload any plugin ZIP file and run a comprehensive static safety scan before it ever touches your live environment. It works by reading and parsing PHP files as plain text — no plugin code is executed at any point during the scan.
After the scan completes you receive a full report with one of three overall verdicts: ALL CLEAR, WARNINGS FOUND, or CRITICAL ISSUES. If the scan passes, you can install and activate the plugin with a single click directly from the results page.
Installation
- Download PreFlight Scanner from WordPress.org.
- In your WordPress admin, go to Plugins → Add New → Upload Plugin.
- Select the downloaded ZIP and click Install Now, then Activate Plugin.
- Navigate to Tools → PreFlight Scanner to start scanning.
install_plugins capability is required. This is reserved for Administrators by default.
Running a Scan
- Go to Tools → PreFlight Scanner.
- Click Choose File and select the plugin ZIP you want to test.
- Click Run Pre-Flight Scan.
- Wait a few seconds while the scanner extracts and analyses the files.
- Review the results page.
wp-content/uploads/preflight-tmp/. The ZIP itself is deleted immediately after extraction. The extracted PHP files are kept for up to 5 minutes — enough time to review results and install if you choose to. On your next page load, any leftover data from a previous scan is also cleaned up automatically.
Understanding Results
✅ ALL CLEAR — Ready to Install
No issues were detected across all 13 checks. The plugin appears safe and compatible with your environment. A prominent green banner confirms this. You can install and activate the plugin directly from the results page.
⚠️ WARNINGS FOUND — Review Before Installing
One or more advisory issues were found. The plugin may still work correctly on your site — warnings do not guarantee a problem. Common warning sources include deprecated WordPress functions, missing PHP namespace declarations, or suspicious outbound HTTP calls. Review each warning in the report and use your judgement. The install button remains available.
🚨 CRITICAL ISSUES — Do NOT Install
One or more critical issues were detected — malicious code patterns, function/class name collisions, dangerous PHP functions, or suspicious executable files. Installing the plugin will very likely cause a PHP fatal error or compromise your site. A red banner marks the report and a confirmation dialog warns you before any files are copied. It is strongly recommended that you contact the plugin author before proceeding.
All 13 Checks
PreFlight Scanner runs four groups of checks on every scan. The table below lists each check, its severity level, and what triggers a flag.
Version Compatibility
| Check | Severity | What triggers a flag |
|---|---|---|
| PHP Version | DANGER | Plugin's Requires PHP header is higher than the server's PHP version — activation will cause a fatal error. Also flags modern syntax features (match, nullsafe operators, arrow functions, typed properties, null coalescing, return types) that your server's PHP cannot parse. |
| WordPress Version | DANGER / WARN | DANGER if the plugin's Requires at least header is higher than your running WordPress version. WARNING if your WordPress version exceeds the plugin's Tested up to header. |
Collision Detection
| Check | Severity | What triggers a flag |
|---|---|---|
| Function Name Collisions | DANGER | A global function in the uploaded plugin already exists in the currently active environment (declared by another active plugin or WordPress core). PHP fatal error guaranteed on activation. |
| Class Name Collisions | DANGER | A class, interface, trait, or enum defined in the uploaded plugin already exists in the active environment. Same result as a function collision. |
| Hook Priority Conflicts | WARNING | An add_action() or add_filter() call in the uploaded plugin uses a hook name and priority that an already-active plugin has also registered. The second plugin's callback will silently overwrite the first's return value — a common cause of WooCommerce checkout and pricing bugs. High-traffic core hooks (init, wp_head, admin_init, etc.) are excluded from this check to reduce noise. |
Security — Critical
| Check | Severity | What triggers a flag |
|---|---|---|
| Obfuscated / Malicious Code | DANGER |
Any of the following patterns are detected:eval(base64_decode(...))eval(gzinflate(...)) or gzuncompresseval(str_rot13(...))eval(rawurldecode(...))preg_replace() with /e modifierLarge base64 blobs (>500 chars) |
| Dangerous PHP Functions | DANGER | shell_exec, exec, system, passthru, proc_open, popen, pcntl_exec — OS-level command execution that has no legitimate use in a standard WordPress plugin. |
| Suspicious File Types | DANGER | Files with extensions .exe, .sh, .bat, .cmd, .com, .py, .rb, .pl, .vbs found anywhere inside the ZIP. |
Warnings & Best Practices
| Check | Severity | What triggers a flag |
|---|---|---|
| Missing PHP Namespaces | WARNING | A PHP file defines global functions, classes, interfaces, traits, or enums without a namespace declaration. Namespace-less code is at elevated risk of future collision as more plugins are added to the site. |
| Deprecated WordPress Functions | WARNING | Calls to WordPress functions that have been deprecated or removed, such as create_function(), get_user_by_email(), clean_url(), and others listed in WordPress core's deprecated function log. |
| Suspicious Outbound HTTP Calls | WARNING | wp_remote_get() / wp_remote_post(), curl_exec(), or file_get_contents() with a hardcoded external URL. Many legitimate plugins make outbound calls (API integrations, update checks) — this is advisory, not a definitive red flag. |
| Direct Database Queries | WARNING | $wpdb->query() (raw SQL) or $wpdb->get_results() / get_row() / get_var() called with string concatenation (. $variable) instead of $wpdb->prepare(). |
| Missing Nonce / Capability Checks | WARNING | A PHP file reads $_POST, $_GET, or $_REQUEST without a detected call to check_admin_referer(), check_ajax_referer(), wp_verify_nonce() (nonce), or current_user_can() (capability) in the same file. Note: false positives are possible when checks live in a parent class. |
Installing After a Scan
Once a scan is complete, the results page shows an Installation Options panel at the bottom:
- ALL CLEAR / WARNINGS FOUND: A green Install & Activate Plugin button copies the plugin from the temporary directory to
wp-content/plugins/and attempts to activate it automatically. If auto-activation fails, you are redirected to the Plugins page to activate manually. - CRITICAL ISSUES: A red Install Anyway (Not Recommended) button is shown instead. Clicking it triggers a browser confirmation dialog before proceeding.
- Discard & Scan Another: Cancels the current scan, deletes the temporary files immediately, and returns you to the upload form.
Troubleshooting
Upload failed or no file was selected
Ensure the file you selected has a .zip extension and that your PHP upload_max_filesize and post_max_size settings are large enough for the plugin ZIP. Large plugins (WooCommerce, etc.) can be 10 MB or more.
Could not unzip the file
The ZIP may be corrupt or not a valid WordPress plugin archive. Try re-downloading the plugin from its source and scanning the fresh copy. PreFlight requires PHP's ZipArchive extension, which is enabled by default on most hosts.
Scan data has expired
You spent more than 5 minutes on the results page before clicking Install. Re-upload the ZIP and re-scan — the process takes only a few seconds.
Could not initialise WP_Filesystem
Your server may require FTP credentials to write files. PreFlight uses the WordPress Filesystem API (WP_Filesystem()). If your WordPress installation normally requires FTP credentials for plugin installs, you may need to define FS_METHOD in wp-config.php:
define( 'FS_METHOD', 'direct' );Only do this if your server's file permissions already allow direct writes from the web server user.
False positives on "Missing Nonce / Capability Checks"
The nonce and capability check is a per-file analysis. If a plugin uses a base class or trait to handle security checks that are inherited by other files, the scanner will flag the child files even though they are actually protected. This is a known limitation of static analysis without execution context.
Frequently Asked Questions
Does PreFlight Scanner execute the uploaded plugin's code?
No. All checks are purely static. PHP files are read as plain text strings and analysed with regular expressions and PHP's built-in introspection functions. No class is instantiated, no function is called, no hook is registered from the scanned plugin.
Can I scan a plugin that is already installed?
The scanner is a pre-installation tool. To audit an already-installed plugin, deactivate it, download its ZIP, and upload that ZIP for scanning. Note that collision detection compares against the live environment — if the plugin being scanned is currently active, its own functions and classes will appear as "collisions."
Why are common hooks like "init" not flagged as hook conflicts?
A curated list of high-traffic core WordPress hooks (init, wp_head, admin_init, plugins_loaded, wp_enqueue_scripts, etc.) is excluded from hook conflict reporting. These hooks are used by virtually every plugin and WordPress itself, so reporting conflicts on them would generate constant noise. The check focuses on non-core hooks where a collision is genuinely surprising — plugin-specific filters, WooCommerce hooks, and custom hook names.
What does the scan do with my ZIP file?
The ZIP is moved to a temporary directory inside wp-content/uploads/preflight-tmp/, extracted, and then deleted. The extracted PHP files are analysed in memory. The temporary directory is protected by an .htaccess file and has a randomly-generated name to prevent direct access. Everything is deleted automatically after 5 minutes.
Is PreFlight Scanner safe to run on a production site?
Yes. The scanner never modifies plugin files, database values, or WordPress settings. All activity is limited to: (1) writing the uploaded ZIP to a protected temp directory, (2) reading PHP files from that directory, and (3) writing two short-lived transients with scan results.
What happens if I close the browser during a scan?
The temporary files will be cleaned up automatically — either when the 5-minute transient expires and WordPress runs its scheduled cron, or on your next visit to the PreFlight Scanner page (whichever comes first).
Support
For bug reports and feature requests, use the WordPress.org support forum for the free version.
For general questions, reach us at [email protected].