WordPress and WooCommerce connector¶

Use this plugin to connect a WordPress or WooCommerce site to Patcherly for automated PHP fatal, parse-error, and white-screen detection and AI-assisted fixing. For non-WordPress apps (standalone PHP, Node, Python), use the Universal Installer instead.

Post-apply shell restarts are not available on WordPress. The plugin only changes files on your site - it never runs commands on your server (WordPress.org plugin-directory rule and a safety feature). For automated restarts or tests after a patch, use a standalone Python, Node.js, or PHP connector. See Restart after a fix.

What the plugin sends to Patcherly¶

The plugin talks to one external service: api.patcherly.com. It does not contact Patcherly when WordPress activates the plugin, when you switch themes, or on every page load.

• Before you click "Connect with Patcherly", the plugin sends nothing. No background calls, no pings.
• After pairing, when an error happens on your site, the connector sends the error details (message, file path, line number), a small snippet of the file around the error, and basic site information (your site URL and WordPress / PHP / plugin versions). It never sends your database, your media library, your user data, or your full site files.
• Site information for the AI (active plugins, theme, WooCommerce status) is uploaded when you click Refresh site context in Settings (or View collected context in Connector Status), once automatically right after pairing if you have already chosen Full or Minimal sharing, and on your next Patcherly admin visit after you activate or deactivate another plugin (when sharing is enabled).
• Your authentication credentials are stored encrypted in your WordPress database.

Early error capture (Rescue): Patcherly also installs a small emergency logger that can catch PHP fatals during plugin load - before your normal error log might record them. Those errors appear in the dashboard like any other error (with the same message format). If both Rescue and the main log monitor see the same fatal, Patcherly keeps one open incident and prefers the most complete stack when available. If you use a custom log path, Rescue may still see errors in debug.log or its own emergency log that your custom file does not contain.

When you expand an error's full text in the dashboard or WordPress admin, Patcherly may append a short source line at the bottom so you can tell how it was captured:

• (Patcherly Emergency Logger) - the error was detected by Emergency Rescue while your site was down or the main plugin could not run (for example a white screen after a bad site update). Rescue still sent the log line to Patcherly so you could see the failure and roll back or approve a fix.
• (Patcherly Advanced Logger) - reserved for errors captured by the main WordPress plugin's normal log monitoring while your site is up (Settings → Advanced). Rescue-sourced errors use the Emergency label instead.

The table preview stays a short headline only; open the full error text to see the source line.

See Privacy Policy and Terms of Service for the full details.

Installation¶

Method 1: Manual Installation¶

1. Download the Plugin

2. Download the patcherly plugin zip from the dashboard or installer

3. Upload to WordPress

4. Navigate to your WordPress site's /wp-content/plugins/ directory

5. Upload the patcherly folder

6. Activate the Plugin

7. Log in to your WordPress admin panel
8. Go to Plugins → Installed Plugins
9. Find "Patcherly" and click Activate

Method 2: WordPress Admin Upload¶

1. Go to Plugins
2. Log in to WordPress admin

3. Navigate to Plugins → Add New

4. Upload Plugin

5. Click Upload Plugin
6. Choose the patcherly.zip file

7. Click Install Now

8. Activate

9. After installation, click Activate Plugin

Configuration¶

Step 1: Open Home¶

1. After activation, you'll see "Patcherly" in the WordPress admin menu (shield icon).
2. Click Home (or the top-level Patcherly menu item) to open the overview page.

Step 2: Connect the connector¶

To connect your site with your Patcherly account, click Connect with Patcherly on the Home page (or use the Connect button in the account status bar when not connected).

To disconnect, click Disconnect on Home when connected, then Connect with Patcherly again. If the account bar shows Connection lost - reconnect required, click Re-Connect Account once - it clears the old connection and starts Connect with Patcherly in place (approve at the dashboard when prompted).

Step 3: Settings (Optional)¶

Open Patcherly → Settings for advanced options, collected site context, and diagnostics. Connecting happens on Home, not Settings.

• Patcherly API endpoint: Defaults to https://api.patcherly.com. Don't change it unless Patcherly Support instructs you to.
• Errors Cache TTL: How long to cache error lists (default: 300 seconds).
• Cleanup on Uninstall: When enabled, removes all plugin settings and the wp-content/uploads/patcherly/ folder (including pre-apply backups) when you delete the plugin. See Deactivation vs uninstall.
• Demo submenu (default OFF): show or hide the Patcherly → Demo (explore) submenu. Tick when you want the local demo tour.
• Debug Mode (optional, default OFF): see Debug mode below.
• Site context for the AI (default Off): choose Full, Minimal, or Off - see Context Collection for what each tier sends. Use View collected context to see exactly what would be shared and what Patcherly last stored.

Demo mode - explore without pairing¶

The Patcherly → Demo opens a demo Errors page with example WordPress / WooCommerce / generic-plugin errors in various states. This is a demonstration of what the Error page will look like, once you connect your Patcherly account with the plugin.

Use Demo mode to preview the connector UX before you pair a real site, or to walk a team member through the workflow without touching production data.

