Documentation

Getting Started with PluginShield

Everything you need to install PluginShield and run your first conflict scan in under 5 minutes.

Installation

From WordPress.org (recommended)

In your WordPress admin, go to Plugins → Add New
Search for PluginShield
Click Install Now, then Activate
You'll be redirected to the PluginShield dashboard automatically

Manual installation

Download the ZIP from wordpress.org/plugins/pluginshield, then upload via Plugins → Add New → Upload Plugin.

ℹ️

Installing Pro? Deactivate the free PluginShield plugin first. Your scan history carries over automatically — both plugins use the same database tables. The Pro plugin automatically creates any new tables it needs on first admin load.

Running Your First Scan

Navigate to PluginShield → Scan for Conflicts in your WordPress admin menu.

Step 1 — Describe the problem

Before starting, write a clear description of what's broken. This isn't sent anywhere — it's just for your reference so you can accurately answer each step. Be specific:

✓

Good: "The Add to Cart button on product pages does nothing when clicked. No error message."

Step 2 — Exclude known-good plugins (optional)

If you know certain plugins are definitely not the cause, check them in the exclusion list. Good candidates: security plugins, your page builder, or WooCommerce itself if the problem predates any WooCommerce updates.

Step 3 — Answer each step

PluginShield will temporarily disable a batch of plugins. Open your site in a new tab and check whether the problem is still there.

Still broken → The culprit is in the plugins that are still active. PluginShield narrows to that half.
Problem gone → The culprit is in the batch that was just disabled. PluginShield narrows to that half.

⚠️

Always check the exact symptom you described. Don't be fooled by other minor visual changes that happen when plugins are disabled — focus only on your specific problem.

Step 4 — Result

After 4–6 steps, PluginShield will identify a single plugin as the culprit. All other plugins are automatically restored. You can then decide to deactivate, replace, or contact the plugin author about the conflict.

How Isolation Works

This is what makes PluginShield different from every other tool.

Most conflict detection plugins "deactivate" plugins by modifying the active_plugins option in the database. WordPress checks this list during boot — but by that point, PHP has already started, and many plugin hooks are already registered.

PluginShield takes a different approach: it renames the plugin directory.

# Before isolation
wp-content/plugins/woocommerce/woocommerce.php  ← PHP can find this

# After isolation
wp-content/plugins/woocommerce__ps_isolated/    ← PHP cannot find this
                                                   File literally doesn't exist

When WordPress tries to load woocommerce/woocommerce.php, PHP cannot find the file. The plugin does not run. Zero code executes. This is identical to deactivating via SFTP — the method WordPress support always recommends when other tools fail.

Safety mechanisms

30-minute auto-restore: If a scan is abandoned, PluginShield restores all plugins on your next admin page load.
Deactivation restore: If PluginShield is deactivated with a scan in progress, the deactivation hook restores everything.
Force Restore button: Available at any time on the scanner page.
Visitor protection: The isolation is scoped to the current admin PHP session. Visitors see all plugins active.

Server Requirements

WordPress 6.2 or higher
PHP 7.4 or higher
Write permissions on wp-content/plugins/

Starting a Scan

Go to PluginShield → Scan for Conflicts. Fill in the problem description, optionally exclude plugins you know are innocent, choose whether to include the active theme as a suspect, then click Start Conflict Scan.

Answering Each Step

After each isolation step, use the Open Site ↗ button to check your site in a new tab. Answer Still Broken or Problem is Gone based solely on the specific symptom you described at the start. Do not answer based on other visual differences caused by unrelated plugins being disabled.

Theme as a Suspect

Many WordPress conflicts are between a plugin and the active theme — not between two plugins. PluginShield can test your theme too.

Enable the "Also test active theme as a suspect" checkbox when starting a scan. If all plugins are cleared without finding the culprit, PluginShield will temporarily switch your active theme to a default WordPress theme (Twenty Twenty-Five or similar) and ask you to check your site again.

⚠️

Theme testing requires a default WordPress theme (Twenty Twenty-Four, Twenty Twenty-Five, etc.) to be installed as the fallback. If none is installed, the option will be disabled. Unlike plugin isolation, theme switching is visible to visitors for the ~30 seconds it takes you to check.

