📘 User Manual - PRO Version 1.3.1

📑 Table of Contents

1. 1. 🚀 Introduction
      • 1.1. 🧠 The Philosophy of WP Optimal State PRO
      • 1.2. 👥 Who is This Manual For?
      • 1.3. ⚠️ A CRITICAL First Warning: ALWAYS BACK UP
   2. 🛠️ Getting Started
      • 2.1. 💻 System Requirements
      • 2.2. 📁 A Note on File & Directory Permissions
      • 2.3. 🚫 CRITICAL: Multisite Not Supported
      • 2.4. ⚡ Installation & Activation
      • 2.5. 🔄 Upgrading From Free Version
      • 2.6. 📊 Filesystem Footprint (What the Plugin Creates)
      • 2.7. 🔔 Keep the Plugin Updated
      • 2.8. 🛑 What Happens When You Deactivate
   3. 🎯 Dashboard Philosophy: The 3-Step Workflow
      • 🛡️ Step 1: The Safety Net (Backup)
      • 🔍 Step 2: The Diagnosis (Analyze)
      • ✨ Step 3: The Solution (Optimize)
   4. 💾 The Database Backup & Restore Manager (Section 1)
      • 4.1. 📥 Creating a Database Backup
      • 4.2. 🔧 Under the Hood: The Backup & Verification Process
      • 4.3. 📋 Managing Existing Backups (The Action Buttons)
      • 4.4. 🛡️ The Chunked, 4-Phase Safety Restore
      • 4.5. 📤 How to Restore Database from an Uploaded File
      • 4.6. 🔒 Security-First: The Upload Validation Process
   5. 🧹 The Database Optimization Suite (Sections 2-9)
      • 5.1. ❤️ Database Health Score
      • 5.2. 📈 Database Statistics (A Detailed Glossary)
      • 5.3. 🚀 One-Click Optimization (The "Easy Button")
      • 5.4. 🔍 Legacy Plugin Data Scanner
      • 5.5. 🎯 Targeted Optimizations
      • 5.6. 🔪 Detailed Database Cleanup
      • 5.7. ⚡ Advanced Database Optimization
      • 5.8. 🔍 Database Structure Analysis
      • 5.9. 🔢 MySQL Index Manager
      • 5.10. 🛡️ Referential Integrity Scanner
      • 5.11. ↳↰ Database Search & Replace
   6. ⏰ Automatic Backup & Cleanup (Section 10)
      • 6.1. ⚙️ Configuring the Scheduler
      • 6.2. 🔄 What the Scheduler Does
      • 6.3. 📧 Understanding Email Notifications (Success & Failure)
      • 6.4. ⏱️ A Note on WP-Cron
   7. ⚡ Performance Features Manager (Section 11)
      • 7.1. 🚫 CRITICAL: Do NOT Use With Other Caching Plugins
      • 7.2. 💨 Feature: Server-Side Page Caching
      • 7.3. 🌐 Feature: Browser Caching (.htaccess)
      • 7.3.1 🖥 Nginx Server Configuration (Security + Caching)
      • 7.4. 🏗️ Feature: WordPress Core Optimizations (A-Z)
      • 7.5. 📊 Feature: Performance Metrics (PageSpeed)
      • 7.6. 🤖 Feature: Bad Bot Blocker
   8. 🎯 Optimization Strategies: Putting It All Together
      • 8.1. 🚀 Strategy 1: The First-Time Setup
      • 8.2. 🆘 Strategy 2: The "My Site is Slow" Emergency Plan
      • 8.3. 📅 Strategy 3: The Monthly Maintenance Tune-Up
   9. 📥 Settings & Security (Section 12)
      • 9.1. 📥 Exporting Settings
      • 9.2. 📤 Importing Settings
      • 9.3. 🔒 User Access Control
      • 9.4. 🛡️ Login Page Protection
   10. 🔧 Troubleshooting & Advanced FAQ
       • 10.1. 🔄 "After updating/upgrading the plugin, some functions don't work."
       • 10.2. 🚧 "The restore process got stuck/maintenance mode didn't turn off. What should I do?"
       • 10.3. 🔄 "My restore failed, and the rollback also failed!"
       • 10.4. 🎨 "I enabled caching and my site looks broken (CSS is missing)."
       • 10.5. 🌐 "I enabled Browser Caching and my site is broken!"
       • 10.6. ⏳ "The 'Automatic Preload' gets stuck or times out."
       • 10.7. ❌ "The plugin shows a 'Critical Error: Cannot initialize WP_Filesystem'."
       • 10.8. ☁️ "I'm using a CDN (like Cloudflare). Will this work?"
       • 10.9. 🖥 "Does this plugin work on Nginx servers?"
       • 10.10. 🚦 "My PageSpeed Audit is showing an "API Error" or failing to load."
   11. 🏗️ Technical Architecture
       • 11.1. 🔒 Security-First Principles
       • 11.2. 🧩 Key PHP Classes & JavaScript Objects
       • 11.3. 🔐 Advanced Security Features
   12. 📝 Disclaimer
   13. 📝 Developer API (Hooks & Filters)
   14. 🆘 Technical Support

🚀 1. Introduction

🧠 1.1. The Philosophy of WP Optimal State PRO

WP Optimal State PRO is an advanced, all-in-one WordPress optimization and management suite. It was built on the philosophy that site management should be comprehensive, secure, and powerful. It provides a complete set of tools to clean, optimize, back up, and secure your WordPress database, combined with a robust performance module to make your site exceptionally fast.

This plugin is not just a simple "cleaner." It's a complete toolkit for database management and site performance, giving you both "one-click" simplicity and the granular, advanced control that professionals demand.

👥 1.2. Who is This Manual For?

This manual is for every user of WP Optimal State PRO.

• 👶 For Beginners: We will guide you through the safest, most effective features, like the One-Click Optimization and the automatic scheduler, allowing you to get 90% of the benefit with zero risk.
• 👨‍💻 For Advanced Users: We will explore the "why" behind each tool, helping you fine-tune your database, analyze its structure, and configure the performance cache for maximum speed.
• 👨‍💼 For Developers: We will explain the underlying architecture, the security measures in place, and the specific SQL commands and file modifications the plugin performs.

⚠️ 1.3. A CRITICAL First Warning: ALWAYS BACK UP

🚨 WARNING: THIS IS A POWERFUL TOOL

WP Optimal State PRO interacts directly and deeply with your website's database. Operations like cleanup, optimization, and restoration are powerful and, in most cases, irreversible.

While this plugin includes its own robust, best-in-class backup system, we cannot overstate the importance of caution.

💾 Before performing ANY cleanup or restore operation, you MUST create a fresh backup.

The plugin's built-in "Safety Backup" feature during restores provides a strong safety net, but a separate, downloadable backup is your ultimate insurance policy. Use this plugin responsibly. The author and this manual are not responsible for any data loss.

🛠️ 2. Getting Started

💻 2.1. System Requirements

To ensure full compatibility and smooth operation, your server should meet these minimum requirements:

• 🖥️ WordPress: Version 5.5 or higher.
• ⚙️ PHP: Version 7.4 or higher.
• 🗄️ Database: MySQL 5.6+ or MariaDB 10.1+.
• 🌐 Server: Apache, Nginx, or a compatible server. (Browser Caching feature requires Apache with mod_expires, mod_deflate, and mod_headers).

2.1.1. ⏱️ Rate Limiting & Timeout Settings

The plugin implements intelligent rate limiting and timeout configurations to prevent server overload:

• Action Rate Limits: Most user actions (like refreshing statistics) are rate-limited to prevent accidental server strain. The default is 6 seconds between repeated actions.
• Database Connection Timeouts:
  • Standard operations: 5 seconds
  • Cron/background tasks: 20 seconds
  • Read/Write operations: 2x the connection timeout
• Connection Lifecycle: Database connections automatically refresh after 10,000 queries or 5 minutes (300 seconds), whichever comes first, to maintain optimal performance.
• User Feedback: If you see 🕐 Please wait a few seconds..., you've triggered rate limiting. This is normal and protects your server.

📁 2.2. A Note on File & Directory Permissions

This plugin requires the ability to write files to your wp-content/uploads/ directory. This is a standard WordPress capability, but if your server has non-standard or overly restrictive permissions, you may encounter errors.

The plugin uses the WP_Filesystem API to safely read and write files. If you see an error like "Cannot initialize WP_Filesystem," it means your server is not configured to allow WordPress to manage its own files. You must contact your hosting provider to resolve this.

2.2.1. 🔧 WordPress Filesystem Method (FS_METHOD)

WordPress supports multiple methods for file operations. WP Optimal State PRO adapts its validation logic based on your server's configuration:

Available Filesystem Methods

How the Plugin Adapts

The plugin's path validation adjusts based on your FS_METHOD setting:

• FS_METHOD='direct': This block is only entered when FS_METHOD is defined as 'direct' and the allowed directory already exists on disk (verified with file_exists()).
  • Runs realpath() on the allowed directory to obtain its canonical (symlink-resolved, absolute) path. Returns false and rejects the request if resolution fails.
  • Runs realpath() on the target filepath only if that file already exists on disk. Files not yet created (e.g. a new backup about to be written) skip this second resolution but are still protected by the normalisation and boundary checks that run beforehand for all methods.
  • Validates that the resolved filepath starts with the resolved allowed directory, which blocks symlink-based directory escapes.
  • Provides the strongest protection against path traversal attacks.
  • Example: ../malicious/path resolves to its real location and fails the boundary check against the allowed directory.