• No data leaves your server. The demo page never interacts with Patcherly servers, the data is just for test.
• No AI calls. Nothing is sent to any language-model provider.
• No database writes. State lives in sessionStorage (per browser tab), not in your site's database. Closing the tab resets the demo.

Enable the Demo (explore) submenu by ticking Demo submenu in Settings → Advanced settings when you want the local tour (default is OFF).

The Demo and live Errors tables share the same columns, row-action icons (two rows: analyze/preview/approve/reject on top; mark fixed/ignore/delete below), and two footers under the table: an action-icon legend and a status-badge legend (same labels and colors as the Status column - Analyzed, Ready to Patch, and Manual review use the same blue tone; Suspicious is a separate red quarantine flag; Bad patch (red) appears when you reject a draft as wrong; orange Source changed / Stale patch appear when the file on the site no longer matches what analysis or apply expected; waiting badges keep their stage color with a short pulse or spin - apply green, rollback amber, analysis sky-blue). Ongoing action icons (Waiting for connector / In progress) use the same stage colors with a pulse and no fill background. Each legend includes a small Help link for more detail. Dashboard legends also collapse to a short preview with Show all; the WordPress plugin legends stay fully expanded. Excluded path-rule rows appear slightly faded; use Hide Error & Ignore to remove them from the default list. Hover any row icon or badge for the full tooltip. Above the table, Filters (collapsed by default) and Columns sit in the toolbar next to bulk actions - same pattern as the Patcherly dashboard.

When your site won't load¶

If a theme or plugin fatal leaves WordPress showing a blank screen, the normal Patcherly plugin may not load - but Rescue mode can still help.

flowchart TD
    A[A theme or plugin causes a PHP error] --> B{Can the main Patcherly plugin still run?}
    B -->|Yes| C[Errors are logged and sent to Patcherly]
    B -->|No - blank or broken site| D[Rescue must-use plugin runs early]
    D --> E[Rescue logs the error and can roll back or apply fixes]
    C --> F[You see the error in Patcherly and can approve a fix]
    E --> F
    F --> G{Fix made things worse?}
    G -->|Yes| H[Rollback restores files from your local backup folder]

When even Patcherly cannot help (rare): if PHP crashes inside wp-config.php before WordPress starts, if another must-use plugin crashes before Rescue loads, or if you deleted the local backup folder: Rescue cannot capture errors or roll back. Use your hosting provider's snapshot or restore files manually from wp-content/uploads/patcherly/backups/.

On pairing, Patcherly prepares storage under wp-content/uploads/patcherly/ (backups, locks, queue, emergency log, and a cache/ subfolder for local AI context JSON). The plugin writes Apache .htaccess and IIS web.config deny files in those folders (including nested backup and cache dirs). Tools → Site Health and Settings → Diagnostics explain when a canary URL returns HTTP 200 (common on Nginx without a deny rule) and how to add optional vhost hardening. Optional PATCHERLY_BACKUP_ROOT moves backups only - queue, fix-cache, locks, and emergency.log stay under uploads/patcherly and still need a vhost deny on Nginx (see Connectors overview). Right after pairing, the Home page shows a short onboarding card where you choose site context for the AI (Full / Minimal / Off), confirm Emergency Rescue (must-use helper, recommended, on by default), and - if the site has no debug logging yet - allow the wp-config snippet (recommended, on by default). If logging is already configured, Get started skips the snippet and registers any custom log path when your plan allows. Click Get started - that is your explicit consent; pairing itself never writes the must-use file or wp-config.

Emergency Rescue copies one small must-use file (000-patcherly-rescue.php) into your must-use plugins folder so Patcherly can still reach your site when the main plugin cannot load - for example after a plugin update that causes a white screen. Without it, Patcherly may not be able to roll back or restore your site in that emergency. You can turn Rescue off later in Settings → Advanced.

If install or update fails with a permissions error (common when wp-content/mu-plugins/ is owned by a deploy user), Patcherly fails closed without writing Permission denied warnings into your PHP error log, and stops retrying automatically so the log is not flooded. Fix file ownership/permissions for that folder (or reinstall Rescue from Settings → Advanced after your host grants write access).

Did you know? The Patcherly WordPress plugin is loaded by WordPress in the same PHP process that serves your site - just like any other plugin. A fatal error in your theme or another plugin can white-screen the site and stop the main Patcherly plugin (and all other plugins) from running normally. Emergency Rescue solves that in-process coupling: it is a must-use (MU) plugin that loads earlier than regular plugins, so it can still log errors, apply approved fixes, and run rollbacks you trigger from the dashboard even when the main plugin - or the site itself - cannot load. Patcherly built it to stay crash-independent because WordPress loads plugins in a fixed order, and a broken plugin update is one of the most common ways sites go down.

Rescue then:

• Writes PHP errors to wp-content/uploads/patcherly/emergency.log and tails wp-content/debug.log when enabled
• Sends new log lines to Patcherly even when the main plugin cannot run
• Picks up Rollback requests from the dashboard and restores files from your local pre-apply backups
• Applies approved fixes when the main plugin is down (same backup + verify flow)