If the problem disappears when the fallback theme is active, your theme is identified as the culprit and logged to scan history. The result can be submitted to the community database just like a plugin conflict.

Interpreting Results

Conflict Found — A single plugin (or theme) was isolated as the cause. All others are restored.
No Conflict Detected — All suspects were cleared. The issue may be server configuration, custom code, or something outside the scope of plugins and themes.
Cancelled — The scan was manually cancelled. All plugins restored.

Submitting to Community

After a conflict is found, the result card shows a "Help the community!" prompt. Clicking Submit Anonymously sends the plugin slug and name to the PluginShield community database. No site URL, username, or any other identifying data is ever sent.

Submitted conflicts appear in the Community Conflict Database alongside counts from other users who reported the same plugin. Community data refreshes every 12 hours.

Force Restore

If anything goes wrong mid-scan, click Force Restore All on the scanner page. This immediately renames all __ps_isolated directories back to their original names. If admin is completely inaccessible, connect via FTP/SFTP and manually rename directories ending in __ps_isolated.

Safe Update Mode Pro

Navigate to PluginShield → Safe Update to see all plugins with available updates.

Click Safe Update next to any plugin. PluginShield will:

Copy the current plugin directory to pluginname__ps_backup/
Redirect you to the standard WordPress update process
When you return, show Commit and Rollback options alongside the Risk Score

Test your site thoroughly, then:

Commit — Deletes the backup. Update is now permanent.
Rollback — Deletes the updated version, renames the backup back. Site is instantly restored.

⚠️

Update sessions automatically roll back after 2 hours if neither Commit nor Rollback is selected.

Update Risk Score Pro

Every plugin on the Safe Update page shows a 1–5 risk score before you click update. The score is calculated from four independent signals pulled from the WordPress.org Plugins API:

Changelog keywords — High-impact: "breaking change", "major rewrite", "migration required", "incompatible". Medium: "security", "vulnerability", "CVE-". Low: "removed", "deprecated", "dropped support".
Support thread spike — Unusually high ratio of new unresolved threads in the 7 days following the release indicates user pain.
Rating drop — If the plugin's star rating fell since the last cached check, the score increases.
Version jump — A major version bump (e.g. 1.x → 2.x) raises the baseline score regardless of other signals.

Scores are cached per plugin for 6 hours so the Safe Update page loads fast. The score is displayed with a colour-coded badge (green → red) and an expandable explanation of which signals fired.

ℹ️

A high risk score doesn't mean you shouldn't update — it means you should test carefully first. That's exactly what Safe Update Mode is for.

Plugin Health Dashboard Pro

Navigate to PluginShield → Plugin Health and click Run Health Check.

PluginShield queries the WordPress.org API for each active plugin and checks for:

Abandoned — Not updated in 2+ years.
Untested — The plugin author has not tested against your current WordPress version.
PHP Incompatible — The plugin requires a different PHP version than your server runs.
Removed from repo — The plugin no longer appears in the WordPress.org directory.

Results are cached for 24 hours. Each issue can be individually dismissed with the Ignore button.

PHP Error Attribution Pro

Navigate to PluginShield → PHP Errors to see a weekly breakdown of PHP errors attributed to each plugin.

PluginShield installs a silent PHP error handler that captures warnings, notices, deprecated calls, and fatal errors during normal WordPress execution. Each error is traced to the plugin file it originated from, not just logged as a generic PHP error.

How attribution works

When a PHP error fires, PluginShield checks whether the error originated from a file inside wp-content/plugins/. If yes, it maps the file path back to the plugin slug and increments that plugin's weekly error count. Errors from themes, WP core, and must-use plugins are excluded.

Error log management

Errors are grouped by plugin, week, and error type (warning / notice / deprecated / fatal)
Log is pruned automatically after 4 weeks
Badge count in the admin menu shows new errors this week
Use the Clear Log button to reset the log at any time

ℹ️

PHP Error Attribution is production-safe. No output is added to page responses. No debug mode is required. It runs quietly in the background at all times.

DB Footprint Tracker Pro

Navigate to PluginShield → DB Footprint to see what database tables and wp_options entries each installed plugin has created.

How scanning works

