Documentation

Everything you need to install, configure, and use SmartFix.

Getting started

Installation

Install SmartFix from the WordPress plugin directory or upload the ZIP file manually.

Option A: From WordPress admin

Go to Plugins → Add New
Search for “SmartFix”
Click Install Now, then Activate

Option B: Via WP-CLI

$ wp plugin install smartfix --activate

Option C: Manual upload

Download smartfix.zip from WordPress.org
Go to Plugins → Add New → Upload Plugin
Upload the ZIP and activate

First run

After activation, SmartFix automatically registers your site with the analysis backend. This happens on the first admin page load and takes about 1 second. No API key or account required.

You'll see the SmartFix menu item in your admin sidebar (shield icon). Click it, then click “Run Scan.”

Running scans

Click the “Run Scan” button on the SmartFix admin page. The scan process:

Local scan (1–3s): Reads PHP files from all active plugins, extracts hooks, assets, post types, REST routes, and recent error log entries.
Upload to backend (<1s): Sends the extracted data to smartfixwp.com/api/plugin/report.
Analysis (2–6s): Backend runs rule-based detection, checks the known conflict database, and runs AI analysis on ambiguous cases.
Results displayed: Conflicts appear in your admin panel, sorted by severity.

Note: Scans are manual only. Nothing runs automatically or on the frontend. Your visitors are never affected.

What gets scanned

SmartFix reads PHP files up to 2 directories deep in each active plugin folder. It skips vendor/, node_modules/, .git/, and tests/ directories.

What gets sent to the server

// Exact payload structure

{

"plugins": [{

"slug": "plugin-name",

"name": "Plugin Name",

"version": "1.2.3",

"hooks": [{"hook": "init", "type": "action", "priority": 10}],

"assets": [{"handle": "select2", "type": "js"}],

"post_types": ["portfolio"],

"rest_routes": ["myapi/v1/items"]

}],

"wp_version": "6.7",

"php_version": "8.2.14",

"error_log": "...last 20 plugin-related errors..."

}

No PHP source code is sent. Only extracted metadata (hook names, priorities, asset handles, slugs).

Understanding results

Severity scale

Critical8–10/10. Likely causing visible breakage now. Fix immediately.

High6–7/10. May cause issues under certain conditions. Fix soon.

Medium4–5/10. Performance impact or minor functionality overlap. Fix when convenient.

Low1–3/10. Cosmetic or theoretical. Monitor but no action needed.

Conflict types

Type	Detection method	Typical severity
Hook priority	Rule-based	4–9
Duplicate asset	Filename fingerprint	5
Post type collision	Rule-based	8
REST route collision	Rule-based	6
Output conflict	AI analysis	5–8
Known conflict	Database lookup	Varies

Dismissing conflicts

Click the × button on any conflict to dismiss it. Dismissed conflicts are stored in WordPress options and won't appear in future scans.

To un-dismiss: delete the smartfix_dismissed_conflicts option from your database, or deactivate and reactivate SmartFix.

API reference

SmartFix uses three API endpoints on smartfixwp.com. These are called automatically by the WordPress plugin — you don't need to call them manually unless building a custom integration.

POST/api/plugin/register

Called on first admin load. Creates a site record and returns a site key.

// Request body

{ "site_url": "https://example.com",

"admin_email": "admin@example.com",

"site_name": "My Site" }

// Response

{ "site_key": "sfx_abc123...",

"site_id": "uuid" }

POST/api/plugin/report

Called when you click “Run Scan.” Sends plugin data, receives conflict analysis.

Requires X-Site-Key header.

GET/api/plugin/status?site_key=sfx_...

Returns the latest scan results and active conflicts for a site.

Troubleshooting

“Site not registered” error

SmartFix auto-registers on first admin page load. If it fails (network issue, firewall blocking outbound requests), reload the SmartFix admin page. Registration retries every 5 minutes.

Scan takes too long or times out

The AJAX request has a 60-second timeout. Sites with 50+ plugins may take longer. If your server's max_execution_time is low, the local scan may time out before reaching the backend. Increase it to 120s.

No conflicts found (expected some)

SmartFix is conservative. It only reports conflicts it can verify. If two plugins use the same hook at different priorities, that's normal WordPress behavior and isn't flagged. Only same-priority collisions on critical hooks are reported.

Plugin files not found

SmartFix looks for plugin files in WP_PLUGIN_DIR. If your plugins are symlinked or in a non-standard location, the scanner may not find them. Mu-plugins are not currently scanned.

FAQ

Does SmartFix modify any plugin files?

No. SmartFix is completely read-only. It reads PHP files using file_get_contents() and regex, but never writes to any files.

Is it safe to use on production?

Yes. The scan is a read-only operation that runs in the admin panel. It does not affect the frontend, modify the database (other than storing results), or interfere with any plugin behavior.

What about mu-plugins?

Currently, SmartFix only scans plugins in the standard wp-content/plugins/ directory. Mu-plugins and drop-ins are not scanned yet. This is planned for a future version.

Can I use SmartFix with WP-CLI?

Not yet. A wp smartfix scan command is planned for a future version.