• FS_METHOD='ssh2', 'ftpext', 'ftpsockets':
  • Skips realpath() validation (SSH/FTP connections can't resolve server-side paths)
  • Relies on normalized path checking only
  • Still validates: no ../, no null bytes, must start with allowed directory

Checking Your Current Method

To see which filesystem method WordPress is using:

1. Check wp-config.php for: define('FS_METHOD', 'value');
2. If not defined, WordPress auto-detects based on file permissions
3. View in "WP Site Health" → "Info" tab → "Filesystem Permissions" section

Recommended Configuration

For best performance and security with this plugin:

// In wp-config.php (if your hosting supports it)
define('FS_METHOD', 'direct');

To enable direct method safely:

• Ensure WordPress files are owned by the web server user (usually www-data, apache, or nginx)
• Set directory permissions to 755 for wp-content/uploads/
• Set file permissions to 644 for uploaded files

2.3. 🚫 CRITICAL: Multisite Not Supported

WP Optimal State PRO cannot be activated on WordPress Multisite (network) installations. If you attempt to activate it on a multisite network, you will see a clear error message and activation will be blocked.

Why Multisite Is Not Supported

This is a deliberate architectural decision, not a limitation to be worked around:

1. Shared Table Operations: Multisite installations share certain database tables (users, usermeta, sitemeta) across all sites. Cleanup operations on one subsite could delete data needed by other subsites.
2. Complex Prefix Handling: Multisite uses dynamic table prefixes (wp_, wp_2_, wp_3_, etc.). The plugin's table detection logic is designed for single-site prefixes and could misidentify tables.
3. Metadata Cascade Risk: Deleting orphaned metadata on a multisite network requires checking relationships across ALL subsites, not just one. This multiplies execution time by the number of sites and risks deadlocks.
4. Backup/Restore Scope: Should a backup include all subsites? Just one? The network tables? There's no clear answer, and partial restores could break the network.
5. Performance Feature Conflicts: Browser caching rules, page caching, and bad bot blocking need network-wide coordination on multisite. The single-site implementation would conflict with network-wide plugins.

The Safety Check

During activation, the plugin executes this check:

if (is_multisite()) {
    deactivate_plugins(plugin_basename(__FILE__));
    wp_die(
        'WP Optimal State cannot be activated on WordPress Multisite installations.',
        'Plugin Activation Blocked'
    );
}

Alternatives for Multisite Users

If you run a multisite network, consider these alternatives:

• Network-Wide Optimization Plugins: Look for plugins explicitly designed for multisite, such as WP-Optimize (has multisite mode)
• Manual Database Maintenance: Use phpMyAdmin or Adminer with custom SQL queries for controlled cleanup
• Professional Services: For large multisite networks, consider hiring a database administrator for scheduled maintenance

⚡ 2.4. Installation & Activation

1. Navigate to your WordPress Admin Dashboard.
2. Go to Plugins > Add New.
3. Click Upload Plugin.
4. Choose the WP_Optimal_State_PRO_X-X-X.zip file from your computer and click Install Now.
5. Once installed, click Activate Plugin.
6. Upon activation, the plugin will immediately check for and create its required directories and default settings files (Section 2.6).
7. Look for "Optimal State" in you admin menu.

🔄 2.5. Upgrading From FREE Version

The upgrade process is straightforward. Simply replace the free version with the PRO version.

👉 Follow these quick steps:

1. In the plugin interface, go to section 1 and download your database backups (they will download as compressed .sql.gz files).
2. Then, go to section 12 (Settings & Security) and click Export Settings to download your .json settings file.
3. Go to Plugins > Add Plugin, then click Upload Plugin. Choose the zip file WP_Optimal_State_PRO_X-X-X.zip containing the PRO version and click Install Now.
4. At this point, you will now be asked to either replace the current version with the uploaded one, or cancel and go back. Click Replace current with uploaded.
5. The update is complete! Visit the plugin admin panel to confirm that your backups and settings are intact.
6. If your settings have not been properly preserved, go to section 12 and import the .json file you downloaded in step 2.

💡 TROUBLESHOOTING: Functions Not Working After Upgrade

If after upgrading some functions don't work properly (e.g., save buttons not responding), this is usually caused by your browser still using cached versions of old JavaScript and CSS files.

Solution: Clear your browser cache

• Chrome/Edge: Press Ctrl+Shift+Delete (Windows) or Cmd+Shift+Delete (Mac), select "Cached images and files", then click "Clear data".
• Firefox: Press Ctrl+Shift+Delete (Windows) or Cmd+Shift+Delete (Mac), select "Cache", then click "Clear Now".
• Safari: Go to Safari menu → Settings → Privacy → "Manage Website Data" → "Remove All".
• Quick alternative: Try a hard refresh by pressing Ctrl+F5 (Windows) or Cmd+Shift+R (Mac) while on the plugin page.

📊 2.6. Filesystem Footprint (What the Plugin Creates)

On activation, the plugin creates the following directories and database tables to ensure persistent operation and data integrity.

📂 Filesystem (wp-content/uploads)

• .../uploads/optistate-settings/
  • settings.json: Stores all your saved settings (schedule, backup limits, performance toggles).
  • optimization-log.json: A log of all major operations (backups, restores, cleanups).
  • .htaccess: A security file that blocks all direct web access to this directory.
• .../uploads/optistate/db-backups/
  • Stores your compressed .sql.gz backups.
  • .htaccess: A security file that blocks web access.
• .../uploads/optistate/db-restore-temp/
  • A temporary, secure location for .sql and .sql.gz files you upload for restoration. Files are scanned and deleted after use.
  • .htaccess: A security file that blocks all access.
• .../uploads/optistate/page-cache/
  • Stores the static .html files for the Server-Side Page Caching feature.
  • .htaccess: A security file that blocks web access to anything except .html files.

🗄️ Database Tables

• wp_optistate_backup_metadata: Stores cryptographic checksums (SHA-256), file sizes, and timestamps for every backup. This allows the plugin to verify file integrity instantly without reading the entire file from disk.
• wp_optistate_processes: A specialized state-management table with three-tier caching:
  • Layer 1 - Runtime Cache: PHP memory (static array) - fastest, request-only persistence
  • Layer 2 - Object Cache: Memcached/Redis if available - microsecond access, survives across requests
  • Layer 3 - Database Table: Permanent storage - survives server restarts
  This multi-layer system means status checks during operations (polling every 2 seconds) cost virtually nothing in server resources. The table also automatically purges expired entries in batches of 1,000.
• wp_optistate_login_protect: Tracks failed login attempts by IP address for brute-force protection. Stores IP, timestamp, and attempt count with automatic cleanup of old entries.

⚠️ WARNING - NGINX SERVERS

If your server is running Nginx, your site's sensitive directories are currently unprotected. The .htaccess files this plugin relies on are ignored, leaving your files and settings exposed.

To secure your server, you must manually add the security rules to your Nginx configuration. Read Section 7.3.1 for immediate instructions.

2.6.1. 🗄️ The Process Store: Multi-Layer Caching System

WP Optimal State PRO uses a sophisticated three-tier caching system for process state management:

Cache Layers (Fastest to Slowest)

1. Runtime Cache (PHP Memory): Static array that persists for the current request only. Fastest possible access with zero overhead.
2. Object Cache (Memcached/Redis): If available, stores process data in your server's object cache (via wp_cache_set/get). Shared across PHP requests but cleared on server restart.
3. Database Table (wp_optistate_processes): Permanent storage for process data that survives server restarts. Created during activation with optimized indexes for fast lookups.

How the Fallback Works

When you access process data (like backup/restore status), the system:

1. First checks runtime cache (instant)
2. Falls back to object cache if available (microseconds)
3. Falls back to database query if needed (milliseconds)
4. Stores result in faster layers for subsequent requests

Automatic Cleanup

The process store automatically purges expired entries in batches of 1,000 to prevent table bloat. Expiration times are set per-operation:

• Backup/restore operations: 2 seconds (fast polling for UI updates)
• General process data: 5 seconds
• Permanent data: 0 (never expires)

🔔 2.7. Keep the Plugin Updated

Your update process depends on whether you are using the FREE or PRO version. Please read the correct section for your plugin.

✔ UPDATING THE PREVIEW VERSION

If you installed the free preview/demo version of the plugin from the official WordPress plugin repository, you can update it directly from your WordPress dashboard.

• Go to Plugins → Installed Plugins.
• Find "Optimal State" and click the "update now" link.

⭐ UPDATING THE PRO OR FREE VERSION

Updating the PRO or FREE version (which you received as a .zip file) takes just a couple of minutes. You have two equally valid options.

💡 Option 1: Via the Dashboard

1. In the plugin interface, go to section 1 and download your database backups (they will download as compressed .sql.gz files).
2. Then, go to section 12 (Settings & Security) and click Export Settings to download your .json settings file.
3. Go to Plugins > Add Plugin, then click Upload Plugin. Choose the .zip file containing the latest plugin release and click Install Now.
4. At this point, you will now be asked to either replace the current version with the uploaded one, or cancel and go back. Click Replace current with uploaded.
5. The update is complete! Visit the plugin admin panel to confirm that your backups and settings are intact.
6. If your settings have not been properly preserved, go to section 12 and import the .json file you downloaded in step 2.

👨‍💻 Option 2: Via FTP Client

1. Unzip the new plugin .zip file on your computer to get a folder named optistate.
2. Open your FTP client or hosting file explorer and navigate to wp-content/plugins/.
3. Upload the optistate folder from your computer, choosing to replace or overwrite all existing files in the /wp-content/plugins/optistate/ directory.
4. Once complete, go to Plugins > Installed Plugins, find WP Optimal State and verify that the new version number is displayed.
5. The update is complete! Visit the plugin admin panel to confirm that your backups and settings are intact.

📥 How to Get PRO Updates

• You will receive an email notification when a new version is released.
• Download the update from your account on the purchase site (Payhip.com).
• If you did not register at the time of purchase or no longer have access to your account, contact 🆘 Technical Support with your license key and website URL. We will send the update package to you via email.

💡 TROUBLESHOOTING: Functions Not Working After Update

If after updating some functions don't work properly (e.g., save buttons not responding), this is usually caused by your browser still using cached versions of old JavaScript and CSS files.

Solution: Clear your browser cache

• Chrome/Edge: Press Ctrl+Shift+Delete (Windows) or Cmd+Shift+Delete (Mac), select "Cached images and files", then click "Clear data".
• Firefox: Press Ctrl+Shift+Delete (Windows) or Cmd+Shift+Delete (Mac), select "Cache", then click "Clear Now".
• Safari: Go to Safari menu → Settings → Privacy → "Manage Website Data" → "Remove All".
• Quick alternative: Try a hard refresh by pressing Ctrl+F5 (Windows) or Cmd+Shift+R (Mac) while on the plugin page.

2.8. 🛑 What Happens When You Deactivate

Understanding the deactivation cleanup process helps you make informed decisions about plugin management. The steps below reflect the actual execution order in the code.

Automatic Cleanup (Execution Order)

When you deactivate WP Optimal State PRO, the following actions run in this sequence:

1. Bot Blocking Rules Removed: Bad bot blocking rules are removed from .htaccess.
2. Deactivation Logged: A 🔌 Plugin Deactivated by {username} entry is written to the activity log before any data is deleted, ensuring the event is always recorded.
3. Scheduled Hooks Cleared: All four plugin cron hooks are unregistered: optistate_scheduled_cleanup, optistate_daily_cleanup, optistate_background_preload_batch, and optistate_run_rollback_cron.
4. Browser Caching Rules Removed: Browser caching directives are removed from .htaccess.
5. Maintenance Mode Cleared: The optistate_maintenance_mode_active option is deleted to prevent the site being left in maintenance mode.
6. Database Tables Dropped:
   • wp_optistate_processes — the process-store table (dropped via its class method).
   • wp_optistate_login_protect — the login-protection table (name validated against alphanumeric pattern before the drop is executed).
   • Any stray tables matching wp_optistate_old_* or wp_optistate_temp_* — see the Stray Table Cleanup Logic subsection below.
7. Transients Cleared: All transient keys matching _transient_optistate_* and their corresponding timeout keys _transient_timeout_optistate_* are deleted in a single query.
8. Options Cleaned: All remaining options whose names start with optistate_ are deleted in batches of 100 to avoid memory issues on large databases.
9. User Metadata Removed: The optistate_action_timestamps meta key is deleted from all user records.
10. Filesystem Cleanup: Two directories are deleted entirely:
    • Page cache: wp-content/uploads/optistate/page-cache/
    • Restore temp: wp-content/uploads/optistate/db-restore-temp/

What Is Preserved (Intentionally NOT Deleted)

Two directories survive deactivation on purpose, so that reactivating the plugin restores your previous state without data loss:

• Settings & Log directory: wp-content/uploads/optistate-settings/ — contains settings.json (your configuration) and optimization-log.json (your complete activity/audit history).
• Backup directory: wp-content/uploads/optistate/db-backups/ — all .sql.gz backup files are kept here. These are never touched by deactivation to prevent accidental data loss.

Manual Cleanup (Complete Removal)

To remove all traces of the plugin after deactivation:

1. Delete via FTP: wp-content/uploads/optistate-settings/ (settings and logs) and wp-content/uploads/optistate/db-backups/ (all backup files).
2. Delete plugin folder: wp-content/plugins/optistate/

Stray Table Cleanup Logic

The deactivation process includes a dedicated routine to clean up tables left behind by interrupted or failed operations:

1. Queries information_schema.TABLES for tables in the current database whose names match optistate_old_% or optistate_temp_%.
2. Each candidate is validated through three checks: the name must be alphanumeric-plus-underscore only (/^[a-zA-Z0-9_]+$/), no longer than 64 characters, and must start with the expected WordPress prefix (e.g. wp_optistate_old_ or wp_optistate_temp_). Tables that fail any check are skipped.
3. Foreign key checks are disabled (SET FOREIGN_KEY_CHECKS = 0) for the duration of the drops to avoid constraint errors on interdependent tables.
4. All validated tables are dropped.
5. Foreign key checks are re-enabled (SET FOREIGN_KEY_CHECKS = 1).

Reactivation

Because the settings and backup directories are preserved, reactivation is designed to be seamless:

• Settings Restored: Configuration is read from the preserved settings.json file.
• Performance Features Reapplied: Any previously enabled features (browser caching, bad bot blocker) are automatically re-added to .htaccess.
• Tables Recreated: The wp_optistate_processes and wp_optistate_login_protect tables are recreated with their indexes.
• Log Entry: An activation entry is written listing which features were restored.

🎯 3. Dashboard Philosophy: The 3-Step Workflow

The plugin dashboard is organized to guide you through a logical and safe workflow.

🛡️ Step 1: The Safety Net (Backup)

Section: 1. Create a Database Backup

Before you diagnose or fix anything, you must have an exit strategy. This section is your safety net. You can create a new, verifiable backup in seconds.

🔍 Step 2: The Diagnosis (Analyze)

Sections: 3. Database Health Score, 4. Database Statistics, 6. Database Structure Analysis

You can't fix what you don't understand. These sections are your diagnostic tools.

• ❤️ Health Score: Gives you a high-level "grade" of your site's condition.
• 📊 Statistics: Shows you the raw numbers—how many post revisions you have, how much database overhead, etc.
• 🔍 Structure Analysis: Gives you a "map" of your database, showing you what's core, what's from plugins, and how big each table is.

✨ Step 3: The Solution (Optimize)

Sections: 2. One-Click Optimization, 8. Detailed Cleanup, 9. Advanced Optimization, 10. Automation, 11. Performance

Once you have a backup and have diagnosed the problems, you can apply the solution.

• 🚀 For a Quick Fix: Use Section 2 (One-Click Optimization).
• 🔪 For Granular Control: Use Section 8 (Detailed Cleanup).
• ⚡ For Deep Issues: Use Section 9 (Advanced Optimization).
• ⏰ For Future-Proofing: Use Section 10 (Automation).
• 💨 For Site Speed: Use Section 11 (Performance Manager).

💾 4. The Database Backup & Restore Manager (Section 1)

This is the plugin's most critical feature. It allows you to create, manage, download, and restore your database with a focus on security and integrity.

📥 4.1. Creating a Database Backup

The backup process relies on an asynchronous chunked engine that runs entirely in the background, making it resilient on any hosting environment — including shared hosting with low PHP time limits.

1. 📊 Maximum Backups to Keep: This setting (1–10) enforces a rolling limit. After a backup completes, the engine sorts all existing backups by last-modified timestamp (oldest first) and deletes the excess. Only .sql and .sql.gz files are counted — internal SAFETY-RESTORE-* backups created during the restore process are explicitly excluded from this limit.
   • 💡 Recommendation: Set this to 3. This keeps recent restore points available while minimizing server storage usage.
2. 🔄 Create Backup Now Button: Clicking this initializes a secure multi-step background process:
   • 🔒 Collision-Safe Filename: Each backup filename is suffixed with 14 random hex bytes (random_bytes(7)), making filename collisions statistically impossible. If a file at the target path already exists, the process throws an exception rather than overwriting.
   • 🔑 PID Lock File: A .lock file is written with the current PHP process ID before any data is touched. If the lock cannot be created, the backup is aborted immediately. This prevents two concurrent backups from writing to the same file.
   • 📋 Table Discovery: The engine runs SHOW FULL TABLES to enumerate every table, including its type (BASE TABLE vs. VIEW). Internal plugin tables (wp_optistate_processes, wp_optistate_backup_metadata, wp_optistate_login_protect, and any stray optistate_old_* tables) are silently excluded from the backup to avoid self-referential loops.
   • ⚙️ Worker Coordination: Before processing each chunk, the engine atomically registers itself as the active worker in the process store. If another worker process is already active and has sent a heartbeat within the last 45 seconds, the new worker skips its chunk and exits cleanly, preventing parallel writes to the same file.
   • 📦 Streamed gzip Writing: Data is written chunk by chunk directly into a .sql.gz file opened in append mode (ab6f), meaning no full SQL file is ever held in memory. If PHP crashes mid-chunk, the partial gzip file is cleaned up on the next request.
   • 🔒 Metadata Storage: On successful completion, the backup's filename, file size, creation timestamp, and database name are written to the protected wp_optistate_backup_metadata database table. This is intentionally a database table, not a sidecar file — it cannot be tampered with by uploading a file to the backup directory.
   • ✅ SHA-256 Integrity Seal: A SHA-256 checksum of the completed file is generated and stored separately. Every subsequent action on that backup (download, restore) re-verifies this checksum before proceeding. A failed checksum aborts the action entirely.

🔧 4.2. Under the Hood: The Backup & Verification Process

The backup mechanism is server-timeout proof using an asynchronous, chunked process. The plugin executes a series of timed AJAX requests, each running for a fixed window before saving state and yielding — ensuring reliability on any hosting environment including aggressively time-limited shared hosts.

1. 🔓 Concurrency Lock: When a chunk starts, the engine atomically claims the active_worker slot in the process store with a unique worker ID and a worker_ping timestamp. If another process already holds the slot with a fresh ping (<45 seconds old), the new chunk exits immediately without touching the file. If the existing worker has gone stale, the slot is stolen and processing continues.
2. 🧠 Adaptive Resource Tiering: Before the first chunk, the engine detects your server's available resources (CPU cores via shell_exec, PHP memory limit) and assigns a performance tier that controls how long each chunk runs and how quickly subsequent chunks are scheduled:
   • High Tier: High RAM/CPU — longer chunk windows with minimal delays between requests.
   • Medium Tier: Standard VPS — balanced chunk windows.
   • Low Tier: Shared hosting — short chunk windows with longer cooldowns to avoid triggering resource abuse limits.
3. 🏗️ Structure Dump: For each table the engine first emits DROP TABLE IF EXISTS followed by the full SHOW CREATE TABLE output (or SHOW CREATE VIEW for views). The AUTO_INCREMENT value is read from SHOW TABLE STATUS and explicitly written into the CREATE statement, ensuring auto-increment counters are preserved exactly. Generated columns are detected and excluded from the column list to avoid restore errors.
4. 📐 Pagination Method Selection: After dumping the structure, the engine examines each table's primary key to choose the safest pagination method:
   • Keyset (primary): Single numeric PK → WHERE pk > last_seen LIMIT N. Zero drift, no performance degradation at scale.
   • Unique index fallback: If no PK exists, the engine scans SHOW INDEX … WHERE Non_unique = 0 and uses the first numeric unique column for keyset pagination.
   • OFFSET fallback: Composite PKs, non-numeric PKs, or no PK at all → standard LIMIT N OFFSET M, with batch size reduced to 65% of normal to compensate for offset overhead.
5. 📦 Adaptive Batch Sizing & Streaming: For each table, AVG_ROW_LENGTH is fetched from information_schema (with SHOW TABLE STATUS as fallback) and cached in memory (up to 160 entries) and as a transient (10-minute TTL). The batch limit is calculated as floor(2MB / avg_row_length), clamped between 10 and 2,000 rows. Rows are buffered in memory up to 2MB, then flushed as a single INSERT INTO … VALUES (…),(…) block directly into the gzip stream. Oversized single rows that exceed the 2MB buffer are flushed individually. Memory usage is monitored every 1,000 rows — if usage exceeds 80% of the PHP memory limit, gc_collect_cycles() is called and the buffer is flushed immediately.
6. 📄 phpMyAdmin-Compatible Header & Footer: The output SQL begins with a full phpMyAdmin-style header (version, host, generation time, server version, database name, charset/collation) and wraps all data in START TRANSACTION … COMMIT. This ensures the file is importable by phpMyAdmin, MySQL CLI, or any standard SQL tool without modification.
7. ✅ SHA-256 Checksum: After all tables are written and the file is finalized, a SHA-256 checksum of the completed gzip file is computed and stored in the wp_optistate_backup_metadata table alongside the filename, file size, database name, and creation timestamp.
8. 🗜️ Compression: Data is written into the gzip stream in real time using PHP's gzopen/gzwrite (level 6 by default). On servers where pigz (parallel gzip) is available and shell_exec is enabled, the decompression step during restore uses pigz for multi-core performance — backup creation always uses the streaming PHP path for safety.

Database Connection Refresh During Long Operations

For large databases (500MB+), backup/restore operations may exceed the standard connection lifecycle limits. The plugin automatically handles this:

When Does Connection Refresh Occur?

• After 10,000 queries: Each table copy/restore can involve thousands of INSERT statements
• After 5 minutes (300 seconds): Prevents MySQL wait_timeout disconnections
• When connection is dead: Detected via SELECT 1 heartbeat queries

What Happens During Refresh?

1. Old connection is gracefully closed (commits any pending autocommit changes)
2. New connection is established with fresh timeouts
3. Session settings are reapplied:
   • SET SESSION time_zone
   • SET SESSION sql_mode='NO_ENGINE_SUBSTITUTION'
   • SET SESSION wait_timeout=300
   • Character set/collation
4. Operation continues seamlessly from next query

Foreign Key Constraint Handling

Database tables with foreign key relationships require special handling during backup and restore operations.

What Are Foreign Keys? Constraints that enforce relationships between tables (e.g., wp_postmeta.post_id must reference existing wp_posts.ID).

The Problem: During restore, you can't drop parent tables if child tables have foreign keys pointing to them, causing "Cannot add or update child row" errors.

The Solution: The plugin temporarily disables foreign key checks during operations:

SET FOREIGN_KEY_CHECKS = 0;
-- ... perform operations ...
SET FOREIGN_KEY_CHECKS = 1;

Safety Mechanisms:

• Transaction Wrapper: All operations happen inside transactions, so errors trigger automatic rollback
• Emergency Cleanup: If PHP crashes, the emergency cleanup function restores FOREIGN_KEY_CHECKS = 1 (see Section 4.6.1)
• Session-Level Only: Uses SET SESSION commands, affecting only this connection, not other users

SET FOREIGN_KEY_CHECKS = 1;

Common Plugins Using Foreign Keys: WooCommerce (orders), Advanced Custom Fields, BuddyPress, LearnDash

📋 4.3. Managing Existing Backups (The Action Buttons)

This table lists all available backups.

• ✅ File Integrity: This is the most important column.
  • ✅ File integrity: The plugin has re-computed the SHA-256 checksum of the backup file on-the-fly and confirmed it exactly matches the fingerprint stored in the wp_optistate_backup_metadata table at the time of creation. The backup is 100% valid and safe to restore.
  • ⚠️ File integrity: The live checksum does not match the stored fingerprint. The backup file has been modified, truncated, or corrupted since it was created. 🚫 DO NOT RESTORE THIS FILE. Delete it immediately and create a new backup.
• 📥 Download: This securely prepares and downloads a compressed .sql.gz version of the file to your computer.
  • 🔒 Security: Before preparation, the plugin re-verifies the original file's SHA-256 checksum. If the check fails, the download is aborted, protecting you from downloading a corrupted file.
• 🗑️ Delete: This permanently deletes the backup file and all associated integrity data from your server. A confirmation modal will appear.
• 🔄 Restore: This is the most powerful action. It will completely replace your current database with the data from this backup file. Please read the next section carefully.

🛡️ 4.4. The Chunked, 4-Phase Safety Restore

Restoring a database backup is the most critical operation the plugin performs. To guarantee zero data loss against server timeouts, crashes, or corrupted files, the restore is broken into four distinct phases — each resumable, each with its own safety gate.

🔐 Phase 1: Pre-Flight Validation & Safety Backup

1. 🔒 Global MySQL Advisory Lock: First of all, the engine acquires a MySQL-level advisory lock (GET_LOCK('optistate_master_restore_global', 5)). This prevents two concurrent restore operations from running simultaneously — even across different browser tabs or server requests. If the lock cannot be acquired within 5 seconds, the restore is refused with a clear error message. A PHP shutdown handler is registered to release this lock automatically if the process crashes.
2. 📄 SQL File Validation: The restore target file is opened and its first 8KB is scanned for a -- Database: dbname header comment. If the database name in the file does not match your current WordPress database name (compared with hash_equals() to prevent timing attacks), the restore is blocked immediately. This prevents accidentally restoring a backup from a different site.
3. 💾 Automatic Safety Backup: Before the target database is touched, the plugin creates a complete, real-time SAFETY-RESTORE-{date}.sql.gz backup of your current live database using the same chunked engine described in section 4.2. This backup is your guaranteed rollback point — if anything goes wrong during the restore, it will be used to recover your original data automatically.
4. ✅ Safety Backup Integrity Validation: After the safety backup completes, the engine verifies it is readable and its gzip stream is valid before proceeding. If the safety backup is missing, smaller than 1KB, or its gzip stream is unreadable, the restore is aborted. A restore that begins without a verified safety backup is never allowed to proceed.
5. 🚧 Maintenance Mode: Only after the safety backup is verified does the site enter a brief maintenance mode (optistate_maintenance_mode_active option set to true). This blocks new front-end database writes while tables are being swapped. Maintenance mode is always deactivated — even if the restore fails — via the same shutdown handler that releases the advisory lock.

⚙️ Phase 2: Staged Import to Temporary Tables

1. 🗄️ Shadow Table Naming: Every CREATE TABLE statement in the backup is rewritten on-the-fly by the SQL parser to target a shadow table instead of the live table. For example, wp_posts becomes optistate_temp_wp_posts_{hash}. Your live tables are never touched during the import phase.
2. 📦 Chunked Streaming Import: The backup file is parsed and executed asynchronously. Each AJAX chunk runs for approximately 18 seconds, processes as many SQL statements as possible, commits its transaction, saves the file pointer position, and initiates the next request. If the server times out, the next request resumes from the exact byte offset where the previous one stopped — nothing is lost or re-executed.
3. 🏗️ Deferred Index Building: When a CREATE TABLE statement is parsed, the engine strips secondary indexes from the CREATE statement and stores the corresponding ALTER TABLE … ADD INDEX queries separately. The table is created with only its primary key, all data is inserted at full speed (no index maintenance overhead), and the indexes are built in a single pass after the data is loaded. This mirrors what professional database import tools like mysqldump --disable-keys achieve.
4. 🔒 Charset & Collation Safety: Before the first statement executes, the engine reads the current database charset and compares it against the backup's charset (detected from the backup's SET NAMES header). A utf8mb4 backup into a utf8 database is blocked with a clear error: this would cause data corruption (emoji and 4-byte characters would be silently truncated). A utf8 backup into a utf8mb4 database is allowed and handled correctly.
5. 🛡️ Statement Security Filter: Every SQL statement passes through a whitelist filter before execution. Statements that are blocked regardless of file source include: SET GLOBAL, SET USER, GTID_NEXT/GTID_PURGED, CREATE PROCEDURE/FUNCTION/TRIGGER/EVENT, CREATE DATABASE, USE dbname, and LOCK TABLES/UNLOCK TABLES. This ensures a maliciously crafted backup file cannot escalate privileges or alter server-level settings.
6. 🔁 Connection Resilience: Every 100 queries the engine sends a SELECT 1 heartbeat. If the connection has gone stale (MySQL wait_timeout disconnection), the engine automatically reconnects, re-applies all session settings, and resumes without loss. If the statement that failed was an INSERT, the transaction is reopened and the statement is retried.