PluginShield detects a plugin's database footprint by matching its directory slug against table names and option keys in your database. For example, WooCommerce's slug is woocommerce, so PluginShield finds all tables like wp_woocommerce_* and options like woocommerce_*.

Automatic capture

On activation — PluginShield scans and records the plugin's footprint immediately after it activates.
On deactivation — PluginShield diffs the stored footprint against what still exists in the database. Anything that remains is flagged as leftover debris.

Manual scan

Click the Scan button next to any plugin on the DB Footprint page to refresh its record on demand. Use Scan All Active Plugins to run a full sweep — this is useful the first time you use the feature.

Reading the results

Click any count to expand and see the full list of table names or option keys.
Rows with orange highlighting have leftover debris after deactivation.
Clean badge means the plugin deactivated without leaving anything behind.

⚠️

The DB Footprint Tracker identifies debris but does not delete it. Manually removing database rows and options should only be done if you are certain the plugin will not be reactivated, as some plugins store settings that are intentionally preserved across deactivations.

Email Alerts Pro

Go to PluginShield → Settings and enable Email Alerts. Enter the address you want notifications sent to. PluginShield will email you when a conflict is found during a scan or when a health issue is detected.

Scheduled Scans Pro

Go to PluginShield → Settings and enable Scheduled Scans. Set the frequency to daily, weekly, or monthly. PluginShield uses WP-Cron to run automated health checks and notify you of any new issues via email (if alerts are also enabled).

Community Conflict Database

The Community Conflict Database is a shared, anonymously-contributed record of conflict-causing plugins reported by PluginShield users across thousands of WordPress sites.

After a scan finds a culprit, you'll see a "Help the community!" prompt in the result card. Clicking Submit Anonymously records the plugin slug on the PluginShield server and increments its community count. You can also submit previously-found conflicts from the Known Conflicts page in your admin.

The Known Conflicts admin page shows:

This Site — how many times this plugin was found as a culprit on your own site
Community — the aggregated count from all PluginShield users worldwide
Submitted — whether you've already submitted this result to the community

Privacy & Data

When you submit a conflict to the community database, the following is sent to pluginshield.com:

The plugin directory slug (e.g. woocommerce)
The plugin display name (e.g. "WooCommerce")
Your WordPress version
Your PHP version

Never sent: site URL, admin username, email address, plugin license key, or any other personally identifiable information.

Community data is rate-limited to one submission per IP address per plugin slug per hour to prevent abuse.

Filesystem Permissions

PluginShield requires the web server process to be able to rename directories inside wp-content/plugins/.

Check current permissions

ls -la wp-content/plugins/

Fix permissions (if needed)

chown -R www-data:www-data wp-content/plugins/
chmod -R 755 wp-content/plugins/

Managed Hosting

Most managed WordPress hosts (WP Engine, Kinsta, Flywheel, Cloudways) allow renaming within wp-content/plugins/ because the web server runs as the same user that owns your files. If PluginShield reports a permissions error, contact your host and ask whether the PHP process has write access to wp-content/plugins/.

FAQ

Will the scan affect my visitors?

No. Plugin isolation is scoped to your admin browser session via PHP session state. Visitors' page requests run with all plugins active throughout the scan. Note: theme testing briefly switches the active theme, which is visible to visitors for ~30 seconds.

What if I have a white screen mid-scan?

Navigate directly to /wp-admin/admin.php?page=pluginshield-scanner and click Force Restore All. If admin is completely inaccessible, connect via FTP/SFTP and rename any directories ending in __ps_isolated back to their original names.

Can I exclude plugins from the scan?

Yes. Before starting a scan you'll see a checklist of all active plugins. Check any you want to exclude — these will never be isolated during the scan.

Does the DB Footprint Tracker delete database rows?

No. It only identifies and reports debris. It never modifies or deletes any database data.

Does PHP Error Attribution slow down my site?

No measurably. The error handler adds a single function call to PHP's error pipeline. It uses buffered writes (batched at the end of each request) so there are no per-error database queries during page execution.

How do I get support?

Free users: WordPress.org support forums.
Pro users: support@pluginshield.com with priority response.

Still need help? We're happy to help you find the conflict.

WP.org Forums Email Support