wp-config bootstrap (recommended when logging is not set up yet): On Get started, if the site has no PHP error logging yet, the snippet checkbox defaults on and applies with your consent. If logging is already configured, Get started skips the snippet and registers any custom log path when your plan allows. You can still apply the Patcherly snippet later in Settings → Advanced - never automatic on pairing.

Run rescue now¶

On Sites, expand a WordPress site and use Run rescue now. That sends one signed request from Patcherly to your site - the same rescue ping path used automatically after you Approve a fix or start a Rollback when the main plugin may be down.

Status under the button is green when Rescue is healthy (MU-plugin installed, error logging ready - Patcherly snippet or your own logging setup - and emergency log writable). Red means at least one of those checks failed.

When to use it

• Your host has slow or missing WP-Cron and you want Rescue to check now
• The site is white-screened (main plugin cannot load) and you just approved a fix or clicked Rollback
• You changed Cloudflare / bot settings and want to re-test whether the ping can reach WordPress

What to expect

• The button shows Pinging… briefly. Success means the request reached Rescue (or you see a clear failure if it did not)
• Rescue only acts on work already waiting: new emergency / debug log lines, an approved fix to apply, or a rollback request. It does not invent a fix or “heal” the site by itself
• If the main plugin is still healthy, its normal poll often handles the same work; Rescue is the early / crash-independent path

Honest limits

• Not a Cloudflare bypass. The ping is inbound HTTPS to your site, same path Bot Fight Mode can block with a 403 / “Just a moment…”. If that happens, use Patcherly → Errors → Retry Patch in wp-admin (outbound from your server) - see Cloudflare: rescue ping blocked
• Needs Emergency Rescue installed and WordPress able to start (Rescue cannot run if PHP dies in wp-config.php or an earlier must-use plugin crashes first)
• Rollback still needs your on-site backup files under wp-content/uploads/patcherly/backups/

How rollback is coordinated: after a failed health check, Patcherly sets the error to rolling back and pings Rescue on WordPress sites only. If the main plugin is still alive, its own rollback cron runs first; Rescue steps in only when the main plugin cannot load or has gone quiet. Both paths use the same on-site backups and a file lock so they cannot fight over the same restore.

Limits (Rescue overall): Rescue cannot run if PHP dies inside wp-config.php before WordPress loads, if another must-use plugin fatals first, or if you deleted the local backup folder. In those cases use your host snapshot or restore files manually from wp-content/uploads/patcherly/backups/. On a VPS where must-use plugins are disallowed, the PHP connector on the same host can fill a similar role - it polls on a schedule without needing wp-admin visits.

Managing the connection¶

Once your site is paired, the plugin keeps a secure connection open to Patcherly. Every fix it receives is verified before being applied, and every message it sends to Patcherly is signed so the server knows the request really came from your site. Failed calls are retried automatically.

Reconnecting¶

If credentials need a full re-pair (plugin shows Connection lost / dashboard Re-auth required):

1. Prefer Auto-Reconnect on the Sites row in the Patcherly dashboard (for re-auth it opens this plugin’s Home with a reconnect prompt), or
2. On the site: Patcherly → Home → Re-Connect Account once (clears the old connection and starts Connect with Patcherly in place; approve at the dashboard when prompted).

Temporary network blips show Reconnecting… on Sites while Patcherly is actively retrying (or while you run Auto-Reconnect). The badge hides between scheduled waits and after retries stop - you usually do not need to Disconnect.

Agent offline (stale or inactive presence after a prior pairing) is different from Reconnecting…: the connector has not checked in recently. Use Auto-Reconnect to restore a live session. Never-paired sites show Pair site / Connect instead of Agent offline.

"This site isn't paired" notice¶

If you open Patcherly → Errors before pairing - or after your site has been removed from your Patcherly account - the Errors page shows a friendly notice at the top with a one-click link back to Home to (re)connect.

Supported Applications & File Types¶

✅ Supported Applications¶

The WordPress connector is designed specifically for WordPress websites:

• WordPress Core - Standard WordPress installations
• WordPress Multisite - WordPress network installations
• WordPress with Custom Themes - Any WordPress theme
• WordPress with Plugins - Any WordPress plugin
• Custom WordPress Applications - WordPress-based websites, blogs, e-commerce sites

✅ Supported File Types¶

The connector can patch and validate syntax for:

• .php - PHP files (themes, plugins, WordPress core files)
• .phtml - PHP template files

What gets patched: - WordPress theme files (/wp-content/themes/) - WordPress plugin files (/wp-content/plugins/) - Custom PHP files in your WordPress installation - WordPress core files (if you have write permissions)

❌ Not Supported¶

Other file types: - JavaScript files (.js) - Client-side JavaScript is not patched - CSS files (.css) - Stylesheets are not patched - Other languages (Python, Node.js, etc.) - Database content - The connector patches code files, not database entries