🔍 Phase 3: Staged Table Verification

• ✨ Core Table Existence Check: The engine confirms that temporary tables for *_options, *_posts, and *_users were all created successfully (matched by suffix to support any non-standard table prefix).
• 📊 Data Integrity Checks: The temporary *_options table is checked for: a non-empty row count, the presence of the siteurl option, all four required columns (option_id, option_name, option_value, autoload), and an intact PRIMARY KEY. A backup that passes structure validation but has an empty or structurally invalid options table is rejected before the atomic swap.

⚡ Phase 4: Atomic Swap & Instant Rollback Guarantee

1. 🔄 Atomic RENAME TABLE: The swap is executed as a single RENAME TABLE statement that renames all live tables to optistate_old_* and all temporary tables to the live names simultaneously. MySQL guarantees this operation is atomic — either all renames succeed, or none do. There is no moment when your live tables are missing or partially replaced. Table names longer than 64 characters are automatically handled with a hash-based truncation strategy.
2. 🔴 Instant Rollback Map: Immediately before executing the RENAME, the engine writes a map of live_table → optistate_old_table pairs to the process store. If anything fails after the swap — including a PHP fatal error, memory exhaustion, or server crash — a subsequent request can call perform_rollback() which executes a reverse atomic RENAME to restore the original tables. This rollback itself is wrapped in a transaction, so it either succeeds completely or leaves the optistate_old_* tables intact for manual recovery.
3. 🧹 Post-Swap Cleanup: On successful swap, deferred indexes are applied to the now-live tables, the optistate_old_* tables are dropped, the safety backup file is deleted (it's no longer needed), and maintenance mode is deactivated. wp_cache_flush() is called to ensure no stale object cache entries survive the restored data.

This architecture means that at no point during a restore operation is your site left in an undefined state. Either you have your original data, the restored data, or (in the rare event of a catastrophic failure) an automatic revert to the safety backup created in Phase 1.

📤 4.5. How to Restore Database from an Uploaded File

This feature is designed to upload a .sql or .sql.gz file. You can upload a compressed backup downloaded from this plugin or an export from phpMyAdmin.

🚨 WARNING

Only upload .sql or .sql.gz files generated by WP Optimal State or phpMyAdmin. Uploading a random file or a backup from another plugin may damage your database structure. 🧩 phpMyAdmin Compatibility: To ensure 100% compatibility with WP Optimal State, uncheck the Enclose export in a transaction option before performing exports.

🔄 Process:

1. 📁 Choose SQL File: Click the button to select a .sql or .sql.gz file from your computer.
2. 🔍 Validation & Upload: The file will be uploaded, and a progress bar will be displayed. During this process, a multi-step security validation occurs (see 4.6).
3. 🔄 Restore from File: Once the upload is complete and validated, the "Restore from File" button will appear.
4. ✅ Confirmation: Clicking this button will trigger the same confirmation modal and the exact same 4-Phase Safety Restore process described in section 4.4.
5. ⏳ Execution: The time required to complete the restore will vary significantly depending on both the size of the database and the available server resources (from a few seconds to 30-60 minutes).

🔒 4.6. Security-First: The Upload Validation Process

When you upload a .sql or .sql.gz file, it undergoes a rigorous multi-step security scan before it is ever used. Every check that fails results in the uploaded file being deleted from the server immediately.

1. 📄 Extension & MIME Check: The file extension must be .sql or .sql.gz. The MIME type (e.g., text/plain, application/sql, application/gzip, application/x-gzip) is also verified independently to prevent file-type spoofing via renamed extensions.
2. 📏 File Size Limit: Enforces a 5GB maximum (Free tier: 50MB). Files exceeding this limit are rejected before decompression.
3. 🛡️ Content Security Scan: If the file is compressed, it is first decompressed into a secure temporary path. The plugin reads the SQL content and scans for:
   • PHP code injection: <?php, <?=
   • Server-side code execution functions: eval(, system(, exec(, base64_decode
   Any match causes immediate rejection and deletion of the upload.
4. 🗄️ Database Name Verification: During the restore phase, the SQL file's first 8KB is read and searched for a -- Database: dbname comment (the standard phpMyAdmin export header). If found and the name does not match your current WordPress database name, the restore is blocked. The comparison uses hash_equals() (constant-time comparison) to prevent timing-based enumeration of your database name. A random microsleep of 3–18ms is also inserted at this check point to further frustrate automated probing.
5. 📋 WordPress Table Structure Validation: Beyond the database name check, the validator scans up to 5,000 SQL statements looking for CREATE TABLE or INSERT INTO statements targeting tables with the core WordPress suffixes (_options, _posts, _users). A file that passes the MIME and size checks but contains no recognizable WordPress tables is rejected as "not a valid SQL database backup."

If any of these checks fail, the file is deleted from the server and the restore is aborted with a specific error message identifying which check failed.

🚨 4.6.1. Emergency Recovery: What Happens When Things Go Wrong

WP Optimal State PRO has a sophisticated emergency recovery system that activates during PHP shutdown to prevent database corruption.

What Triggers Emergency Cleanup?

• PHP fatal errors during database operations
• Maximum execution time exceeded (timeout)
• Memory limit exceeded
• Server crashes or forced process termination

Emergency Recovery Steps (Automatic)

When PHP shuts down unexpectedly, the emergency_cleanup() function executes:

1. Transaction Detection: Checks if any database transaction is still active
2. Connection Health Check: Uses $connection->ping() to verify if MySQL connection is still alive
3. Rollback Active Transactions: If connection is alive, rolls back any uncommitted changes
4. Restore Safety Settings: Ensures FOREIGN_KEY_CHECKS and AUTOCOMMIT are set back to defaults
5. Connection Reconnection: If connection was lost, attempts to reconnect and restore settings
6. Graceful Closure: Properly closes database connection to free server resources

What This Prevents

Checking Emergency Cleanup Logs

If emergency cleanup runs, you'll find entries in your PHP error log (error_log file):

[03-Feb-2026 14:32:18 UTC] OPTISTATE DB EMERGENCY ERROR: Connection lost during transaction
[03-Feb-2026 14:32:18 UTC] OPTISTATE: Failed to reconnect during emergency cleanup: Too many connections

Preventing Emergency Situations

To minimize the chance of emergency cleanup activation:

• Increase max_execution_time to at least 300 seconds for large databases
• Ensure memory_limit is adequate (512MB minimum, 1GB recommended for databases over 500MB)
• Don't perform major database operations during high-traffic periods
• Monitor available disk space (operations may need 2-3x your database size)

🧹 5. The Database Optimization Suite (Sections 2-9)

This is the core optimization suite. These sections work together to help you diagnose and clean your database.

❤️ 5.1. Database Health Score

The Database Health Score is your central diagnostic hub—a comprehensive analysis that gives you a single number (0-100) representing your database's overall condition. This score is calculated by examining multiple aspects of your database and applying weighted penalties for issues that impact performance, cleanliness, and structural efficiency.

🎯 How the Score is Calculated

The plugin analyzes your database across three key categories, each with its own sub-score. These are then combined into a single Overall Score using a weighted formula:

📊 Understanding Your Overall Score

• 🎉 90-100 (Excellent): Your database is in optimal condition. No critical issues detected. Continue with regular maintenance.
• 👍 75-89 (Good): Minor optimization opportunities exist, but nothing urgent. Consider addressing recommendations when convenient.
• 😐 60-74 (Fair): Noticeable database bloat or fragmentation. Performance improvements are possible with cleanup.
• 👎 40-59 (Poor): Significant issues detected. Your database is bloated and likely affecting site speed. Optimization recommended.
• 🚨 0-39 (Critical): Severe database health problems. Immediate optimization required—performance is being significantly impacted.

📈 The Three Category Scores Explained

💡 Actionable Recommendations

The most valuable part of the Health Score interface is the recommendations section. Based on the specific issues detected, the plugin provides prioritized, actionable suggestions with direct links to the tools you need.

Recommendations are prioritized by severity:

• 🔴 High Priority (Red): Critical issues significantly impacting performance. Address immediately.
• 🟠 Medium Priority (Orange): Notable issues that should be addressed soon to prevent degradation.
• 🔵 Low Priority (Blue): Minor optimizations that can improve efficiency when convenient.
• 🟢 Success (Green): No issues detected. Database is healthy and optimized.

💡 PRO TIP: Regular Monitoring

Your Health Score is cached for 12 hours to avoid unnecessary database queries. Click "⟲ Refresh" to force a new calculation after making changes.

Check your score weekly or after major content changes (like importing products, publishing many posts, or installing/uninstalling plugins) to catch issues early.

📈 5.2. Database Statistics (A Detailed Glossary)

This is the raw data used to calculate your Health Score. It shows you exactly what was found in your database.

• 📝 Post Revisions: Old, saved versions of your posts and pages.
• 📄 Auto Drafts: Unsaved drafts automatically created by WordPress.
• 🗑️ Trashed Posts: Posts and pages in your trash bin.
• 🚮 Spam Comments: Comments marked as spam.
• 🗑️ Trashed Comments: Comments in your trash bin.
• 🧩 Orphaned Post Meta: Data from plugins/themes that was left behind after a post was deleted. This is "junk" data with no post to attach to.
• 🧩 Orphaned Comment Meta: Data left behind after a comment was deleted.
• 🧩 Orphaned Term Relationships: Data linking non-existent posts to categories or tags.
• ⏰ Expired Transients: Temporary cached data (like a weather widget's data) that has passed its expiration date and can be deleted.
• 💾 All Transients: All temporary cached data, including expired and active.
• 📋 Duplicate Post Meta: Redundant, identical metadata entries for posts.
• 📋 Duplicate Comment Meta: Redundant, identical metadata entries for comments.
• 🧩 Orphaned User Meta: Data left behind from deleted users.
• ⏳ Unapproved Comments: Comments awaiting moderation.
• 🔗 Pingbacks: "Pingback" notifications in your comments.
• 🔗 Trackbacks: "Trackback" notifications in your comments.
• 💾 Database Overhead: "Empty" space in your tables, similar to file fragmentation. This space can be reclaimed.
• 📚 Total Indexes Size: The size of the database "phone book" used for fast lookups.
• 📊 Number of Tables: The total count of tables in your database.
• ⚡ Autoloaded Options: The number of settings set to load on every single page.
• 💽 Autoload Data Size: The total size of all autoloaded settings. This is a critical performance metric. A high number (e.g., > 1MB) can significantly slow down your site.
• 🗓️ Action Logs: Background task records (completed, failed, or canceled) created by plugins like WooCommerce to handle scheduled events.
• 🎥 Embed Cache: Cached data for external content (like YouTube videos or Tweets) embedded in your posts. Cleaning this forces WordPress to refresh the content.
• 🛒 WooCommerce Sessions/Logs: Temporary data identifying customers and their cart contents, plus expired logs that can accumulate rapidly in active stores.
• 🏷️ Empty Taxonomies: Categories, tags, or custom terms that currently have zero posts assigned to them.

🚀 5.3. One-Click Optimization (The "Easy Button")

The "One-Click Optimization" is the heart of the plugin's ease-of-use philosophy. It is designed to be a "safe-by-default" maintenance routine that you can run without fear of breaking your site or losing important data.

🛡️ What is "Safe Cleaning"?

Unlike aggressive cleaners that might empty your trash bin or delete comments you haven't reviewed yet, this process selectively targets only useless data that has no effect on your live content.

🔄 The 2-Stage Process

When you click "🚀 Optimize Now", the plugin executes two distinct operations in sequence:

1. Stage 1: Garbage Collection
   It runs the SQL delete commands for all the "Safe Junk" items listed above.
2. Stage 2: Table Defragmentation
   Immediately after cleaning, it runs OPTIMIZE TABLE on your database. This reclaims the empty space ("overhead") left behind by the deleted data, physically shrinking your database size and speeding up read/write operations.

💡 Result: After completion, you will see a summary report of exactly how many items were removed and how much disk space was reclaimed.

This is the recommended action for most users after creating a backup.

🔍 5.4. Legacy Plugin Data Scanner

The Legacy Plugin Data Scanner helps you find "ghost data" — database entries left behind by plugins and themes you've already removed. Many plugins don't clean up after themselves when uninstalled, leaving behind options, metadata, custom tables, and files that waste space and can slow down your site.

What It Actually Scans:

• wp_options table: Scans the top 250 largest autoloaded options for known plugin patterns. Options over 50KB are automatically flagged as high risk.
• wp_postmeta table: Scans the top 250 most common meta keys (by count) for inactive plugin signatures
• Custom tables: Scans all database tables for those created by uninstalled plugins (prefixed with plugin identifiers)
• Filesystem directories: Scans wp-content, uploads, plugins, themes, and mu-plugins directories for leftover plugin/theme folders

How Detection Works:

The scanner uses intelligent pattern matching:

1. First, it builds a "protected list" from your currently active plugins, themes, and must-use plugins
2. It also identifies all installed (but inactive) plugins and themes
3. Then it scans your database for option names, meta keys, and custom tables that match known plugin patterns (like yoast_, elementor_, woocommerce_)
4. If it finds a match that's not in the protected or installed lists, it flags it as potential ghost data
5. For filesystem scans, it checks wp-content and related directories for orphaned folders (limited to 3000 folders max to prevent timeouts)
6. Results are shown with the detected plugin name, data type, size/count, and risk level

Risk Levels Explained:

• 🔴 High Risk: Data from page builders (Elementor, Divi, Beaver Builder), eCommerce (WooCommerce), membership/LMS systems, custom field plugins (ACF), payment gateways, or custom tables. Deleting could break content or lose critical information.
• 🟠 Medium Risk: SEO plugins, form builders (Contact Form 7, Gravity Forms), multilingual plugins (WPML, Polylang), email marketing plugins, or content management tools. May contain settings or configurations you want to keep.
• 🟢 Low Risk: Caching, optimization, analytics, social sharing plugins, image optimization plugins, or backup plugins. Usually safe to delete.
• Note: Options over 50KB are automatically upgraded to high risk, and all custom tables are flagged as high risk regardless of the original plugin risk level.

How to Use the Scanner:

1. Go to the Optimize tab
2. Scroll down to find the "🔌 5. Legacy Plugin Data Scanner" section
3. Click "🔎 Scan for Ghost Data"
4. Wait a few seconds while it scans (rate-limited to once per 5 seconds)
5. Review the results table showing Data Source, Type, Size/Count, and Risk Level
6. Click "Delete" on individual items you want to remove
7. Confirm deletion in the popup with verification warnings
8. The item will fade out and be removed from the results table

What Gets Displayed:

Each detected item shows:

• Data Source: Plugin/theme name prefixed with "Legacy:" and the actual database key name or table name displayed in a code block
• Type: "Option" (from wp_options), "Meta" (from wp_postmeta), "Table" (custom database table), or "Folder" (filesystem directory)
• Size/Count: For options, shows human-readable data size (e.g., "12.3 KB"); for meta and tables, shows row count (e.g., "1,234 rows"); for folders, shows file count
• Risk Level: Color-coded badge showing Low (green), Medium (orange), or High (red)
• Delete button: One button per item for individual deletion (appears on the right side of each row)

Examples of Safe Deletions:

• Old SEO plugin settings if you've switched to a new one (Yoast → Rank Math)
• Cache plugin data if you've moved to a different caching solution
• Analytics plugin options from tools you no longer use
• Social sharing plugin data if you've removed those features
• Old theme settings from themes you've permanently replaced
• Image optimization plugin metadata after switching tools
• Backup plugin temporary tables if you no longer use that backup solution

What Happens When You Delete:

1. You click the "Delete" button for a specific item
2. A confirmation popup appears with verification requirements showing the exact item name and type
3. After confirmation, the plugin starts a database transaction for safety
4. It deletes the specific entry from wp_options, wp_postmeta, or drops the custom table entirely
5. It logs the action with your username and timestamp
6. The transaction commits (or rolls back if there's an error)
7. The deleted item fades out from the results table with a red background
8. Database statistics are automatically refreshed to reflect the freed space
9. If all items are deleted, a success message appears: "✅ All Clean! No detected ghost data remaining."

Technical Notes:

• Built-in Database: Recognizes 400+ popular plugins including SEO tools (Yoast, Rank Math, AIOSEO), page builders (Elementor, Beaver Builder, Divi), forms (Gravity Forms, Contact Form 7, WPForms), caching (WP Rocket, W3 Total Cache, LiteSpeed), eCommerce (WooCommerce and extensions), LMS (LearnDash, LifterLMS), analytics, multilingual (WPML, Polylang), and more
• Scan Limits: Top 250 autoloaded options (by size), top 250 postmeta keys (by count), all custom tables, and up to 3000 directories in the filesystem
• Rate Limiting: 5-second cooldown between scans to prevent server stress
• Protected Keys: Core WordPress options are automatically excluded (active_plugins, siteurl, home, blogname, admin_email, template, stylesheet, cron, db_version, user_roles, rewrite_rules, users_can_register)
• Protected Tables: Core WordPress tables are excluded (posts, postmeta, users, usermeta, options, comments, commentmeta, links, terms, termmeta, term_taxonomy, term_relationships)
• Transaction Safety: All deletions use database transactions with rollback on error to prevent partial deletions
• Caching: Filesystem scans are cached for 5 minutes to improve performance on subsequent scans
• Multisite Support: Includes both network-activated and site-specific plugins in the protected list

🎯 5.5. Targeted Optimizations

Located directly under the Database Health Score, this section offers four specialized cleanup tools that target specific areas of database bloat often missed by general cleaners. Each tool uses a multi-pass, JOIN-based approach to find orphaned data through actual referential checks — not just pattern matching.

• 🗓️ Action Logs: Cleans up completed, failed, and canceled entries from the Action Scheduler tables (wp_actionscheduler_actions, _logs, _claims, _groups). These tables grow rapidly on any site using WooCommerce, WP Mail SMTP, or similar plugins.
  • Two-phase deletion: First removes all finished actions (status complete, failed, canceled) in 2,000-row batches. Then runs a second pass to remove orphaned log, claim, and group rows that point to deleted actions — using LEFT JOIN … IS NULL queries rather than guessing by name or ID range.
  • Time-aware: On AJAX requests, the cleaner monitors execution time against your server's max_execution_time limit and stops safely when nearing it, preserving all data processed so far.
• 🎥 Embed Cache: Clears oEmbed cache data (YouTube, Spotify, Twitter embeds, etc.) stored in your database. This forces WordPress to re-fetch fresh embed HTML from the source — useful when embeds are broken or displaying outdated previews.
  • Two-table cleanup: Removes _oembed_* rows from wp_postmeta (per-post embed cache) AND clears matching transient pairs (_transient_oembed_* + _transient_timeout_oembed_*) from wp_options. Most tools only clean one location, leaving the other behind.
  • Keyset-paginated: Uses meta_id > last_id / option_id > last_id pagination so cleanup of tens of thousands of rows never stalls or drifts.
• 🛒 WooCommerce Cleanup: Runs six targeted passes against WooCommerce-specific bloat in wp_options and the native sessions table. Generic cleanup tools typically miss most of this data.
  • Pass 1 — Expired WC transient pairs: Finds _transient_timeout_wc_* records whose stored timestamp is in the past, then deletes both the timeout record and its matching _transient_wc_* value in a single query.
  • Pass 2 — Orphaned WC timeout records: Removes timeout records that have no matching value entry (LEFT JOIN orphan detection).
  • Pass 3 — Orphaned WC value records: Removes value records that have no matching timeout entry.
  • Pass 4 — Expired session pairs: Same atomic pair-deletion for _wc_session_expires_* + _wc_session_* records past their expiry timestamp.
  • Pass 5 — Orphaned session values: Removes session data with no matching expiry record.
  • Pass 6 — Native sessions table: If the wp_woocommerce_sessions table exists, removes expired rows directly from it.
  • Each pass runs in 2,000-row batches with a 20ms pause between batches to avoid locking the options table under load.
• 🏷️ Empty Taxonomies: Scans for and removes taxonomy terms that have a count of 0 and are not assigned to any content. Unlike simpler tools that just delete any zero-count term, this cleaner first classifies all taxonomies into three buckets:
  • Registered taxonomies (e.g., category, post_tag, custom plugin taxonomies): Deleted using wp_delete_term() — the correct WordPress API call that fires all hooks, updates counts, and cleans relationships correctly.
  • Unregistered taxonomies with active relationships (from deactivated but not uninstalled plugins): Skipped entirely to avoid breaking live data.
  • Orphan taxonomies (unregistered AND with no relationships): Deleted via direct SQL since wp_delete_term() cannot process unknown taxonomies. Cleans term_relationships, term_taxonomy, terms, and termmeta in one pass. After cleanup, wp_update_term_count_now() is called on all remaining taxonomies to keep counts accurate.

🔪 5.6. Detailed Database Cleanup

This section provides a button for every single item listed in the Database Statistics. It allows you to clean items one by one with full control.

⚠️ IMPORTANT: Safe vs. Unsafe (Review First)

Most items are "safe" to clean. However, some items are marked with a ⚠️ Warning Icon. These are "unsafe" because they involve deleting data you might want to review first.

• ✅ Safe to Clean: * Post Revisions, Auto Drafts, Trashed Comments, Orphaned Meta (all types), Expired Transients, Duplicate Meta, Pingbacks, Trackbacks.
• ⚠️ Unsafe (Review First): *🗑️ Trashed Posts: This will permanently empty your posts trash bin. *💬 Spam Comments: This will permanently delete comments marked as spam. *⏳ Unapproved Comments: This will permanently delete all comments awaiting moderation. *💾 All Transients: This will clear all cached data, including non-expired. While generally safe, it can temporarily break parts of your site that rely on active cache.

⚙️ How the Cleanup Engine Works

Every cleanup operation in this section shares the same underlying architecture, which sets it apart from standard database plugins:

• 🔑 Keyset Pagination (No Drift): All deletions use WHERE id > last_seen_id ORDER BY id ASC LIMIT N rather than LIMIT / OFFSET. This means the cleanup never loses rows or re-processes already-deleted data, even on tables with hundreds of thousands of rows.
• 📦 Transactional Batches: Every batch of up to 2,000 rows is wrapped in START TRANSACTION … COMMIT. If anything fails mid-batch, the entire batch rolls back cleanly. There are no partial deletes or half-cleaned states.
• 🌊 Cascade-Aware Deletion: The cleaner understands parent-child relationships in your database and always cleans children before parents. For example:
  • Post Revisions & Auto Drafts: Deletes matching rows from wp_postmeta AND wp_term_relationships for the post IDs in each batch before deleting from wp_posts. Most other plugins skip this step, leaving thousands of orphaned meta rows behind after a revision cleanup.
  • Trashed Posts: Goes further — also fetches all comments on those posts, walks the full comment reply tree (BFS traversal to collect all descendants), deletes wp_commentmeta for all collected comment IDs, then the comments themselves, then postmeta, then term relationships, then the posts. A single trashed post cleanup can touch six tables correctly.
  • Spam & Trashed Comments: Performs the same BFS reply-tree traversal to collect all descendant comments before deleting, ensuring no orphaned child comments or commentmeta are left dangling.
• 🔗 JOIN-Based Orphan Detection: Orphaned metadata cleanup (postmeta, commentmeta, usermeta) uses LEFT JOIN … WHERE parent.id IS NULL queries to find records whose parent no longer exists. This finds orphans that were created by buggy plugins or direct SQL deletes — not just records from the WordPress trash.
• 🧬 Duplicate Meta via Self-Join: The duplicate metadata cleaner uses a SQL self-join (m1 INNER JOIN m2 ON same parent + same key + same value WHERE m1.id > m2.id) to find exact duplicates across all four meta tables (post, comment, user, term). It always retains the record with the lowest ID (oldest), and deletes the newer duplicates.
• 🛡️ Parameter Whitelisting: Internal cleanup methods validate every table name and column against a hardcoded allowlist before executing any query. Even if called with wrong parameters internally, the methods reject the call entirely — a defense-in-depth measure that prevents any misconfiguration from touching unintended tables.
• ⏱️ Time-Aware: On AJAX requests, each loop monitors your server's max_execution_time and stops safely when approaching the limit, preserving all committed work. A 20ms micro-pause between batches prevents table lock contention on busy servers.

⚡ 5.7. Advanced Database Optimization

These are powerful tools for database maintenance. 💾 Always create a backup before using them.

• ⚡ Optimize All Tables: Defragments your database tables and reclaims wasted space ("overhead"). Unlike standard optimization that blindly runs OPTIMIZE TABLE on everything, this tool applies a different strategy per storage engine:
  • InnoDB tables (most WordPress tables): Attempts ALTER TABLE … ENGINE=InnoDB, ALGORITHM=INPLACE, LOCK=NONE first. This is an Online DDL operation — it defragments the table without any table lock, meaning your site remains fully readable and writable during the operation. Only if the server does not support online DDL does it fall back to standard OPTIMIZE TABLE.
  • MyISAM tables: Uses standard OPTIMIZE TABLE (the only available option for this engine).
  • Smart skipping: Tables with less than 1KB of overhead, zero rows, MEMORY engine tables, or non-base tables (views) are automatically skipped to avoid unnecessary locking.
  • Resumable: On AJAX requests, the process saves its position every 5 seconds. If the page is closed or times out, re-running it picks up where it left off rather than starting from scratch.
• 🛠️ Analyze & Repair Tables: A multi-phase diagnostic and repair tool. It runs CHECK TABLE in batches of 20, identifies any tables with corruption or crash markers, then runs REPAIR TABLE on those specifically. A final optimization pass is also applied to all large tables (>1,000 rows) as part of the same workflow. If your site is experiencing strange database errors, run this.
• ⚙️ Optimize Autoloaded Options: A highly advanced performance tool that intelligently reduces the amount of data loaded on every single page request.
  • ❓ What is Autoloaded Data? In your wp_options table, options marked autoload='yes' are loaded on every page request. If plugins store large data here (1MB+), it can severely slow your Time to First Byte (TTFB).
  • 🧠 Multi-Layer Safety System: This tool does not simply set everything to autoload='no'. It uses a layered decision tree to determine what is safe to optimize:
    • Layer 1 — Hardcoded Essential List: Core WordPress options (active_plugins, siteurl, cron, rewrite_rules, widget_*, theme_mods_*) and known critical options from WooCommerce, Elementor, Yoast SEO, and Wordfence are always skipped.
    • Layer 2 — Credential Protection: Any option whose name contains license, api_key, secret_key, or password is always skipped.
    • Layer 3 — Name Pattern Analysis: Options containing settings, config, or options in their name are treated as plugin configurations and skipped unless they are very large.
    • Layer 4 — Size + Pattern Combo: Known cache/temp patterns (_transient_, _oembed_, jetpack_sync_, wc_session_) are safe-listed at any size. Generic large options (>200KB) that don't match any settings pattern are optimized regardless.
  • 📐 Dynamic Thresholds: Size thresholds scale with your database size. A database over 100MB uses tighter thresholds (lower size before optimizing) because autoload overhead matters more at scale.
  • 🎯 The Result: The data is still safely in your database, but is only loaded when actually needed. This can significantly reduce TTFB, especially on sites with accumulated plugin data.

🔍 5.8. Database Structure Analysis

Inside section 9, under the Advanced tab, this tool provides a complete map of your database structure and allows you to remove unused tables.

• 📊 Database Summary: Shows total tables, core vs. plugin tables, and total size.
• 🏗️ WordPress Core Tables: Lists all standard WP tables (e.g., wp_posts, wp_users) with descriptions of what they do.
• 🧩 Plugin & Theme Tables: Lists all other tables created by your plugins and theme. This is extremely useful for identifying "orphaned tables" left behind by old, uninstalled plugins.
• 🗑️ Delete Unused Tables: You can permanently delete third-party tables directly from this interface.
  • 🕸️ Abandoned Detection: Tables that haven't been updated in over 30 days are marked with a spider web icon, helping you identify potential junk data.
  • ⚠️ Safety First: This action is irreversible. Only delete a table if you are certain the associated plugin/theme has been fully uninstalled.

🔢 5.9. MySQL Index Manager

The MySQL Index Manager is a powerful diagnostic tool that analyzes your database for missing or redundant indexes. Unlike standard cleanup tools, this module uses Prefix-Matching Analysis to ensure your database structure is optimized for high-traffic environments and complex queries, such as those generated by WooCommerce.

🔍 Analysis Categories

• 🔴 Missing Indexes: These are critical structural optimizations identified for core WordPress and WooCommerce tables.
  • Core Targets: Optimizes wp_options (autoloaded settings), wp_postmeta (custom field lookups), wp_posts (content queries), wp_usermeta, wp_commentmeta, and wp_termmeta.
  • WooCommerce Targets: Automatically detects and fixes missing indexes on high-traffic tables like wc_order_product_lookup to speed up sales analytics and reporting.
  • Column Validation: Before suggesting any index, the plugin verifies that every required column actually exists in your table. If a plugin removed or renamed a column, the suggestion is silently skipped rather than throwing an error.
• 🟡 Redundant Indexes: These are "duplicate" or "overlapping" indexes.
  • Definition: If Index A covers (post_id) and Index B covers (post_id, meta_key), Index A is redundant because Index B can handle all queries that Index A would.
  • Benefit: Removing these reduces the time the database spends updating indexes during every INSERT or UPDATE, improving overall site responsiveness.
  • Safety: The engine will never flag a UNIQUE index as redundant when the covering index is non-unique, preserving data integrity constraints even if the column overlap looks identical.

🚀 Workflow: Scan & Apply

1. Initiate Scan: Click the "Scan for Missing Indexes" button. The plugin reads all index metadata for your entire database from information_schema.STATISTICS in a single query, then performs analysis in PHP — minimizing database load during the scan.
2. Review Recommendations:
   • Recommendations will display the Table, Column(s), and a detailed Reason explaining the performance benefit.
3. Apply Fixes: Click "Fix Index" to add a missing index or "Remove Bloat" to remove a redundant one. All index operations run in a background worker (via WP-Cron) so they never block your browser or time out regardless of table size.

🔒 Lock-Free Index Operations

Adding or removing indexes on large tables can be a risky operation on busy sites. The Index Manager handles this intelligently:

• Online DDL First: For each operation, the plugin first attempts ALTER TABLE … ALGORITHM=INPLACE, LOCK=NONE. This is MySQL's online DDL mode — the table remains fully readable and writable during the entire index build. No downtime, no locked pages.
• Automatic Fallback: If the server does not support online DDL for that specific operation (e.g., certain older MySQL versions or MyISAM tables), it automatically falls back to a standard ALTER TABLE.
• Disk Space Pre-Check: Before starting any index operation, the engine checks available disk space. Building an index requires approximately 2× the table's current size as temporary space. If there is insufficient space, the operation is blocked with a clear message showing available vs. required space.
• Result Verification: After the operation completes, the plugin queries SHOW INDEX FROM table to confirm the index was actually added or removed — and marks the task as failed if the schema did not change as expected.

⚠️ CAUTION: LARGE TABLES

Adding or dropping indexes on tables with millions of rows can take several minutes. Thanks to Online DDL, your site remains accessible during the operation. However, it is still recommended to perform these operations during low-traffic periods on very large databases.

🛡️ 5.10. Referential Integrity Scanner

The Referential Integrity Scanner is a specialized sanitation tool designed to find "Zombie Data"—rows in your database that point to parent data that no longer exists.

🔍 What It Detects

• Orphaned Metadata:
  • Post Meta: Meta rows pointing to deleted posts.
  • Comment Meta: Meta rows pointing to deleted comments.
  • User Meta: Meta rows pointing to deleted users.
  • Term Meta: Meta rows pointing to deleted taxonomy terms.
• Broken Relationships:
  • Orphaned Revisions: Revisions in wp_posts that have no parent post.
  • Zombie Taxonomies: Rows in term_taxonomy that refer to term definitions that no longer exist.
  • Comments on Deleted Posts: Comments still attached to a post_ID that has been removed.

🚀 How to Use

1. Scan: Click the "Scan Database Integrity" button. The tool will check foreign key relationships across your core tables.
2. Review: Unlike the standard cleaner, this tool provides specific examples. It will show you the exact Issue Type (e.g., "Post Meta (Orphaned)") and provide sample IDs (e.g., #452: _edit_lock) so you can verify the data is truly junk.
3. Fix: Click the "Fix Orphans" button next to any issue found. The plugin uses a batched deletion process to remove the orphaned rows without timing out your server.

⚠️ SAFETY FIRST

While orphaned data is generally safe to remove (as it points to nothing), always create a database backup before running integrity fixes, just as you would with any database operation.

🛠️ Technical Resilience

The Index Manager includes several important safeguards:

• Dynamic Prefix Handling: Correctly identifies WooCommerce and Core tables regardless of whether your prefix is wp_, wp_custom_, or another variation.
• Case-Insensitive Table Matching: Ensures compatibility across different server environments (Linux/Windows) and collation settings.
• Constraint Protection: The logic is programmed to never suggest dropping a UNIQUE index or a PRIMARY KEY, even if it appears redundant, to preserve data integrity.

↳↰ 5.11. Database Search & Replace

Located in the "Advanced" tab, this professional-grade tool allows you to find and replace text strings across your entire database. It is essential for tasks like migrating domains (http → https), updating shortcodes, or fixing bulk content errors.

🚨 CRITICAL WARNING

This is a destructive operation. Changes made here cannot be "undone" without restoring a backup.
💾 You must create a fresh database backup (Section 1) immediately before running this tool.

🌟 Key Features:

• 📦 Deep Serialized Data Support: Unlike standard SQL search-and-replace approaches, this tool handles WordPress serialized data (PHP objects and arrays stored as strings in the database) correctly. It uses a recursive unserialize → replace → re-serialize strategy that understands the full structure of PHP serialized strings — including nested arrays, objects, and incomplete class instances. String length metadata within serialized strings is recalculated correctly after every replacement, preventing broken widget settings or plugin configuration data. The serialized data parser is Unicode-aware and handles multibyte characters properly throughout.
• 👁️ Dry Run (Preview): Scan your entire database without making any changes. Every match is shown with table name, column, row ID, and a highlighted excerpt with the matched text in context. The preview is capped at 500 entries or 512KB of preview data — whichever comes first — to prevent browser slowdown on very large datasets.
• 🎯 Scoped Table Selection: Run on all tables or select specific ones. The engine validates every table name against SHOW TABLES before executing — no user-supplied table name is ever directly interpolated into SQL.
• 🔎 Case-Sensitive Mode: When enabled, the SQL scan clause uses BINARY operators to find exact character-case matches. The regex replacement also switches to a non-insensitive pattern. Case sensitivity applies independently to both the scan and the replacement phases.
• 🔗 Two Matching Modes:
  • Word Boundary (Default): Uses Unicode-aware regex (\p{L} lookbehind/lookahead) rather than simple \b word boundaries, so it correctly handles accented characters and non-ASCII text. Searching for "test" finds "This is a test" but not "testing" or "latest".
  • Partial Match: Uses str_replace / str_ireplace for maximum speed. Matches text anywhere within strings — required for URL updates, path changes, or domain migrations.
• 🛡️ Protected Options: The wp_options table is given special treatment. Two categories of options are handled differently:
  • Permanently protected (never modified): active_plugins, wp_user_roles, cron, db_version, optistate_settings, and the plugin's own search-replace session transients.
  • Deferred options (updated last, in a separate transaction): siteurl and home. These are applied only after all other tables complete successfully, minimizing the window of URL inconsistency on a running site.
• 🔐 Concurrency Lock: Each operation (dry run and execute) is protected by a token-based lock stored as a WordPress transient. When you start an operation, a 32-character random hex token is returned. Every subsequent chunk of that operation must present this token. If two requests arrive simultaneously (e.g., accidental double-click), the second is rejected with a 409 Conflict response. Locks expire automatically after 10 minutes.
• ⏱️ Rate Limiting: Dry runs are rate-limited to one per 5 seconds per user; execute operations to one per 10 seconds. Repeated rapid requests receive a 429 Too Many Requests response.

🛠️ How to Use:

1. Input Terms: Enter the text you want to find (e.g., http://old-site.com) and the text to replace it with (e.g., https://new-site.com).
2. 🔡 Case Sensitivity: By default, searches are case-insensitive. Check "Case Sensitive" for exact-case matching (e.g., replacing a specific variable name or brand capitalization).
3. 🔗 Partial Match:
   • Unchecked (default): Unicode word-boundary matching. Use this for replacing standalone words in content.
   • Checked: Substring matching anywhere in the string. Required for URL updates, domain changes, and any partial text replacements.
4. Select Tables: Leave as "All Tables" for a full-site update, or use Ctrl/Cmd+Click to select specific tables.
5. 🔎 Step 1 — Dry Run: Click this button first. The plugin scans your database in 4-second AJAX chunks and shows a highlighted preview of every match found. Review carefully before proceeding.
6. ↳↰ Step 2 — Execute Replacement: Once you have verified the dry run results, click this to perform the actual replacement. Execution also runs in 4-second AJAX chunks with keyset pagination (WHERE pk > last_seen LIMIT 300) so it is resumable and never re-processes already-updated rows. Each batch of 300 rows is wrapped in a START TRANSACTION … COMMIT block. A failed batch triggers a ROLLBACK and logs the error — subsequent tables continue processing.

📋 Common Use Cases & Examples

🎯 Understanding Match Modes

⚙️ Best Practices

• 💾 Always backup first: Create a fresh database backup immediately before running any search and replace operation.
• 🔎 Run dry run first: Always preview results with a dry run before executing the replacement.
• 🎯 Start specific: For domain changes, include the full URL (e.g., http://oldsite.com) rather than just oldsite to avoid unintended matches.
• 🔗 Use Partial Match for URLs: Any URL-related updates require Partial Match mode to be checked.
• 📝 Use Word Boundary for text: When replacing actual words in content, leave Partial Match unchecked to avoid replacing parts of other words.
• 🧪 Test on staging first: If possible, test your search and replace on a staging/development site before running it on production.

⏰ 6. Automatic Backup & Cleanup (Section 10)

This section provides a "set it and forget it" scheduler for all the tools you just learned about.

⚙️ 6.1. Configuring the Scheduler

• 🔄 Run Tasks Automatically Every X DAYS: Set the frequency.
  • 0 = ❌ Disabled
  • 1 = 📅 Daily
  • 7 = 📅 Weekly
  • 30 = 📅 Monthly
• ⏰ Run at (Time): Select the time of day for the tasks to run.
  • 💡 Recommendation: Choose a low-traffic time for your site (e.g., 3:00 AM).
• 💾 Backup Only: Check this box to perform only the database backup at the scheduled time. The automatic cleanup tasks will be skipped.
  • 💡 Recommendation: This is useful if you want daily backups but prefer to run cleanup operations manually.
• 📧 Email Notifications: Check this box to have a summary report sent to your site's admin email address.

🔄 6.2. What the Scheduler Does (when it runs):

The scheduler will run in one of two modes, depending on your settings: *backup & cleanup* or *backup only*:

1. First, it 💾 creates a new database backup.
2. Then, it 🚀 runs the One-Click Optimization (all safe cleanups + table optimization).
3. Finally, it 📊 enforces the backup limit, deleting the oldest backup if necessary.
4. If enabled, it sends a success or failure email.

📧 6.3. Understanding Email Notifications (Success & Failure)

This is a key "pro" feature.

• ✅ Success Email: If tasks are completed, you get a simple report summarizing what was backed up and what was cleaned.
• ❌ Failure Email: If the backup or the cleanup fails, the plugin will send you a Failure Notification. This email is critical, as it will include:
  • What stage failed (e.g., "Backup Creation Failed").
  • A list of possible causes (e.g., "Insufficient disk space," "File permission problems," "PHP memory limit reached").
  • Recommended actions to resolve the issue.

⏱️ 6.4. A Note on WP-Cron

This scheduler uses the built-in WordPress Cron system (wp_schedule_single_event). This is not a "true" cron job, which means it relies on someone visiting your website to trigger the schedule.

If you set a schedule for 3:00 AM, the tasks will run on the first site visit that occurs at or after 3:00 AM. For most sites, this is perfectly reliable.

⚡ 7. Performance Features Manager (Section 11)

This is a complete, standalone performance suite.

🚫 7.1. CRITICAL: Do NOT Use With Other Caching Plugins

🚨 WARNING

The Server-Side Page Caching and Browser Caching features in this section will conflict with other caching plugins like WP Rocket, LiteSpeed Cache, W3 Total Cache, WP Super Cache, etc.

🤔 You must choose ONE.

If you are already using another caching plugin, 🚫 DO NOT enable "Server-Side Page Caching" or "Browser Caching" in WP Optimal State PRO. You can, however, still use all the "WordPress Core Optimizations" (Section 7.4).

💨 7.2. Feature: Server-Side Page Caching

This is the single most effective way to speed up your site. It converts heavy PHP processing into instant static HTML. When a visitor requests a page, a lightweight cached file is served directly, bypassing slow PHP and database queries. For example, after enabling this, viewing your homepage for the second time will load instantly from a pre-generated HTML file instead of rebuilding the page from scratch. Combine this with browser caching for ultimate performance.

• 🎯 The Concept (Dynamic vs. Static):
  • Dynamic (Slow): By default, WordPress builds every page from scratch for every visitor. It executes PHP, queries the database, and assembles the HTML.
  • Static (Fast): This feature saves that final HTML to a file in wp-content/uploads/optistate/page-cache/. Subsequent visitors get this file instantly, bypassing WordPress entirely.
• 🧠 The "Smart Cache" Engine:
  • 🛡️ Smart Exclusions (Automatic): The plugin automatically bypasses the cache for:
    • Logged-in Users: Administrators and members always see live content.
    • E-Commerce: Cart and Checkout pages (WooCommerce & Easy Digital Downloads) detected via session cookies (woocommerce_items_in_cart, edd_items_in_cart, etc.).
    • Tracking URLs: URLs containing marketing parameters: utm_*, fbclid, gclid, msclkid, mc_cid, mc_eid, _ga, ref, source.
    • Special Pages: Search results (?s=), 404 Error pages, Password-protected posts, and the Theme Customizer.
  • 🍪 Enterprise Cookie Detection: To comply with GDPR/CCPA, the cache is bypassed if a user has not given consent (unless "Disable Cookie Checks" is on). It supports consent cookies from:
    CookieYes, Complianz, Borlabs Cookie, Real Cookie Banner, Cookiebot, OneTrust, Termly, Iubenda, Moove GDPR, WP GDPR Cookie Consent, GDPR Cookie Consent, Cookie Control, and Cookie Notice.
    (You can also define a custom consent cookie in the settings)
  • 🔄 "Smart Purge" Logic: You rarely need to clear the cache manually. The plugin automatically clears the specific relevant files when you:
    • Update/Publish a Post: Clears the post itself, the Homepage, the Blog Feed (RSS/Atom), Author Archives, and Post Type Archives.
    • Edit Terms: Clears Category and Tag archives (including pagination).
    • Comments: Approving or changing a comment status refreshes the post.
    • Site Structure: Updating Menus, Widgets, or the Customizer clears the entire cache.
• ⚙️ Configuration Options:
  • 📊 Cache Status: Real-time stats showing Total Cached Pages, Mobile-Specific Pages, Total Size, and Last Write time.
  • 🗑️ Purge All Cache: Instantly deletes all .html files in the cache directory.
  • 🔋 Automatic Preload:
    • Function: Scans your sitemap.xml (detects from robots.txt or standard paths) and simulates a visit to every URL to generate the cache file.
    • Note: Runs in background batches to prevent timeouts. High CPU usage.
  • 🕒 Cache Lifetime: The maximum age of a cache file (default: 24 hours). After this expires, the next visitor will trigger a fresh page generation.
  • ❓ Query String Handling:
    • 1. Ignore All: example.com/page?ref=twitter serves the exact same file as example.com/page. (Fastest).
    • 2. Include Safe (Recommended): Ignores tracking params (like UTMs) but creates unique cache files for functional parameters. (Default).
      Safe Param List: page, paged, s, lang, sort, orderby, replytocom, view, amp, product_cat, product_tag, product-page, brand, eventDisplay, eventDate, forum-page.
    • 3. Unique Cache: Every unique URL creates a unique file. ⚠️ Risk: Can fill disk space rapidly if bot traffic hits random query strings.
  • ⛔️ Exclude Pages: Enter URL fragments to block caching (e.g., /my-account/* or /forum/). Supports wildcards (*).
  • 📲 Mobile-Specific Cache: Creates a separate -mobile.html cache file for mobile User-Agents. Enable ONLY if your site serves different HTML/Layouts to mobile devices (rare in modern responsive themes).
  • 🛡️ Disable Cookie Checks: Serves cached pages to everyone, ignoring consent cookies. ⚠️ GDPR Warning: Only use if you do not use a cookie banner or if your cached content is fully compliant without consent.
  • ⤷ Custom Consent Cookie: If you use a custom solution, enter your specific cookie name here (e.g., my_custom_consent). When this cookie is detected, the system will automatically serve cached pages to the user.

🔍 How to Verify Caching is Working:

After enabling page caching, you can easily confirm it's working by checking the page source:

1. Visit any page on your site (while logged out or in a private/incognito window).
2. Right-click anywhere on the page and select "View Page Source" (or press Ctrl+U on Windows / Cmd+Option+U on Mac).
3. Scroll all the way to the very bottom of the HTML source code.
4. Look for this comment: <!-- Cached by WP Optimal State Plugin -->

If you see this comment: ✅ The page was served from the static cache — your site is now delivering lightning-fast performance!
If you don't see it: The page was generated dynamically (this is normal for logged-in users, cart pages, or first visits before the cache is built).

🌐 7.3. Feature: Browser Caching (.htaccess)

This complements Server Caching. It tells a visitor's browser to save static files (like your logo, CSS, and JS) on their computer.

• ❓ What it is: When a user visits a second page, their browser doesn't need to re-download your logo; it can pull it from its local storage.
• 🔧 How it works: This feature modifies your website's root .htaccess file (this feature only works on Apache servers).
• 📝 The .htaccess Writable Check: The plugin will check if it can write to this file. If this section shows a warning, you must fix your server's file permissions (usually 644) for .htaccess.
• ➕ What it Adds:
  1. mod_expires: Tells browsers how long to cache file types (e.g., "cache images for 1 year," "cache CSS for 1 month").
  2. mod_deflate / mod_brotli: Enables Gzip and Brotli compression, making your files smaller.
  3. mod_headers: Adds security headers (like X-Content-Type-Options, X-Frame-Options) to improve your site's security score.

The following code block will be automatically added to the .htaccess file when this feature is activated:

🖥 7.3.1. Nginx Server Configuration (Security + Caching)

ℹ️ IMPORTANT: Nginx Users

If your server runs on Nginx instead of Apache, the Browser Caching (.htaccess) feature cannot be activated automatically because Nginx does not use .htaccess files.

All other plugin features work normally on Nginx servers, including:

• ✅ Database backup and restore
• ✅ Database cleanup and optimization
• ✅ Server-side page caching
• ✅ WordPress core optimizations
• ✅ Automatic scheduling

This section provides the configuration you need to manually add to your Nginx configuration file to enable browser caching and secure your plugin directories.

📍 Where to Add This Configuration

You need to add the configuration blocks below to your Nginx configuration file. This file is typically located at:

• /etc/nginx/sites-available/your-domain.com (Debian/Ubuntu)
• /etc/nginx/conf.d/your-domain.conf (CentOS/RHEL)
• Or inside your main nginx.conf file

⚠️ Important: Add these blocks inside your server { ... } block for your WordPress site.

🔐 Step 1: Secure Plugin Directories (Important)

Add this configuration to block direct access to sensitive plugin directories, such as database backups and your custom settings:

# ============================================================
# WP Optimal State - Directory Security (Nginx)
# ============================================================

# Block access to plugin settings directory
location ~* /wp-content/uploads/optistate-settings/ {
    deny all;
    return 403;
}

# Block access to database backup directory
location ~* /wp-content/uploads/optistate/db-backups/ {
    deny all;
    return 403;
}

# Block access to temp restore directory
location ~* /wp-content/uploads/optistate/db-restore-temp/ {
    deny all;
    return 403;
}

# Allow only .html files in cache directory, block everything else
location ~* /wp-content/uploads/optistate/page-cache/ {
    location ~* \.html$ {
        # Allow HTML files to be served
    }
    location ~* {
        deny all;
        return 403;
    }
}

🚀 Step 2: Browser Caching Configuration (Optional)

Add this configuration to enable browser caching for static assets and speed up site loading for returning visitors:

# ============================================================
# BEGIN WP Optimal State - Browser Caching (Nginx)
# ============================================================

# ------------------------------
# 0. Basic server tuning (safe defaults)
# ------------------------------
sendfile on;
tcp_nopush on;
tcp_nodelay on;
keepalive_timeout 65;
types_hash_max_size 2048;
server_tokens off;
etag off;

# ------------------------------
# 1. Compression: Brotli (if compiled) + Gzip fallback
# ------------------------------
# Brotli (requires ngx_brotli)
brotli on;
brotli_comp_level 6;
brotli_types text/plain text/css application/javascript application/json application/xml application/rss+xml application/wasm image/svg+xml;

# Gzip fallback
gzip on;
gzip_vary on;
gzip_proxied any;
gzip_comp_level 6;
gzip_types text/plain text/css application/javascript application/x-javascript application/json application/xml application/rss+xml application/wasm image/svg+xml;

# ------------------------------
# 2. Security and common headers
# ------------------------------
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
add_header X-Permitted-Cross-Domain-Policies "none" always;
add_header Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=(), usb=(), gyroscope=(), accelerometer=(), magnetometer=(), ambient-light-sensor=(), fullscreen=(self)" always;
add_header Cross-Origin-Resource-Policy "same-site" always;
add_header Content-Security-Policy "frame-ancestors 'self'; object-src 'none'; base-uri 'self'; form-action 'self'" always;
add_header Vary "Accept-Encoding" always;

# HSTS only on HTTPS
if ($scheme = https) {
    add_header Strict-Transport-Security "max-age=31536000" always;
}

# Hide PHP server header from upstream if possible
fastcgi_hide_header X-Powered-By;

# ------------------------------
# 3. Immutable static assets (1 year) — immutable for fingerprinted assets
# ------------------------------
location ~* \.(?:css|js|ico|jpg|jpeg|png|gif|webp|avif|svg|woff2|woff|ttf|eot|mp4|webm|mp3|ogg|aac|m4a|flac|wasm)$ {
    expires 365d;
    add_header Cache-Control "public, max-age=31536000, immutable" always;
    access_log off;
    log_not_found off;
    try_files $uri =404;
}

# ------------------------------
# 4. Static HTML fallback (24 hours)
# ------------------------------
location ~* \.(?:html|htm)$ {
    expires 24h;
    add_header Cache-Control "public, max-age=86400, must-revalidate" always;
    try_files $uri $uri/ =404;
}

# ------------------------------
# 5. PHP handling — let WordPress/plugins control PHP headers
# ------------------------------
location ~ \.php$ {
    include fastcgi_params;
    fastcgi_split_path_info ^(.+\.php)(/.+)$;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_pass unix:/run/php/php-fpm.sock;
    fastcgi_read_timeout 300;
}

# ------------------------------
# 6. Login/admin and sensitive files — never cache
# ------------------------------
location = /wp-login.php {
    add_header Cache-Control "no-cache, no-store, must-revalidate" always;
    add_header Pragma "no-cache" always;
    add_header Expires "0" always;
    include fastcgi_params;
    fastcgi_pass unix:/run/php/php-fpm.sock;
}

location ^~ /wp-admin/ {
    add_header Cache-Control "no-cache, no-store, must-revalidate" always;
    add_header Pragma "no-cache" always;
    add_header Expires "0" always;
    try_files $uri $uri/ /index.php?$args;
}

location ~* ^/(?:wp-config\.php|readme\.html|license\.txt|xmlrpc\.php)$ {
    add_header Cache-Control "no-cache, no-store, must-revalidate" always;
    add_header Pragma "no-cache" always;
    add_header Expires "0" always;
    deny all;
    return 404;
}

# ------------------------------
# 7. Reduce logging for static assets
# ------------------------------
location ~* \.(?:css|js|jpg|jpeg|png|gif|webp|avif|svg|ico|woff|woff2|ttf|eot)$ {
    access_log off;
    log_not_found off;
}

# ============================================================
# END WP Optimal State - Browser Caching (Nginx)
# ============================================================

📝 Step 3: Apply the Configuration

1. Access your server via SSH or your hosting control panel's file manager.
2. Open your Nginx configuration file for editing (the location depends on your server setup).
3. Add both configuration blocks inside your server { ... } block.
4. Test your configuration by running:
   sudo nginx -t
5. If the test passes, reload Nginx:
   sudo systemctl reload nginx

⚠️ IMPORTANT

If you're not comfortable editing Nginx configuration files, please contact your hosting provider or system administrator for assistance. Incorrect Nginx configuration can cause your site to become inaccessible.

Always backup your configuration file before making changes.

✅ Verification

After applying the configuration, you can verify it's working by:

• Browser Caching: Open your browser's Developer Tools (F12), go to the Network tab, and reload your site. Check the response headers for static files - you should see Cache-Control and Expires headers.
• Directory Security: Try accessing https://yoursite.com/wp-content/uploads/optistate-settings/ - you should get a 403 Forbidden error.

🏗️ 7.4. Feature: WordPress Core Optimizations (A-Z)

This is a comprehensive suite of toggles and configurations designed to disable or optimize non-essential WordPress features that can slow down your site.
These are all safe to use alongside other third-party caching plugins.

• 🌐 Server-Side Page Caching: Drastically improves site speed by storing fully rendered pages as static HTML files. When a visitor requests a page, the lightweight cached file is served directly, bypassing slow PHP and database queries. For example, after enabling this, viewing your homepage for the second time will load instantly from a pre-generated HTML file instead of rebuilding the page from scratch. Combine this with browser caching for ultimate performance. DO NOT ACTIVATE if you already use a caching plugin such as WP Rocket, LiteSpeed, WP Super Cache, etc (see section 7.2 for more details).
  • 💡 Recommendation: Activate (if not using another caching plugin).
  • ⚙️ Configuration Settings:
    • 📊 Cache Status: Real-time stats showing Total Cached Pages, Mobile-Specific Pages, Total Size, and Last Write time.
    • 🗑️ Purge All Cache: Instantly deletes all .html files in the cache directory.
    • 🔋 Automatic Preload: Scans your sitemap.xml and simulates a visit to every URL to generate the cache file. Runs in background batches to prevent timeouts.
    • 🕒 Cache Lifetime: The maximum age of a cache file (default: 24 hours). After this expires, the next visitor will trigger a fresh page generation.
    • ❓ Query String Handling: Controls how URLs with parameters are cached (Ignore All, Include Safe, or Unique Cache).
    • ⛔️ Exclude Pages: Enter URL fragments to block caching (e.g., /my-account/* or /forum/). Supports wildcards (*).
    • 📲 Mobile-Specific Cache: Creates a separate -mobile.html cache file for mobile User-Agents. Enable ONLY if your site serves different HTML/Layouts to mobile devices.
    • 🛡️ Disable Cookie Checks: Serves cached pages to everyone, ignoring consent cookies. ⚠️ GDPR Warning: Only use if you do not use a cookie banner.
    • ⤷ Custom Consent Cookie: If you use a custom solution, enter your specific cookie name here (e.g., my_custom_consent).
• 💻 Browser Caching (.htaccess): Enables browser caching by adding optimized caching and security rules to your .htaccess file. This improves page load times for returning visitors by storing static assets like your logo, CSS files, and JavaScript in their browser. For example, after a user visits your site, their browser will save your logo locally, so it doesn't need to be downloaded again on their next visit. Requires Apache server with writable .htaccess file. For Nginx servers, manual configuration is required (Section 7.3.1).
  • 💡 Recommendation: Activate (if on Apache and not using another caching plugin).
  • ⚙️ What It Adds:
    • mod_expires: Tells browsers how long to cache file types (e.g., "cache images for 1 year," "cache CSS for 1 month").
    • mod_deflate / mod_brotli: Enables Gzip and Brotli compression, making your files smaller.
    • mod_headers: Adds security headers (like X-Content-Type-Options, X-Frame-Options) to improve your site's security score.
• 🗄️ Database Query Caching: Advanced object caching for database queries. Reduces MySQL database load by caching complex query results directly in memory. For example, the list of recent posts in your sidebar will be stored in Redis or Memcached after the first page load, so subsequent page views don't need to query the database again for the same information.
  • 💡 Recommendation: Activate (⚠️ Requirement: A persistent object cache like Redis or Memcached must be active on your server. If missing, this feature cannot be enabled.)
  • ⚙️ Configuration Settings:
    • 🕒 Main Query TTL: Controls how long primary page queries (e.g., your homepage, single posts/pages, and archive loops) are stored.
      Tip: Set to 12-24 hours for mostly static sites, or 1-4 hours for frequently updated sites. (Options range from 5 Minutes to 1 Week).
    • 🕒 Secondary Query TTL: Controls caching for auxiliary queries (widgets, recent posts, related posts, and sidebars).
      Tip: These are less critical and can typically be cached 2-3x longer than main queries.
    • ⛔️ Exclude Post Types: A comma-separated list of post types that should never be cached to ensure real-time data accuracy.
      Default exclusions: shop_order, ticket, product (Crucial for dynamic e-commerce operations).
    • ⛔️ Exclude Post IDs: Specific post or page IDs (comma-separated) whose queries should always bypass the cache (e.g., highly dynamic members-only dashboards).
    • 💾 Flush on Post Save/Update: When enabled, the entire query cache is automatically cleared whenever a post or page is published, updated, or deleted. Ensures visitors always see fresh content.
    • 🗨️ Flush on New Comment: When enabled, the query cache clears whenever a comment is posted or its moderation status changes. Recommended for active blogs to keep comment counts perfectly synced.
• 𝐆 Font Loading Optimization: Optimizes delivery of external fonts (Google Fonts) to eliminate render-blocking resources, improve First Contentful Paint (FCP), and reduce Cumulative Layout Shift (CLS). For example, instead of your site appearing with invisible text while waiting for a custom font to download, text will immediately appear using a system font, then seamlessly swap to your custom font once it's ready.
  • 💡 Recommendation: Activate (Leave default options checked for most sites).
  • ⚙️ Optimization Strategy:
    • ⚡ Async Google Fonts: Loads fonts in the background so they do not stop the page from rendering. Uses advanced rel="preload" and media-switching techniques.
      Recommended: ✔ Enabled
    • 👁️ Force "display=swap": Ensures text remains visible immediately using a fallback system font, then seamlessly swaps to your custom font once downloaded. Prevents the dreaded "Flash of Invisible Text" (FOIT).
      Recommended: ✔ Enabled
    • 🔌 Preconnect to Font CDN: Establishes an early, prioritized connection to fonts.gstatic.com, reducing DNS lookup latency by hundreds of milliseconds.
      Recommended: ✔ Enabled
    • 🚫 Remove Google Fonts: A nuclear option that completely strips Google Fonts from your site for maximum privacy and raw performance.
      Recommended: ✘ Disabled (Default). Only enable if you've confirmed your theme and plugins work correctly without Google Fonts.
      ⚠️ Warning: This forces your site to use standard system fonts and disables the three optimization options above. Test thoroughly before deploying.
• ⏲ Lazy Load Images & Iframes: Enforces native browser lazy loading by injecting loading="lazy" and decoding="async" attributes into images and iframes. This improves Core Web Vitals by deferring off-screen media until needed. For example, images at the bottom of a long blog post will only load when the user scrolls down to them, saving bandwidth and speeding up the initial page display.
  • 💡 Smart LCP Detection: Unlike basic lazy loaders, this tool automatically detects "Above the Fold" contexts (like headers, heroes, logos) and the first few images on the page. It applies loading="eager" and fetchpriority="high" to these critical elements to dramatically boost your Largest Contentful Paint (LCP) score, while safely lazy-loading the rest.
• 🤖 Bad Bot Blocker: Blocks resource-intensive SEO crawlers that provide competitive intelligence to other businesses. Does NOT block legitimate search engines like Google, Bing, or regional search engines. For example, bots like AhrefsBot and SemrushBot, which can consume significant server resources by crawling your entire site daily, will be blocked from accessing your content. You can customize the list to match your needs (see section 7.6 for more details).
  • 💡 Recommendation: Activate (especially useful for reducing server load on shared hosting).
  • ⚙️ Configuration:
    • 🤖 Blocked Bots List: Customize the list of bot User-Agents to block (one per line). Default list includes MJ12bot, AhrefsBot, SemrushBot, DotBot, PetalBot, Bytespider, Mauibot, MegaIndex, SerpstatBot, BLEXBot, DataForSeoBot, and AspiegelBot.
• 📝 Post Revisions Limit: WordPress saves a new copy every time you click "Save Draft". Limiting revisions prevents database bloat while keeping recent versions for safety. For example, instead of saving 50 versions of a single blog post, you can limit it to 5, keeping the database lean while still having a safety net.
  • 💡 Recommendation: "Limit to 5 Revisions."
  • (Note: If this setting is defined in your wp-config.php file, this control will be disabled.)
• 🗑️ Automatic Trash Emptying: By default, WordPress automatically purges trashed posts and pages older than 30 days. However, you can customize this period or completely disable automatic emptying. For example, you can set it to 7 days to keep your trash cleaner for longer, or disable auto-empty if you prefer to manually review trash contents before permanent deletion. ⚠ Warning: Once emptied, deleted content cannot be recovered.
  • 💡 Recommendation: "WordPress Default (30 days)" or "14 Days."
  • (Note: If this setting is defined in your wp-config.php file, this control will be disabled.)
• ᯤ XML-RPC Interface: Disables the XML-RPC API used by legacy mobile apps. It has been replaced by the REST API and is a frequent target for brute-force attacks. For example, with this enabled, automated attack scripts trying to guess your password via the xmlrpc.php file will be completely blocked, reducing server load and improving security.
  • 💡 Recommendation: Activate (set to "✔ Active").
• ၊၊||၊ Heartbeat API Control: Reduces or disables the WordPress Heartbeat API that creates frequent AJAX calls (every 15-60 seconds). This saves server resources but may disable real-time features like post editing locks. For example, on a site where multiple authors aren't simultaneously editing the same post, you can set it to "Slow Down" to reduce background AJAX requests by 75%.
  • 💡 Recommendation: "Slow Down (Every 2 minutes)."
• 😊 Emoji Scripts: Removes the emoji detection JavaScript (wp-emoji-release.min.js) loaded on every page. Modern browsers display emojis natively, making this script redundant. For example, on a business website that never uses emojis, this removes an unnecessary HTTP request and JavaScript execution, slightly improving page load speed.
  • 💡 Recommendation: Activate (set to "✔ Active").
• ↩️ Self Pingbacks: Prevents WordPress from creating pingback notifications when you link to your own posts, reducing unnecessary database operations. For example, if you write a blog post that links to another post on your own site, without this feature WordPress would create a pingback comment for that internal link, cluttering your comments section and adding database overhead.
  • 💡 Recommendation: Activate (set to "✔ Active").
• 🔗 REST API Link Tag: Removes the <link rel="https://api.w.org/" ...> tag from your site's header. For example, viewing your site's HTML source will no longer include the line <link rel='https://api.w.org/' href='https://yoursite.com/wp-json/' />. The REST API itself remains fully functional; only the auto-discovery header is removed. (Safe to activate).
  • 💡 Recommendation: Activate (set to "✔ Active").
• 🔗 Shortlink Tag: Removes the <link rel='shortlink' ...> tag from your page headers. For example, a single post page will no longer output <link rel='shortlink' href='https://yoursite.com/?p=123' />. Shortlinks are rarely used, and removing them saves minimal bandwidth. (Safe to activate).
  • 💡 Recommendation: Activate (set to "✔ Active").
• 🔗 RSD (Really Simple Discovery) Link: Removes the RSD link tag, which is only used by old desktop blogging clients. For example, the line <link rel="EditURI" type="application/rsd+xml" title="RSD" href="https://yoursite.com/xmlrpc.php?rsd" /> will be removed from your site's header. If you don't use desktop software like Windows Live Writer to blog, this is safe to activate.
  • 💡 Recommendation: Activate (set to "✔ Active").
• 🪟 Windows Live Writer Manifest: Removes the wlwmanifest.xml link tag, used by a discontinued Microsoft product. For example, the tag <link rel="wlwmanifest" type="application/wlwmanifest+xml" href="https://yoursite.com/wp-includes/wlwmanifest.xml" /> will be removed. This is completely safe as the software is no longer in use.
  • 💡 Recommendation: Activate (set to "✔ Active").
• ♯ WordPress Version Meta Tag: Removes the <meta name="generator" content="WordPress X.Y.Z" /> tag. This is a minor security improvement, as it hides your WordPress version from simple scanners. For example, automated bots scanning for vulnerable WordPress versions will not see your version number in the page source.
  • 💡 Recommendation: Activate (set to "✔ Active").
• 📡 Feed Links (RSS & Atom): Removes RSS and Atom feed discovery links from page headers. The feeds themselves remain accessible via their direct URLs; only the auto-discovery <link> tags are removed. For example, after activation, a request to https://yoursite.com/feed/ will still return your RSS feed, but the browser will no longer automatically discover it. (Safe to activate).
  • 💡 Recommendation: Activate (set to "✔ Active").
• 🔗 Post Relational Links: Removes legacy relational <link> tags (index, start, parent, prev, next) from page headers. These are navigation hints not used by modern browsers. For example, on a single post page, the link <link rel='prev' href='https://yoursite.com/previous-post/' /> will no longer be output. (Safe to activate).
  • 💡 Recommendation: Activate (set to "✔ Active").

🔐 Advanced Security Features

7.4.1. File Path Validation & Path Traversal Protection

The plugin implements multi-layer file path validation to prevent directory traversal attacks and unauthorized file access:

Validation Layers

1. Path Normalization: All file paths are normalized using wp_normalize_path() to convert backslashes to forward slashes and resolve relative paths.
2. Boundary Checking: Every file operation verifies the path starts with the allowed directory (typically wp-content/uploads/optistate-*).
3. Malicious Pattern Detection: Blocks paths containing:
   • ../ or ..\ (directory traversal)
   • Null bytes (\0) - common in exploit attempts
4. Canonical Path Resolution: When using direct filesystem access (FS_METHOD='direct'), the system resolves symlinks with realpath() and verifies the canonical path is still within allowed boundaries.

7.4.2. JSON Data Encryption for Sensitive Information

Settings containing potentially sensitive data are encrypted using AES-256-CBC:

Encryption Implementation

• Algorithm: AES-256-CBC (Advanced Encryption Standard, 256-bit key, Cipher Block Chaining mode)
• Key Derivation: Uses WordPress AUTH_KEY constant hashed with SHA-256. If AUTH_KEY is unavailable, falls back to wp_salt().
• Initialization Vector (IV): Cryptographically secure random IV generated for each encryption using openssl_random_pseudo_bytes().
• Format: Encrypted data is prefixed with enc: and base64-encoded with IV prepended to ciphertext.

What Gets Encrypted?

Currently, encryption is available via OPTISTATE_Utils::encrypt_data() for:

• API keys (if storing third-party credentials)
• Email addresses in notification settings
• Any other sensitive configuration data extensions might add

7.4.3. SQL Injection Protection

Multiple layers protect against SQL injection attacks:

Protection Mechanisms

• WordPress $wpdb->prepare(): All dynamic queries use prepared statements with proper placeholders (%s, %d, %i for identifiers).
• Table Name Validation: Before DROP/ALTER operations, table names are validated against a whitelist pattern: /^[a-zA-Z0-9_]+$/ (alphanumeric and underscore only).
• Length Limits: Table names exceeding 64 characters (MySQL's limit) are automatically rejected.
• Prefix Validation: Operations on stray tables verify expected prefixes (optistate_old_, optistate_temp_) before execution.
• Identifier Escaping: When WordPress version supports it (%i placeholder), table names use identifier escaping. Otherwise, manual backtick escaping with double-backtick protection is applied.

Example Code (from class-optistate-activation.php)

// Safe table name validation before dropping
if (!preg_match('/^[a-zA-Z0-9_]+$/', $table_name)) {
    continue; // Skip invalid table names
}
if (strlen($table_name) > 64) {
    continue; // Skip names exceeding MySQL limit
}

// Use WordPress's identifier placeholder if available
if (method_exists($wpdb, 'remove_placeholder_escape')) {
    $wpdb->query($wpdb->prepare("DROP TABLE IF EXISTS %i", $table_name));
} else {
    // Fallback: manual backtick escaping with protection
    $safe_table_name = str_replace('`', '``', $table_name);
    $wpdb->query("DROP TABLE IF EXISTS `{$safe_table_name}`");
}

7.4.4. Nonce Verification & AJAX Security

Every AJAX request requires valid nonce verification:

• Nonce Action: All requests use OPTISTATE::NONCE_ACTION constant for verification
• User Capability Check: After nonce verification, check_user_access() confirms administrator capabilities
• Nonce Lifespan: Uses WordPress default (24 hours, 12-hour window)
• Automatic Refresh: The JavaScript frontend automatically refreshes nonces when they approach expiration

7.4.5. Login Protection System

The plugin includes a full brute-force protection system that tracks failed login attempts by IP address and blocks repeat offenders for a configurable period. It is designed to be both accurate and very fast — the critical path on login page loads is optimized to avoid database queries whenever possible.

Configuration Options

• Max Attempts: Choose 1–6 failed attempts before a block is applied (default: 3).
• Block Duration: Choose 1, 3, 6, 12, 24, or 48 hours (default: 6 hours). Only these exact values are accepted — arbitrary input is clamped to the nearest valid option.
• Cloudflare Mode: When enabled, the IP is read from the HTTP_CF_CONNECTING_IP header instead of REMOTE_ADDR, but only if the request is arriving from a verified Cloudflare IP range (all 21 IPv4 and IPv6 Cloudflare CIDR ranges are built in and cached for one week).

Three-Layer Check Sequence (Critical Path)

When a visitor hits the login page, the block check runs in this exact sequence, stopping at the first result to minimize overhead:

1. Request-level cache: A PHP static variable caches the result for the current request. If is_access_blocked() is called twice in the same request (once for login_init, once for authenticate), the second call returns instantly with no transient or database read.
2. Transient fast-path (block): Checks optistate_block_{ip_hash}. If the transient exists and its stored blocked_until timestamp is still in the future, the visitor is blocked immediately — no database query.
3. Transient fast-path (clean): Checks optistate_clean_{ip_hash}. If this transient exists, the IP was recently confirmed as not blocked — return clean immediately. This 60-second clean cache eliminates database reads for legitimate repeated login attempts.
4. Database query (cold path): Only if both transients are absent does the engine query the wp_optistate_login_protect table. On a hit, the result is immediately cached back into the block transient for the duration of the remaining block period. On a miss (legitimate user), the clean transient is set for 60 seconds.

Recording Failed Attempts

When a login fails, the engine uses a single INSERT … ON DUPLICATE KEY UPDATE query to either create a new record or atomically increment the attempt counter for the existing IP. The block timestamp is set in the same query using an IF(attempts_count >= max, blocked_until, 0) expression — making the transition from "tracking" to "blocked" a single atomic SQL operation with no race condition. The user agent is also stored (truncated to 255 bytes, UTF-8 safe) for audit purposes. A successful login from the same IP immediately deletes its record and clears both transients.

IP Address Resolution

The IP resolution logic correctly handles proxy chains:

• Standard requests: Uses REMOTE_ADDR directly.
• Behind a trusted proxy: When the connecting IP is in the trusted proxy list, the engine walks the X-Forwarded-For chain from right to left and selects the first non-proxy IP as the real client address.
• Cloudflare: When Cloudflare mode is enabled and the request arrives from a verified Cloudflare IP, the real client IP is read from HTTP_CF_CONNECTING_IP.
• IPv4-mapped IPv6: Addresses like ::ffff:1.2.3.4 are automatically converted to their IPv4 form before storage and comparison.
• IPv6 CIDR matching: Full IPv6 CIDR range matching with bit-level precision (not just string prefix comparison).
• Validation: After resolution, the final IP is validated with FILTER_VALIDATE_IP and stripped of any non-IP characters. If validation fails, it falls back to REMOTE_ADDR.

Blocking Scope

Blocking applies to all three WordPress login surfaces simultaneously:

• Standard login form: Checked via login_init (before the form renders) and authenticate filter (before credentials are verified). A blocked IP sees a custom 403 page instead of the login form — they cannot even attempt a password.
• XML-RPC: Returns a well-formed XML fault response with code 403.
• REST API: Returns a JSON error response with HTTP 403.

Automatic Record Cleanup

The table is self-maintaining. A scheduled cleanup routine runs automatically and deletes: expired block records (blocks whose blocked_until timestamp has passed), and casual attempt records (IPs with no block that have had no activity in the last 24 hours). If more than 100 records are deleted in a single cleanup pass and the table has more than 1MB of overhead, OPTIMIZE TABLE is automatically run to reclaim space.

Dedicated Database Table

Attempt data is stored in a dedicated wp_optistate_login_protect table with a UNIQUE KEY on ip_address (enabling the atomic INSERT/UPDATE), and compound indexes on (blocked_until, updated_at) and updated_at for fast cleanup queries. The table is never included in plugin backups and is recreated automatically on plugin reactivation.

📊 7.5. Feature: Performance Metrics (PageSpeed)

Located under the 'Statistics' tab in section 7, this module integrates the Google PageSpeed Insights API directly into your WordPress dashboard. It allows you to monitor real-world performance metrics without leaving the platform, focusing on the Core Web Vitals that impact your search engine rankings and user experience.

🔑 API Configuration & Security

• API Key Requirement: To use this feature, you must enter a valid Google PageSpeed Insights API key. This key remains visible in the settings field for easy management and verification.
  👉 Please note: the default key is a generic one and isn't unique to your website. You should get your own key for better security and accuracy.
• Persistence: Once saved, the key is stored securely in your settings.json file.

📈 Understanding the 7 Key Metrics

The plugin retrieves seven specific data points. The results are color-coded based on Google's official performance thresholds:

• ● Green (Good): The metric meets the recommended fast threshold.
• ● Orange (Average): Performance is acceptable but needs improvement.
• ● Red (Poor): The metric is significantly below recommendations and hurting UX.

Logged Metrics Glossary:

• 🎨 First Contentful Paint (FCP):
  Time until the first text or image is painted.
  Why it matters: It answers the user's question: "Is it loading?"
• 🖼️ Largest Contentful Paint (LCP):
  Time until the largest element (hero image, heading, video) becomes visible.
  Why it matters: This is the most important Core Web Vital for SEO. It tells the user the main content is ready.
• 📏 Cumulative Layout Shift (CLS):
  Measures visual stability. Do elements jump around while loading?
  Why it matters: Prevents users from accidentally clicking the wrong button due to a shifting layout.
• 🚀 Time to First Byte (TTFB):
  Measures the time from the user's request until the first byte of the response arrives from the server.
  Why it matters: A fast TTFB indicates efficient server processing and network response. High TTFB suggests server-side bottlenecks or slow hosting.
• 🚫 Total Blocking Time (TBT):
  Measures time the main thread is blocked, preventing input responsiveness.
  Why it matters: High TBT makes the site feel "frozen" or laggy when a user tries to scroll or click.
• ⏱️ Speed Index (SI):
  Measures how quickly the content is visually displayed during page load.
  Why it matters: A lower score means the user perceives the page as loading faster.
• 👆 Time to Interactive (TTI):
  Measures how long it takes for the page to become fully interactive.
  Why it matters: Ensures that when a user clicks a button, the site actually responds immediately.

💾 Smart Caching & Logging

• 30-Day Persistence: To reduce API overhead and provide a stable reference, audit results are cached for 30 days. You can bypass this cache at any time by clicking "Run Audit" to force a fresh test.
• Activity Logging: Every successful audit is automatically recorded in the Activity Log (Section 10) using the format: Performance Audit Updated (Score% - Strategy). For example: ⚡ Performance Audit Updated (98% - Desktop).

🤖 7.6. Feature: Bad Bot Blocker

Not all traffic to your website is human or helpful. Resource-intensive bots—such as aggressive SEO crawlers, backlink analyzers, and competitive intelligence tools—can consume up to 40% of your server resources without providing any value to your business or visitors.

🎯 What This Feature Blocks

The Bad Bot Blocker targets specific categories of bots that consume resources without benefiting your website:

• 🔗 SEO Crawler Bots: Tools like AhrefsBot, SemrushBot, and MJ12bot that crawl your site repeatedly to build backlink databases. These only benefit their platforms' subscribers, not your website.
• 📊 Competitive Intelligence Bots: Bots that analyze your content, pricing, and structure to provide data to your competitors or third-party analytics services.
• ⚡ High-Volume Crawlers: Bots known for aggressive crawling patterns that ignore standard rate-limiting protocols and consume excessive bandwidth.

🤖 Default Blocked Bots List

When enabled, the following bots are blocked by default. This list has been carefully curated to include only resource-intensive crawlers that provide no direct benefit to your website:

⚙️ How It Works

• 🛡️ Early Blocking: Bots are identified by their User-Agent string and blocked before they can trigger resource-intensive WordPress processes.
• 📉 Immediate Resource Savings: By preventing these bots from executing PHP and database queries, your Time to First Byte (TTFB) remains stable even during high bot activity.
• ✅ SEO Safe: This feature is carefully designed to never block legitimate search engines (Google, Bing, DuckDuckGo, Yahoo, Yandex) or social media crawlers, ensuring your search rankings and social sharing remain unaffected.
• 🔧 Fully Customizable: Advanced users can modify the blocked bot list in the Performance tab to suit their specific needs or allow certain crawlers if they use those services.

🖥️ Server Compatibility

💡 When Should You Use This Feature?

💡 PRO TIP: Nginx Users

For maximum performance, we recommend combining this feature with the Nginx security rules provided below. This allows your server to drop bad traffic at the web server level, before it even reaches PHP or WordPress—resulting in even greater resource savings.

🚀 Nginx Implementation Guide

If you are using an Nginx server, add the following block to your server configuration file (e.g., /etc/nginx/sites-available/your-domain.com) inside the server { } block. This will block bots at the web server level for maximum efficiency:

# WP-OPTIMAL-STATE: High-Performance Bot Blocking
if ($http_user_agent ~* (MJ12bot|AhrefsBot|SemrushBot|DotBot|PetalBot|Bytespider|Mauibot|MegaIndex|SerpstatBot|BLEXBot|DataForSeoBot|AspiegelBot)) {
    return 403;
}

Important: After adding this configuration:

1. Test your configuration: nginx -t
2. If test passes, reload Nginx: systemctl reload nginx
3. Monitor your server logs to ensure legitimate traffic isn't affected

🎯 8. Optimization Strategies: Putting It All Together

Here are a few "recipes" for common scenarios.

🚀 8.1. Strategy 1: The First-Time Setup (5-Minute Tune-Up)

1. 💾 Backup: Go to Section 1 -> Click Create Backup Now.
2. 🔍 Diagnose: Go to Section 3 -> Click Refresh Analysis to see your starting Health Score.
3. ✨ Optimize: Go to Section 2 -> Click 🚀 Optimize Now.
4. ⏰ Automate: Go to Section 10 -> Set "Run Tasks" to 7 days and your preferred time. Check 📧 Email Notifications. Click Save Settings.
5. 🛡️ Harden: Go to Section 11 -> Activate all the "WordPress Core Optimizations" (Emoji Scripts, XML-RPC, etc.). Click Save Performance Settings.
6. ✅ Done. Your database is now clean and will stay clean automatically.

🆘 8.2. Strategy 2: The "My Site is Slow" Emergency Plan

1. 💾 Backup: Go to Section 1 -> Click Create Backup Now.
2. 🔍 Diagnose: Go to Section 6. Look at Autoload Data Size. If this is high (e.g., > 1 MB), this is your problem.
3. 🔧 Fix Autoload: Go to Section 9 -> Click ⚙️ Optimize Autoloaded Options.
4. 🔧 Fix Overhead: Go to Section 9 -> Click ⚡ Optimize All Tables.
5. 💨 Enable Caching: (If you have no other cache plugin) Go to Section 11 / Server-Side Page Caching.
   • Enable Server-Side Page Caching. Use the "Include Safe" query mode.
   • Enable Browser Caching (.htaccess).
   • Click Save Performance Settings.
6. 🗑️ Purge & Preload: Go to Section 11 / Server-Side Page Caching -> Click 🗑️ Purge All Cache. If you enabled "Automatic Preload," this will start the cache warming process.
7. ✅ Done. Your site should now be significantly faster.

📅 8.3. Strategy 3: The Monthly Maintenance Tune-Up

(Assuming you already have the automatic schedule running).

1. 🔍 Check Backups: Go to Section 1. Make sure your automated backups are being created.
2. ❤️ Review Health: Go to Section 3. Check your Health Score.
3. 🔪 Manual Cleanup: Go to Section 8. Manually clean the "unsafe" items if you wish:
   • Click "Clean Now" for 🗑️ Trashed Posts.
   • Click "Clean Now" for ⏳ Unapproved Comments (if you've already moderated them).

📥 9. Settings & Security (Section 12)

This utility allows you to save all your plugin configurations to a single .json file. You can use this to create a backup of your settings or to quickly migrate your exact setup to another website. You can also restrict plugin access to specific administrator accounts.

🚨 IMPORTANT: What is NOT Exported

This feature ONLY exports the plugin's settings, such as your configurations for scheduled tasks, performance features, and user access restrictions. It does NOT export your database backups, cached pages, or activity logs. Always download your database backups separately from Section 1.

📤 9.1. Exporting Settings

1. Navigate to Section 12: Settings & Security in the plugin dashboard.
2. Click the "Export Settings" button.
3. Your browser will download a file named optistate-settings-YYYY-MM-DD-His.json.
4. Keep this file in a safe place.

📤 9.2. Importing Settings

This will completely overwrite all your current plugin settings. This is useful for restoring your configuration after an update (as described in Section 2.7) or for setting up a new site.

1. Click the "Choose JSON File" button and select the json file you previously exported.
2. The plugin validates the file. It must be a valid .json file, under 1MB, and contain the "WP Optimal State" signature.
3. Once validated, click the "Import Settings" button.
4. A confirmation pop-up will appear warning you that your current settings will be overwritten. Click "OK" to proceed.
5. After a successful import, you will be prompted to reload the page to see the new settings take effect.