=== Clashlens – Conflict Detector ===
Contributors: sungraizfaryad
Tags: plugin conflict, troubleshooting, debug, site health, compatibility
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 8.0
Stable tag: 1.0.0
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Find which plugins are conflicting on your site. Scans for jQuery overrides, PHP errors, hook collisions and known incompatible plugin pairs.

== Description ==

Something on your site breaks. The slider stops moving, the checkout button does nothing, a page turns white. The usual advice is to deactivate every plugin and switch them back on one at a time, which means taking your live site apart while visitors are on it.

Clashlens reads the evidence instead. One click scans your active plugins and gives you a severity-rated report: green when things look fine, red when something needs attention, and a named plugin wherever the data supports one.

= What Clashlens checks =

**Known incompatible plugin pairs.** Your active plugins are compared against a curated list of combinations known to clash: two SEO plugins competing over meta tags, two caching plugins writing conflicting output, duplicate SSL redirect handlers causing redirect loops, two page builders fighting over the editor. Each hit names both plugins and explains the problem in one sentence, so you know exactly which one to deactivate. Pairs that are merely redundant rather than harmful are marked as such and never inflate your overall status.

**Dangerous overrides and jQuery conflicts.** Every PHP file of every active plugin is scanned for calls that commonly break other plugins: `remove_all_actions`, `remove_all_filters`, deregistering jQuery, or dequeuing core styles. A plugin that deregisters jQuery is one of the most common reasons a slider, lightbox, or form suddenly stops working. Scanning is capped per plugin so it stays fast on large sites.

**PHP errors grouped by plugin.** Clashlens reads your debug.log and attributes fatal errors, warnings and notices to the plugin that produced them, over the last 7 days. A plugin generating 50 or more errors in a single day is flagged critical. Only the tail of the log is read, so even a multi-gigabyte debug.log will not exhaust memory.

**Hook collisions.** Hooks where three or more plugins registered callbacks at the same priority are listed as investigation starting points. Common core lifecycle hooks are excluded because crowding there is completely normal, and this check deliberately never rates your site critical on its own.

= Who it is for =

Site owners debugging a broken page, developers taking over an unfamiliar site, agencies auditing client installs before an update, and anyone who has ever lost an afternoon to plugin compatibility troubleshooting.

= What it will not do =

Clashlens never deactivates, modifies, or repairs anything. It reports what it finds and leaves every decision to you. It also cannot see JavaScript errors that happen in the visitor's browser, and because the scan runs in the admin area, hooks that plugins register only on front-end requests are invisible to the hook collision check. Both are on the roadmap.

= Privacy =

Clashlens sends nothing anywhere. No external requests, no tracking, no analytics. Scan results are stored in your own database and removed when you uninstall the plugin.

== Installation ==

1. Upload `clashlens` to `/wp-content/plugins/`, or install it from Plugins → Add New.
2. Activate the plugin through the Plugins screen.
3. Go to Settings → Clashlens and click **Run Scan**.

Results stay stored until you run the next scan, so you can close the page and come back to them.

== Frequently Asked Questions ==

= Does it deactivate or fix conflicts automatically? =

No. It reports conflicts so you can investigate and decide. Automatic deactivation on a live site would be far too risky.

= My slider stopped working after installing a plugin. Will this find the cause? =

Often, yes. The most common cause is a plugin deregistering or dequeuing jQuery, which Clashlens reports by name under Dangerous Overrides. If the conflict also produces PHP errors, those get attributed to the responsible plugin too. What it cannot yet see is a JavaScript error occurring in the visitor's browser, since that never reaches the server.

= The hook collision section shows results. Is my site broken? =

Not necessarily. Congested hooks are potential conflict points, not confirmed bugs. Use them as a starting point for investigation. This detector never rates your site critical on its own.

= I get "No debug.log found". What should I do? =

Enable `WP_DEBUG_LOG` in your wp-config.php, let the site run for a while, then scan again. Without a log there is nothing for the error detector to read.

= Are front-end hooks covered? =

The scan runs in an admin context, so hooks that plugins register only on front-end requests are not visible to the hook collision detector. The other three checks are unaffected. Front-end analysis is planned for a future version.

= Can I add my own known conflict pairs? =

Yes. Use the `clashlens_known_conflicts` filter in a custom plugin or mu-plugin. Each entry is `[ 'slug-a', 'slug-b', 'Explanation', 'warning' ]` and the fourth element is optional, either `'warning'` or `'info'`, defaulting to `'warning'`.

= Does it slow down my site? =

No. Nothing runs on the front end and nothing runs on a schedule. Code executes only while you are on the Clashlens settings page and you press Run Scan.

= What are the requirements? =

WordPress 6.0 or newer and PHP 8.0 or newer.

== Screenshots ==

1. The scan report, showing overall severity and per-check findings with the responsible plugins named.
2. The starting screen. One button runs the scan; nothing is checked until you ask for it.

== Changelog ==

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.0.0 =
Initial release.