Note: Before applying a fix, the plugin snapshots all existing paths in the patch into your local backup folder under wp-content/uploads/patcherly/backups/. Snapshot filenames never keep a runnable .php extension (hosts such as WP Engine often block creating PHP under uploads). The plugin checks the modified files for syntax errors before and after applying a fix. It's purpose-built for WordPress and can also share WordPress-specific information (active plugins, theme, etc.) with the AI to produce better fixes - see Context Collection below.

For non-WordPress PHP applications: Use the PHP Connector instead.

Features¶

Error Management¶

• View errors - browse, filter by status, severity, or language.
• Bulk delete - select multiple errors and remove them in one click when they were never applied (noise, ignored rows, pre-fix workflow). Delete is not available for successfully patched errors or any row after a patch apply attempt - use Hide Error & Ignore for list cleanup instead; older rows are pruned by audit retention. Delete is permanent (there's no trash), does not undo fixes on your site (use Rollback for that), does not refund quota, and does not touch connector backups on your server. Your dashboard metrics stay accurate.
• Live updates - the errors list refreshes automatically.
• Detailed view - full error message, stack trace, file snippet, and the patch preview.

Fixes, confidence, and plan limits¶

The plugin applies patches you approve in wp-admin or the dashboard. Low-confidence fixes may require explicit confirmation in the dashboard before apply - the plugin shows a notice when that gate is active. Auto Apply and Auto Analysis controls follow your workspace plan and dashboard policy; the plugin mirrors those limits in its UI.

See Approving fixes and Site paths.

Context Collection¶

The plugin can share a small amount of information about your WordPress install with Patcherly so the AI can suggest better fixes. You're in charge: nothing is shared until you pick a tier.

Right after pairing, the Home page shows an onboarding card: pick Full, Minimal, or Off for site context, confirm Emergency Rescue (recommended), and - when the site has no debug logging yet - allow the wp-config snippet (recommended). If logging is already configured, that checkbox is skipped and any custom log path is registered instead. Then click Get started. You can change these choices any time in Settings → Advanced settings.

Privacy: Patcherly does not collect or store your database, user accounts, or site content. Only technical information about your install (versions, and optionally plugin/theme names) is shared when you choose Full or Minimal and click Refresh site context.

• Full - share your active plugins, theme, custom post types, WooCommerce status, and server / database info. Recommended for the best AI suggestions.
• Minimal - share only the WordPress version, PHP version, and database version. Nothing about your installed plugins, themes, or content.
• Off (default) - share nothing. The AI sees only the error message itself. A good starting point if you want to begin carefully and upgrade later.

Nothing is uploaded on activation, theme change, or every page load. After you click Get started with Full or Minimal, the first context upload runs once automatically. You can also click Refresh site context in Settings any time later. When you activate or deactivate another plugin, the connector notes the change locally and uploads an updated snapshot on your next visit to Home, Settings, or Errors (no outbound call on the activation hook itself).

Why sharing context helps: - More accurate AI fixes, tailored to your environment. - Better understanding of how your plugins and theme interact with the bug. - Fewer rounds of back-and-forth before a fix lands.

Where your choice is stored: in your own WordPress site (your site's options). The plugin re-reads it before every upload - if you switch to Off, the next Refresh site context click stops and tells you where to switch it back on.

View collected context: On Home (Connector status → Context sharing row) or Settings → Site context for the AI, click View collected context → to open the collected-site-context panel. It shows a live preview of what this site would share at your current tier and, when paired, the last copy stored on Patcherly after an upload.

Home overview (metrics and audit)¶

When the site is not connected or sign-in expired, the Connect this site to Patcherly pairing block appears above the Overview metrics cards.

Above Overview, a Monitoring live for bugs strip shows whether Patcherly is watching this site (connection, logs, Emergency Rescue). Healthy quiet sites show All systems OK. If something needs attention, the title turns red; connect/reconnect copy points at Connect / Re-Connect Account on this page, and Rescue / log paths / server URL problems link to Settings. While plan and workspace details load, the account bar shows Loading Workspace info beside Connected to Patcherly.

The Home page shows a metrics preview for your paired site when your plan includes advanced analytics (Core, Pro). Personal plans see sample numbers with an upgrade link to billing. Money saved and usage counts use the display currency and number format from the dashboard Profile → Preferences of the user who paired this site (formatting only - the underlying values come from Patcherly). Until prefs arrive, Home defaults to EUR with comma thousands. View full metrics on dashboard → opens the Patcherly metrics page scoped to this site.

Bugs Pending is a live open backlog for this site (not limited to the 30-day window). Bugs caught and Errors analyzed stack in the last column for the Overview window. Fixed / time / money cards sit in the middle.

When Dry-run is on for this site, Home and Errors show a red notice. The account status bar can Turn Dry-run off or Turn Test Mode off (enable either mode only from the dashboard Sites page). Connector Status shows a red Dry-run Enabled badge only while Dry-run is on.

Pause site (maintenance silence for deploys) is available near the top of Patcherly → Settings: turn it on for 4 hours (or resume early). It matches Pause site on the dashboard Sites page and does not enable Dry-run or Test Mode. Security Protection mode still requires the dashboard Sites page to release.

A usage limits bar (Fixes used counts analyses that finish with an applyable code patch this billing period - Not patchable and Bad-patch no-ops do not consume a unit; quality re-analyze after Bad patch is capped separately; Sites and Users vs plan caps) and Workspace name appear in the account status area when connected. The reset line reads Usage resets on <date> for your current billing period.

The Errors analyzed card counts errors where AI analysis completed on this site (still-pending errors and analysis that could not finish for technical reasons are excluded). It is not the same counter as Fixes used - the usage bar is workspace-wide and tied to your plan billing window. Hover the ⓘ icon beside any usage or metric label for a short explanation.

Recent errors (last 3 for this site, any status except test samples) appear above audit events (last 3 workflow events) below the metrics cards. The audit table includes an Actor column (resolved name or system label). View errors in WordPress → opens the plugin Errors page; View full audit log on dashboard → opens the Patcherly audit page scoped to this site. Empty states: No recent errors for this site / No audit events yet for this site.

Custom Log Paths¶

If your plan includes Advanced Error Monitoring (Core, Pro - see Pricing page), you can configure custom log paths:

Get started (and later Home / Settings notices) can detect a custom error_log path in wp-config.php or theme functions.php and register it with Patcherly when your plan allows. Pairing never writes wp-config. Theme files are never edited.

1. In your Patcherly dashboard open Sites, expand this site, and click Customize next to Monitored Logs.
2. Under Add custom log, enter the path, optional description, keep Enabled on, then Add.
3. Review Custom logs, Detected logs, and Preset logs in that modal; Save if you changed anything.

From Connector Status, each path row's Customize button opens the same dashboard modal.

Example custom log paths (must pass path-safety rules for your connector type): - wp-content/debug.log (WordPress) - /_error_log.log (WordPress site root on managed hosts) - logs/error.log or /var/log/apache2/error.log (PHP / VPS: when allowed roots include /var/log/)

Requirements: - Custom log paths require the Advanced Error Monitoring plan feature - see the Pricing page for plan availability. Without it, the connector monitors the preset WordPress / PHP log locations only and adding custom paths is disabled (upgrade hint on Customize).

Connector Management¶

Status Monitoring (after pairing): - Dashboard shows connector connection status. - Displays last connected timestamp. - Shows connection health indicators.

Initiation from Dashboard: - The dashboard walks you through installing the plugin and clicking Connect with Patcherly in WP-Admin. - Pairing happens in one click - no API key to copy or paste.

Connector Status¶

The Connector Status panel is on Home, inside a collapsed Connector status section at the bottom of the page. It tells you at a glance whether your site is in good shape:

• Plugin version - which version of the Patcherly plugin you have installed, and whether it matches the latest Patcherly CDN release (up to date vs update available). That CDN signal is separate from the WordPress.org update notice on Overview (see Plugin updates). Always shown, even before pairing, so support knows which release you're on.
• API - is the Patcherly server reachable from your site.
• Authentication - whether your connection to Patcherly is active (the plugin rotates the access token automatically on each call) or needs re-pairing. Credentials stay fresh when the site talks to Patcherly; quiet sites get a small daily check-in via WordPress scheduled tasks. If that check-in stops (broken WordPress cron, host offline, or credentials revoked from the dashboard), click Re-Connect Account on Home to clear and re-pair.
• Scopes - the permissions this connector was granted at pairing time (e.g. ingest patch audit files). These are locked to the original device-code grant and never change for the life of the connection.
• Secure signing - whether every message between your site and Patcherly is being cryptographically verified (always Enforced once paired).
• Workspace - which Patcherly workspace this site is paired to.
• Plan - your workspace plan name (Personal, Core, Pro) with a link to billing to upgrade limits and features.
• Site - the website registered on your Patcherly account, and whether it's still active. If you've removed the site from your dashboard, the Errors page shows a one-click "Reconnect" notice.
• Last connected - the most recent time Patcherly heard from this site.
• Emergency Rescue - whether the must-use safety net is active (green), still installing, or off / install failed (red). Change this in Settings → Advanced.
• Test Mode - whether the per-site Test error window is currently open in your Patcherly dashboard. While it's ON, synthetic/test events for this site are tagged as samples so they don't pollute your real metrics or fire notifications. Turn it off from the Home account bar or the Sites page.
• Dry-run - red Enabled only while preview-only mode is on; otherwise blank. Turn Dry-run off from the Home account bar when it is on (enable it only on Sites).
• Monitored paths, Excluded paths, Patch exclusion paths - live values from your Patcherly site, each with a Customize button that opens the matching Sites modal (Monitored Logs, monitoring exclusions, or patch exclusions; upgrade link with a ⚡ icon when your plan lacks the feature).
• Context sharing - your Full / Minimal / Off tier, a link to change it in Settings, and View collected context → to inspect the snapshot panel.

Before pairing, every row that depends on the connection shows "Site not connected yet, pair it with Patcherly to run Diagnostics". The plugin will not call Patcherly on its own until you click Connect with Patcherly on Home. If you want to confirm Patcherly itself is up before pairing, expand Connector status on Home and click Refresh - that's the one and only call the unpaired plugin makes, and only when you click it.

Test Connection¶

Test your connection to the Patcherly server:

1. Go to Patcherly → Settings
2. Expand Diagnostics and click "Test Connection"
3. View connection status and diagnostics

Path Management on Settings lists monitored, excluded, and patch-exclusion paths (Customize opens Sites in the dashboard).

Test Mode (synthetic errors)¶

Test that error reporting works end-to-end without polluting your real metrics. Test events only flow while you've explicitly opened a Test Mode window from your Patcherly dashboard - this gate prevents an exposed connector credential, a curious script on your site, or a stray click from spraying synthetic traffic into your real error feed and triggering notifications. The window is per-site and lasts 30 minutes; you stay in control.

1. In your Patcherly dashboard go to Sites, click this site, and flip the Test Mode toggle ON: this opens a 30-minute window for this site only.
2. Use a real connector event or CLI send-test from other stacks; on WordPress, Confirm Test Mode is On in Connector Status, then trigger or wait for an ingest while the window is open.
3. Synthetic or windowed test events show up under Errors, flagged as samples when applicable.

The plugin's Connector Status panel shows whether Test Mode is On or Off. When it is on, the Home account bar can Turn Test Mode off without opening the dashboard.

Debug mode - share what your site asked Patcherly¶

Debug Mode is an opt-in local diagnostic surface designed for support escalations. It is OFF by default. When you turn it ON in Settings → Advanced settings, the plugin captures sanitized metadata about every API call it makes and lists them on a new Patcherly → Debug submenu.

What is captured¶

For each call the plugin made: when it happened, what it was for (e.g. "checking pairing status", "loading the errors list", "reporting a fix result"), the request method and URL, the HTTP status code, how long it took, and the error message if it failed.

What is NEVER captured¶

• Your authentication credentials or signing keys.
• The contents of any request - source-code snippets, AI prompts, settings.
• The contents of any response: AI-generated patches, error details.

Where the data lives¶

• On your own WordPress site only - in your site's database, capped at the most recent 200 entries (older ones drop off).
• Never sent to Patcherly. The Debug page itself does not make any outbound calls.

How to clear it¶

• Turning Debug Mode OFF in Advanced settings immediately deletes the option from your database.
• The Debug page also has a "Clear log" button.
• Uninstalling the plugin always deletes the option (even when Cleanup on Uninstall is off, this specific debug data is purged for safety).

For support reps¶

Ask the user to turn Debug Mode on → reproduce the issue → open Patcherly → Debug → click Copy as JSON → paste the JSON into the support ticket. Once triage is done, ask them to turn Debug Mode off to clear the captured entries from their database.

Security¶

• Encrypted credentials. Your authentication credentials are stored encrypted in your WordPress database - never as plain text, and never in any plugin file. A database-only leak cannot read them.
• Signed messages. Every message between your site and Patcherly is cryptographically signed and verified at the other end. Tampered or replayed messages are rejected automatically.
• No way to disable signing. Fix payloads without a valid signature are refused - this protects you from someone trying to push a malicious patch to your site.
• Revoke any time. Click Disconnect on Home or Settings to invalidate your current credentials. To rotate a healthy connection, Disconnect then Connect with Patcherly. If the account bar already shows Connection lost, use Re-Connect Account instead (one click clears and starts pairing). Disconnect while credentials are still healthy also tells the Patcherly server, so your dashboard's Sites page flips this site to inactive right away instead of waiting up to a week for the connection clock to age out.

Troubleshooting¶

"API server unavailable"¶

• Check that your site can reach api.patcherly.com (your hosting provider or firewall may be blocking it).
• Make sure your site is served over HTTPS.

"Authentication failed" or "token expired"¶

• On Patcherly → Home, click Re-Connect Account (or Disconnect, then Connect with Patcherly if you only see Disconnect).
• Make sure the Patcherly user account you used during pairing still has access to this site (your dashboard's Sites page should still list it).

"Sign-in expired - reconnect required"¶

This banner appears on Patcherly → Home (pair block) when the plugin still has your sign-in saved on disk, but the Patcherly server rejected the most recent silent refresh. It usually means the site went quiet for long enough that the refresh credential aged out (the plugin schedules a daily check-in to prevent this - but a site with no front-end visitors and no admin logins for 30+ days in a row can fail to fire WordPress' built-in scheduled tasks at all, which is what allows the credential to expire). You'll see the same situation reported three ways at once:

• Plugin Home: red sign-in expired notice with Re-Connect Account.
• Connector Status panel: OAuth row reads "Connection lost - please reconnect".
• Your Patcherly dashboard's Sites page: the row shows Re-auth required / Not apply-ready - use Auto-Reconnect, or Re-Connect Account on the plugin Home.

To fix it, prefer Auto-Reconnect on the Sites row, or click Re-Connect Account on Home (one click clears the old connection and starts pairing again; approve at the dashboard when prompted). The dashboard site clears reconnect state within a few minutes of the first successful API call from your re-paired site.

Site URL / hostname changed (clone or migrate)¶

If you clone production to staging, change the domain, or otherwise move the site so the hostname no longer matches the one used when you paired (for example example.com → staging.example.com), the plugin clears local pairing and shows an admin notice with the old and new URLs. It does not immediately revoke the original site on your Patcherly dashboard (so a cloned staging admin load cannot wipe production tokens). Switching only between http/https or adding/removing a leading www. does not trigger this.

1. On the Patcherly dashboard Sites page, update this site's URL to the new hostname (or add a new site for the new host).
2. On Patcherly → Home in wp-admin, click Connect with Patcherly and approve pairing again.
3. If the old Sites row still looks healthy after a real hostname move, use Unplug / Force Disconnect on that row.

After a successful Connect, the notice clears automatically. You can also dismiss it with the notice's Dismiss control (the WordPress core X alone does not persist). A later different host change shows it again.

If the Sites URL still points at the old host, Connect may fail with "site not registered".

"Signature mismatch"¶

• Click Re-Connect Account on Home (or Disconnect, then Connect with Patcherly) to get a fresh credential.
• Check that your server's clock is correct (this is rarely the issue, but worth checking if everything else is fine).

"This endpoint requires HTTPS"¶

• Make sure your WordPress site is served over HTTPS.
• If your site sits behind a reverse proxy (nginx, Cloudflare, etc.), make sure that proxy tells your WordPress install that the original request was HTTPS. Without it, your site may think requests are HTTP, and Patcherly rejects HTTP. Most managed WordPress hosts handle this for you.

"Retry Patch" or rescue ping blocked (HTTP 403, "Just a moment…")¶

When Patcherly Approves a fix, starts a Rollback, you click Retry Patch, or you use Run rescue now on Sites, it sends a signed POST from our API to your site:

https://yoursite.com/wp-admin/admin-ajax.php?action=patcherly_rescue_poll

If Cloudflare Bot Fight Mode or a WAF rule treats that server-to-server request as a bot, the dashboard will show a dispatch failure until the edge allows the request through.

Patcherly registers Patcherly Agent with Cloudflare using Web Bot Auth (User-Agent: Patcherly-Agent/1.0, key directory on api.patcherly.com). After Cloudflare approves the bot, edge verification may improve on paid Bot Management plans - Free Bot Fight Mode may still block rescue until Cloudflare confirms otherwise or you turn Bot Fight Mode off.

Cloudflare Free: Bot Fight Mode must be off

On the Free plan, Bot Fight Mode cannot be bypassed with WAF Skip rules, Configuration rules, or IP allow/skip rules in our testing (Cloudflare’s own docs are inconsistent on exceptions). If Security → Events shows Service: Bot Fight Mode for action=patcherly_rescue_poll, the reliable fix today is:

1. Security → Settings (filter Bot traffic) → turn Bot Fight Mode off.
2. Re-test with Retry Patch or Run rescue now on the site.

You do not need to disable all Cloudflare security - only Bot Fight Mode on Free. Other WAF managed rules can stay on. If you need bot fighting and Patcherly rescue apply without turning Bot Fight Mode off, upgrade to Pro or higher and use Super Bot Fight Mode with the Skip rule below.

Cloudflare Pro+ - Super Bot Fight Mode + Skip rule

On paid plans, Super Bot Fight Mode runs on the WAF Ruleset Engine, so scoped Skip rules can work (Super Bot Fight Mode docs):

1. Security → Settings (filter Bot traffic) → turn Bot Fight Mode off.
2. Turn Super Bot Fight Mode on.
3. Add the WAF custom Skip rule below (include All Super Bot Fight Mode Rules in the Skip sites).

Configuration rule (Browser Integrity / Under Attack only)

If events show Browser Integrity Check or I'm Under Attack (not Bot Fight Mode), add a Configuration rule with the same filter expression as below and turn Browser Integrity Check off for matching rescue requests. This does not bypass Bot Fight Mode on Free.

WAF Skip rule (Pro+ with Super Bot Fight Mode, or general WAF blocks)

1. Security → Security rules → Create rule → Custom rules.

Click Edit expression, then copy and paste the following rule into the dedicated space:

(http.request.uri.path contains "/wp-admin/admin-ajax.php" and http.request.uri.query contains "action=patcherly_rescue_poll" and http.request.method eq "POST" and any(lower(http.request.headers.names[*])[*] eq "x-patcherly-signature"))

Then under Choose action, select Skip and enable:

• All managed rules
• All Super Bot Fight Mode Rules (only effective when Super Bot Fight Mode is on - not Bot Fight Mode on Free)
• Browser Integrity Check
• Security Level
• All rate limiting rules.

Place the rule First so it runs before blocking rules.

1. Configuration rule (optional) - only if step 1 is not enough and events are not tagged Bot Fight Mode:

Go to Rules → Overview → Create rule → Configuration Rule.

Use the same expression as above. Turn Browser Integrity Check off (dark grey, not green). Same for I'm Under Attack if enabled. Place the rule First.

1. Confirm Under Attack Mode is not blocking admin-ajax for unauthenticated POSTs.

If rescue dispatch fails but the main plugin is healthy

Rescue is the fast path (especially when the main plugin cannot load). The WordPress connector also picks up approved fixes on its normal poll when someone visits Home, Settings, or Errors in wp-admin - that traffic is outbound from your server to Patcherly and is not the same as the inbound rescue ping Cloudflare blocks.

If rescue is blocked, Retry Patch in the dashboard may keep showing a dispatch error - open Patcherly → Errors in your WordPress admin and click Retry Patch there; the connector fetches the fix from Patcherly (outbound) and applies it on your server without a rescue ping. The connector warms the local cache when you load the Errors page. Cached signed fix payloads live under wp-content/uploads/patcherly/cache/pending-fixes/. When edge protection blocks dispatch, Approve patch or Retry Patch in wp-admin can auto-fetch into that cache, apply on-server in the same request, and report the result to Patcherly (apply-result) so the error moves to Fixed on the dashboard. If the fix is already on disk and edge is still blocked, retry is idempotent and only syncs status. The connector syncs an edge rescue blocked flag from Patcherly on heartbeat and when the Errors page refreshes.

Local cache notes

• Cache files are not web-served (same protection as other Patcherly uploads storage).
• Every cached patch is re-verified with HMAC before apply; tampered or expired cache (7 days) is rejected.
• Cache is cleared after successful apply, reject patch, mark fixed, delete, or rollback.

After changing Cloudflare settings, wait a minute for propagation, then use Retry Patch on the error or Run rescue now on the site.

General fixes¶

• Reconnect - On Home, use Re-Connect Account when Connection lost is shown; otherwise Disconnect then Connect with Patcherly. This fixes most credential and trust issues.
• Clear the errors cache - temporarily set the cache to 0 in Advanced settings, then reload the Errors page.
• Check your WordPress error log - your hosting control panel usually has a "Logs" or "Error log" section.
• Status page - check the Patcherly status page if multiple sites are showing the same problem.

Deactivation vs uninstall¶

If WordPress could not reach Patcherly during deactivate/delete, the site may only show offline until you Disconnect on Patcherly → Home (or use Unplug on Sites).

Your own lines outside the Patcherly markers in wp-config.php are left alone. Deny rules under uploads/patcherly/ stay until Cleanup on Uninstall removes that folder. Agent status meanings: Agent status on Sites.

Uninstallation¶

Standard uninstall¶

1. Go to Plugins → Installed Plugins
2. Find "Patcherly"
3. Click Deactivate (optional but recommended first)
4. Click Delete

Cleanup option¶

If Cleanup on Uninstall is enabled in Settings → Advanced before you delete the plugin:

• All plugin options and cached credentials are removed
• The wp-content/uploads/patcherly/ folder is deleted (backups, locks, queue, emergency log)

If cleanup is off, your settings and on-server backup folder remain until you delete them manually.

Plugin updates¶

Install from the WordPress.org plugin directory when possible. WordPress then shows updates on Plugins (and Dashboard → Updates) like any other directory plugin. On Home (Overview), Patcherly shows a notice when WordPress already knows an update exists, with a button to View plugin updates.

If you installed from a ZIP (or need a one-off upgrade outside the directory):

1. Download the latest patcherly.zip.
2. In WordPress, go to Plugins → Add New → Upload Plugin.
3. Pick the new patcherly.zip and click Install Now.

WordPress replaces the previous version in place - your settings, your pairing, and your connection to Patcherly are preserved.

Connector Status Plugin version may also say update available based on Patcherly's CDN latest release. That is not the same as the Overview WordPress.org notice. The plugin does not fetch updates from the Patcherly dashboard - WordPress.org (or a manual ZIP) is the upgrade path.

Translations¶

The plugin's admin interface is ready for translation, and WordPress will automatically use the right language based on your Settings → General → Site Language choice (or your user profile's preferred language).

What ships in the plugin:

• A translation template you can use to create translations into your own language.
• An Italian translation, ready to use.

Adding a new language:

1. Open the translation template (patcherly.pot, inside the plugin's languages/ folder) in Poedit - a free, friendly translation editor.
2. Save it as patcherly-<your-locale>.po (e.g. patcherly-de_DE.po for German).
3. Translate the strings, then save: Poedit will write the matching .mo file next to it.
4. Drop both files into your site's wp-content/languages/plugins/ folder.

If you want to contribute your translation back so it ships with the plugin for all users, open a pull request on GitHub.

Support¶

For additional help:

• Check the troubleshooting guide.
• Review your WordPress error logs.
• For credential or sync issues, use Re-Connect Account on Home (or Disconnect, then Connect with Patcherly).
• Open Support from the bottom of the dashboard sidebar if you're stuck.

Next Steps¶

• Understanding errors
• Approving fixes
• Managing your sites