Technical Documentation

Introduction

Welcome to thePlugoSpeed Core Documentation. PlugoSpeed is an advanced performance optimization and server caching suite engineered specifically for commercial WordPress networks. It operates as the foundation performance layer of the PlugoPress ecosystem, bypasses database-heavy bottlenecks, and optimizes client-side resource delivery to yield perfect Core Web Vitals scores.

PlugoSpeed has been designed from the ground up to serve flat static physical assets to anonymous traffic directly via web-server levels, without triggering heavy PHP processes or complex queries. This manual serves as a comprehensive developer reference, detailing settings schemas, database tables, WP-CLI interfaces, REST endpoints, and action schedulers.

Understanding Caching

What is Caching?

Caching is the architectural process of storing temporary, pre-rendered copies of digital assets or database payloads in a high-speed storage medium (typically the server's local NVMe or SSD storage, or RAM). When a client requests a page, the server delivers the cached asset instantly. This avoids running heavy back-end scripts, compiling template engine designs, and querying relational database servers repeatedly.

By transforming dynamic web pages into static visual files, caching represents the single most effective method to dramatically accelerate server response times and handle massive traffic spikes without scaling hardware resources.

How Caching Works in WordPress

In standard WordPress environments, dynamic page requests follow a highly resource-intensive path:

1. An incoming HTTP request triggers the server's PHP process.
2. WordPress core loads runtime configurations, libraries, and active plugins.
3. Multiple SQL connection commands are dispatched to the MySQL/MariaDB database to fetch layout settings, post content, and metadata.
4. The active theme compiles structural template PHP files into visual HTML.
5. Third-party script hooks and tracking codes are injected before streaming response text to the browser.

This dynamic process consumes CPU cores, utilizes memory segments, and increases Time to First Byte (TTFB).PlugoSpeed eliminates this lifecycle entirelyfor anonymous traffic by intercepting requests at the web-server layer, checking for an existing static HTML document on disk, and serving it in milliseconds without executing a single line of PHP or MySQL.

Plugin Requirements

To guarantee absolute operational stability and enable high-performance physical file generation, the hosting environment must meet the following standard requirements:

Verification Checklist

To confirm that PlugoSpeed caching is fully active on your server, you should verify the HTTP response headers. Because PlugoSpeed implements a high-performance Apache file-drop rewrite layer, requests served from cache will bypass the WordPress pipeline entirely and append custom headers at the server level.

Follow these steps to audit your installation performance:

1. Open your browser's Developer Tools (F12) and select theNetworktab.
2. Load your site's landing page in an Incognito window (so that you are fully logged out).
3. Click on the primary document request and examine theResponse Headers.
4. Look for the custom caching tracking headers listed below.

Apache HTML Drop-In

At the heart of PlugoSpeed's exceptional TTFB performance is ourApache-level `.htaccess` rewrite engineand our PHP drop-in wrapper advanced-cache.php. When caching is enabled, the plugin writes absolute rewrite rules directly to the host's root configuration files.

When a visitor requests a page, the Apache server verifies the existence of a corresponding static HTML file on disk prior to launching any PHP scripts. If a matching static file is found in the physical cache folder and the visitor has no active session cookies, Apache handles the request immediately.

Cache Storage Architecture

Flat HTML physical file structures are organized systematically on the server's disk to prevent path collisions. Each cached page corresponds to a directory path under your WordPress directory:

wp-content/cache/plugospeed/{host}/{request_uri}/index.html
wp-content/cache/plugospeed/{host}/{request_uri}/index.html.gz

PlugoSpeed writes both uncompressed and Gzipped variants of the static content. The Gzip file is leveraged by the web server configuration to serve compressed assets natively, reducing raw bandwidth payloads on network routes.

Background Preheating Queue

Serving cached pages is only effective if files are already generated. If cache clearing occurs or dynamic updates occur sitewide, relying on visitors to trigger cache builds creates high latency for early traffic. To mitigate this bottleneck, PlugoSpeed deploys a backgroundCache Preheating Engine.

The preheating queue leverages the native WordPress Action Scheduler. It parses XML sitemaps systematically, populates an processing registry inside the database, and dispatches background runner tasks.

// The preheater schedules batches of 20 URLs to be processed asynchronously
// using Action Scheduler. This prevents server CPU spikes and limits memory utilization.
add_filter( 'plugospeed_preload_batch_size', function( $size ) {
    return 30; // Increase batch size on high-performance dedicated servers
} );

AST Minification Scanner

To optimize structural files, PlugoSpeed integrates a customAbstract Syntax Tree (AST) minifier scannerbased on mature minification libraries. The compiler reads raw CSS stylesheets and JavaScript assets, parses the code block into syntactic trees, eliminates unnecessary properties, and compresses output variables.

Unlike regex-based minifiers which frequently introduce syntax errors or break script logic, AST minification preserves absolute parsing safety by auditing statement dependencies.

• CSS Optimizer:Combines overlapping class rules, strips redundant margins, handles clean shorthand configurations, and minifies variables.
• JS Compactor:Removes spacing, strips logs and comments, resolves global constants, and optimizes lexical blocks.

Script Defer & Delay

To address blocking resource warnings and eliminate initial load latencies, PlugoSpeed implements advancedScript Defer and Delay engines.

Defer Engine:Automatically appends the defer attribute to HTML <script> selectors, instructing browsers to load scripts asynchronously during page parsing, preventing render-blocking bottlenecks.

Delay Engine:Postpones the load and execution of heavy client-side scripts (such as trackers, chatbots, maps, and analytics) until the visitor performs an active physical input (scrolls, touches, or clicks). This ensures that Total Blocking Time (TBT) and Interaction to Next Paint (INP) remain at0mson mobile viewports.

// Core Vanilla JS delaying execution wrapper used by PlugoSpeed Optimizer
const userInteractions = ['click', 'mousemove', 'mousedown', 'keydown', 'touchstart', 'scroll'];
function triggerScripts() {
    userInteractions.forEach(event => window.removeEventListener(event, triggerScripts));
    loadDelayedScriptsQueue(); // Injects delayed scripts dynamically in DOM
}
userInteractions.forEach(event => window.addEventListener(event, triggerScripts, { passive: true }));

Commerce Cart Routing

In transactional websites (such as sites utilizing WooCommerce), caching commercial grids or pages with active user baskets can lead to severe security and display bugs. PlugoSpeed features seamlessCommerce Cart Routing.

The caching drop-in scans active request cookies on every initial inbound payload. If a dynamic transactional session is detected—such as items in the cart or customized accounts—the drop-in bypasses flat caching entirely.

Exclusion Cookie Array

PlugoSpeed monitors the following system cookies to execute cache bypass rules dynamically:

• woocommerce_items_in_cart - Active customer cart bypass.
• woocommerce_cart_hash - Unique session tracking hash.
• wp_woocommerce_session_ - WooCommerce token cookie.
• comment_author_ - Active blog commenter sessions.
• wordpress_logged_in_ - Standard logged-in member session.

Advanced Exclusions

For advanced custom application scenarios, developers can declare custom URL pattern exclusions, query string rules, or physical cookie identifiers to route requests through the dynamic PHP engine.

Exclusion rules are defined in the dashboard's Cache settings and are saved as a structured JSON array within the primary settings database entry. Patterns support simple wildcards (`*`) to target complete subdirectories.

// Dynamically bypass page caching programmatically via theme code
add_filter( 'plugospeed_bypass_cache', function( $bypass, $uri ) {
    if ( strpos( $uri, '/custom-api-route/' ) !== false ) {
        return true; // Forces page to bypass static HTML write/read layers
    }
    return $bypass;
}, 10, 2 );

REST API Directory

PlugoSpeed registers13 secure REST API endpointsunder the system namespace plugospeed/v1. These routes are leveraged by our React-based administration dashboard, external monitoring pipelines, and remote SaaS nodes to audit cache status and trigger optimization sweeps.

All POST routes require valid standard nonce verification or authenticated admin tokens.

WP-CLI Console Command Reference

For advanced DevOps automation and deployment scripting, PlugoSpeed registers6 complete subcommandsunder the unified root command namespace wp plugospeed. This allows sysadmins to trigger manual sweeps, settings migrations, or status audits via terminal shells.

1. Purge Cache

Clears the global caching directory, a specific path, or a post ID.

wp plugospeed purge --all
wp plugospeed purge --url="https://yourdomain.com/category/slug"
wp plugospeed purge --post=124

2. Preheat Cache

Launches or queues preheating procedures through sitemaps.

wp plugospeed preload --sitemap="https://yourdomain.com/sitemap_index.xml"

3. Cache Metrics

Prints files counts, directories paths, and byte sizes on the CLI console.

wp plugospeed stats --format=json
wp plugospeed stats --date="2026-05-25"

4. Settings Modifiers

Query, set, reset or list options schemas in JSON layout.

wp plugospeed settings get cache_ttl
wp plugospeed settings set lazy_load_images 1
wp plugospeed settings list

5. Cloud License Audits

Forces keys and endpoints verification checks manually.

wp plugospeed cloud validate
wp plugospeed cloud refresh

6. Shell Debug Mode

Controls output logging to file system targets.

wp plugospeed debug on
wp plugospeed debug off

Database Schema & Storage Architecture

PlugoSpeed uses WordPress core configurations to track structural parameters. During plugin activation, the database migration module registers and runs dbDelta() to register **two primary data storage structures**.

1. Cache Stats Table

Stores hit and miss metrics dynamically. The stats tracking drop-in writes logs on every request. The records are aggregated to render the performance dashboard charts.

CREATE TABLE {$wpdb->prefix}plugospeed_cache_stats (
    id bigint(20) UNSIGNED NOT NULL AUTO_INCREMENT,
    recorded_at date NOT NULL,
    cache_hits bigint(20) UNSIGNED DEFAULT 0,
    cache_misses bigint(20) UNSIGNED DEFAULT 0,
    bypass_count bigint(20) UNSIGNED DEFAULT 0,
    PRIMARY KEY (id),
    UNIQUE KEY recorded_at (recorded_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

2. PageSpeed History Table

Tracks 30-day historical Google PageSpeed performance trends. To prevent resource inflation, daily measurements are logged via clean daily metrics upsert queries.

CREATE TABLE {$wpdb->prefix}plugospeed_pagespeed_history (
    id bigint(20) UNSIGNED NOT NULL AUTO_INCREMENT,
    date_recorded date NOT NULL,
    desktop_score tinyint(3) UNSIGNED NOT NULL,
    mobile_score tinyint(3) UNSIGNED NOT NULL,
    metrics_data text DEFAULT NULL,
    PRIMARY KEY (id),
    UNIQUE KEY date_recorded (date_recorded)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Hooks & Filters Extensibility

PlugoSpeed exposes rich standard actions and filters, empowering custom theme developers and third-party plugin integrations to alter page rendering, intercept purges, or override caching behaviors programmatically.

Core Filters Directory

Core Actions Directory

Troubleshooting & System Logs

If you encounter unexpected rendering behaviors or performance bottlenecks under specific hosting configurations, audit the items listed below:

Common Performance Checkpoints

• Permission Failures:Verify that your server PHP process has write permissions inside the wp-content/ folder directory. If permissions are misconfigured, PlugoSpeed cannot write the drop-in file or populate the static HTML folder structure.
• Missing HTACCESS Rules:Under Apache environments, check your .htaccess configurations. If security plugins block standard directory rewriting or overwrite standard root files, custom caching will fall back to dynamic PHP routines, raising TTFB numbers.
• Dynamic AJAX Scripts:If interactive page elements (such as stock counters or dynamic user details) render stale inputs, adjust minification settings or delay scripts tags inside settings.

System Logs Interface

PlugoSpeed logs execution routines inside standard files located in your uploads folder. You can examine these tracks to analyze server metrics:

wp-content/uploads/plugospeed-logs/debug.log
wp-content/uploads/plugospeed-logs/preload.log