Static Cache Wrangler
| 开发者 | derickschaefer |
|---|---|
| 更新时间 | 2026年1月8日 06:27 |
| PHP版本: | 7.4 及以上 |
| WordPress版本: | 6.9 |
| 版权: | GPLv2 or later |
| 版权网址: | 版权信息 |
详情介绍:
Static Cache Wrangler is a lightweight, low‑resource static site generator and HTML export engine for WordPress. It automatically creates self‑contained, URL‑agnostic static pages of your site — perfect for anyone who needs to preserve, distribute, or accelerate WordPress content.
Originally developed as a command‑line tool for WP‑CLI, it has evolved into composable, zero‑impact tooling that supports administrators, developers, and site owners alike. Whether you're archiving a client project, deploying to a CDN, or creating a portable offline version that runs anywhere, Static Cache Wrangler delivers fast, CDN‑ready HTML output without complex setup.
Technically, the plugin uses an asynchronous, lazy‑loading build mechanism that generates static pages as visitors browse your site. Over time, your entire site is exported as lightweight static HTML.\
Free companion plugin STCW Coverage Assistant adds real‑time build monitoring and manually triggered full‑site generation for any uncached pages.
Unlike traditional static‑site plugins that require full crawls or database schema changes, Static Cache Wrangler is zero‑impact:
- Does not add custom database tables or modify your schema
- Automatically cleans up all plugin options, cron jobs, and transients upon uninstall
- Keeps your WordPress database completely untouched
- Runs all caching processes asynchronously in the background
- Offers an optional performance profiler for granular resource and execution insights Perfect for:
- Creating fully offline or portable copies of WordPress sites
- Rsyncing to read‑only Nginx failover servers for high availability
- Publishing WordPress content to Amazon S3®, Netlify®, or other static CDNs
- Geo‑distributing static HTML for ultra‑fast global reads
- Archiving, demos, and secure client deliverables
- Small to mid‑sized sites (≈ 100 pages +) — upcoming assistant plugin expands this to 1 K pages
- Multisite administrators needing scalable static‑cache exports A demo site created using this plugin can be found at Cache Wrangler Demo Site which is a static version of this WordPress site
- Triggering of page rendering requires 1-2MB of PHP memory for the duration of the process.
- Average processing duration is less than 500 ms (meaning memory consumption is quickly released)
- Average asset (JS, CSS, image) batch processing is less than 100 ms
- WordPress Core and theme rendering is generally 20-25 MB; SCW usage keeps total memory below 30 MB
- CLI commands are even more efficient Funding Model
- This plugin and all companion plugins will remain 100% free (true WordPress style)
- Want to make a donation? Consider purchasing a copy of the author's book on command-line interfaces for yourself or as a gift. Modern CLI Book
- Enable static site generation using the toggle in the sidebar.
- As users browse your site normally, each page visit creates a static HTML file.
- Assets (CSS, JS, images, fonts) are automatically are queued and asyncronously downloaded and localized.
- Processing happens in the background and can be paused anytime.
- Use free companion plugin to monitor and accelerate cache creation STCW Coverage Assistant
- Download the complete static site as a ZIP file.
- Extract and open
index.htmlin any browser — it works completely offline.
wp scw sitemap- Generate sitemap.xml from cached static fileswp scw sitemap-delete- Remove sitemap files
- Perfect accuracy - sitemap matches exported content exactly
- True portability - works without WordPress/PHP/database
- SEO compliance - search engines see what users see
- Deploy anywhere - S3, Netlify, GitHub Pages, any static host
- Generates sitemaps.org compliant XML sitemap
- Creates XSL stylesheet for browser viewing
- Calculates priorities automatically (homepage = 1.0, deeper pages = 0.4)
- Assigns smart change frequencies (homepage = daily, pages = monthly)
- Includes last modification times from file metadata
- Developer filter hook:
stcw_sitemap_changefreq - Multisite compatible with isolated sitemaps per site
- Fast performance: ~50-100ms per 100 cached files
- New STCW_Sitemap_Generator class scans cached directory recursively
- Uses WordPress Filesystem API for all file operations
- Proper output escaping and sanitization throughout
- No database queries - pure file system operations
- Multisite compatible with isolated sitemaps per site
- Performance optimized: ~50-100ms per 100 files, ~2MB memory for 1,000+ pages
- WordPress 6.8.3
- PHP 7.4, 8.0, 8.1, 8.2, 8.3
- Multisite compatible
- WP-CLI required for sitemap generation
wp_print_scripts() and wp_print_footer_scripts()—ensuring that interactive block functionality is preserved outside of WordPress.
Compatibility Improvements
- Full Kadence Blocks compatibility – Global front-end scripts and CSS are now correctly captured, enabling buttons, accordions, icons, Lottie animations, progress bars, and other JS-driven components to function in static exports.
- Enhanced Gutenberg block support – STCW now reliably detects and exports front-end assets from all major block suites (Spectra, Stackable, GenerateBlocks, CoBlocks, Otter, etc.).
- Improved script capture logic – Dynamically enqueued scripts are now collected before theme rendering, eliminating missing-asset issues for blocks that load JS only when present on a page.
- Better preservation of front-end behavior – Assets required for tooltips, animations, scroll effects, responsive layouts, and block initialization are now exported consistently.
- Resolved blank-page edge cases – Updated capture timing ensures no interference with WordPress's script printing lifecycle, preventing rendering conflicts.
- Added an early script-queue flush to collect output from:
wp_print_head_scripts()wp_print_scripts()wp_print_footer_scripts()- Captured script output is appended to the main buffer before asset extraction, ensuring regex-based scanners detect dynamically enqueued JS/CSS.
- Improved compatibility with theme and plugin lifecycle order by isolating script capture from template rendering.
- Enhanced support for plugins that insert block assets conditionally based on block presence.
- Increased reliability of static exports for mixed-content layouts and advanced interactive block patterns.
wp scw enable– Enable static generationwp scw disable– Disable static generationwp scw status– View current status and statisticswp scw process– Process all pending assetswp scw clear– Remove all generated static fileswp scw zip– Create a ZIP archive of the sitewp scw sitemap– Generate sitemap.xml from cached fileswp scw sitemap --target-url=<url>– Generate sitemap for deployment URLwp scw sitemap-delete– Remove sitemap files
安装:
- Upload the plugin files to
/wp-content/plugins/static-cache-wrangler/or install via Plugins > Add New. - Activate the plugin from the Plugins screen.
- Navigate to Settings → Static Cache to enable generation.
- Browse your site normally — pages are cached as they load.
- Click Download ZIP to export the complete static version.
屏幕截图:
常见问题:
Does it work with any theme or builder?
Yes — Static Cache Wrangler captures the final rendered HTML, so it works with any theme, builder, or framework (Elementor®, Divi®, Gutenberg®, etc.).
Does it use a lot of resources?
No — it's designed as a lazy loader, generating static pages only on demand with minimal memory and CPU impact.
Does it modify my database?
No — it never alters your WordPress database schema or adds tables.\ All plugin-related options, transients, and scheduled events are automatically removed upon uninstall.
Can I use the exported site on any server?
Absolutely. The output is plain HTML and assets — deploy it on any web server, CDN, or open it directly in a browser.
Does it handle dynamic content?
Dynamic features like forms, comments, or live feeds won't function in the static version, but all rendered content and assets are preserved exactly.
How do I update after making changes?
Revisit the updated pages while generation is enabled, or run wp scw process to rebuild all static content.
Can I customize the configuration?
Yes! You can customize file locations and behavior using constants in wp-config.php:
Change static files location:
define('STCW_STATIC_DIR', WP_CONTENT_DIR . '/my-static-files/');
Change assets location:
define('STCW_ASSETS_DIR', WP_CONTENT_DIR . '/my-assets/');
Disable async asset processing (process immediately):
define('STCW_ASYNC_ASSETS', false);
What if I need advanced customization?
You can use WordPress filters to customize behavior:
Exclude specific URLs from generation:
add_filter('stcw_should_generate', function($should, $url) { if (strpos($url, '/private/') !== false) { return false; } return $should; }, 10, 2);
Modify HTML before saving:
add_filter('stcw_before_save_html', function($html) { return str_replace('</body>', '<footer>Generated: ' . date('Y-m-d') . '</footer></body>', $html); });
What WordPress meta tags are removed in version 2.0.5?
Version 2.0.5 removes the following WordPress-specific meta tags from static HTML:
- RSD (Really Simple Discovery) links for XML-RPC
- Windows Live Writer manifest links
- WordPress shortlink tags
- Generator meta tags (WordPress version)
- REST API discovery links
- oEmbed discovery links
- REST API HTTP headers
data-wp-strategyattributes on script tags These tags serve no purpose in static sites and removing them improves portability and security.
How do I use the new developer hooks?
Remove additional WordPress tags:
add_action('stcw_remove_wp_head_tags', function() { remove_action('wp_head', 'your_custom_action'); });
Modify HTML before saving:
add_filter('stcw_process_static_html', function($html) { // Add custom footer, remove tracking, etc. return $html; });
See the plugin documentation for 15+ complete examples.
Do I need to regenerate my static files after upgrading?
No, but it's recommended. Existing static files will continue to work, but regenerating will give you the cleanest output with all WordPress meta tags removed:
wp scw clear
wp scw enable
Then browse your site to regenerate pages.
Can I create companion plugins for Static Cache Wrangler?
Yes! Version 2.0.5 introduces two hooks specifically designed for companion plugins:
stcw_remove_wp_head_tags- Remove additional WordPress tagsstcw_process_static_html- Modify final HTML output These enable agencies, developers, and SaaS providers to build specialized extensions without modifying core plugin code.
Will this work with my SEO plugin?
Yes! Version 2.0.5 is fully compatible with:
- Yoast SEO
- Rank Math
- All in One SEO Pack
- SEOPress
- The SEO Framework The meta tag removal only affects WordPress core tags, not SEO plugin meta tags that contain important information.
更新日志:
2.1.4
- Added: STCW_META comment injection with WordPress post data (ID, post_type, permalink, dates, template)
- Added:
scw_cache_metadatafilter for extending metadata - Enhanced: Cached HTML now includes authoritative WordPress data for headless CMS migrations
- Performance: Zero database queries, uses existing $post object (~200 bytes added to HTML)
- IMPROVED: Adds exclusions for index.php, username, and other bot cralwed URLs that were creating errant cache files.
- FIX: Version number corrected.
- NEW: Added configuration details in addition to file locations on main admin card
- NEW: Cache freshness system with automatic staleness detection
- NEW: Metadata stamps injected into all generated HTML files
- NEW: TTL-based expiry with configurable cache lifetime (default 24 hours)
- NEW: Automatic cache validation on every page request
- NEW: Plugin version tracking in metadata for upgrade detection
- NEW: Automatic sitemap generation when creating ZIP exports
- NEW: STCW_CACHE_TTL constant for configuring cache lifetime
- NEW: STCW_SITEMAP_URL constant for deployment URL configuration
- IMPROVED: Reduced unnecessary page regeneration by 90%+ when content hasn't changed
- IMPROVED: ZIP exports now always include fresh sitemap.xml automatically
- IMPROVED: Better resource utilization - only regenerates when truly needed
- IMPROVED: Smarter regeneration triggers (TTL expiry or plugin upgrade)
- IMPROVED: Enhanced logging for cache freshness decisions
- PERFORMANCE: Average 1-2ms overhead for staleness check (reads first 512 bytes only)
- PERFORMANCE: Zero regeneration cost for fresh files (immediate skip)
- PERFORMANCE: Typical 90%+ cache hit rate in production environments
- COMPATIBLE: WordPress 6.9, PHP 7.4-8.3
- FIX: Eliminated unnecessary regeneration on every page load
- FIX: Resolved race conditions when multiple requests hit same page Cache Freshness System
- Each static HTML file contains metadata:
<!-- StaticCacheWrangler: generated=2025-12-04T15:30:00Z; plugin=2.1.1 --> - On every page request, plugin checks if existing cached file is still fresh
- File is considered stale if: (1) metadata missing, (2) plugin version changed, or (3) age exceeds TTL
- Fresh files skip regeneration entirely - returning existing cached version
- Stale files trigger regeneration with fresh content and updated metadata Configuration Options:
- No need to manually run
wp scw sitemapbeforewp scw zip - Sitemap always reflects current cached content
- Uses configured STCW_SITEMAP_URL if deploying to different domain
- Seamless workflow:
wp scw zipincludes everything Performance Characteristics:
- Hours 0-23: "Cache fresh, skipping regeneration" (0ms overhead)
- Hour 24: "TTL exceeded, marking stale" → Regeneration (~50-500ms)
- After plugin upgrade: Immediate regeneration on next request
- Result: ~90% reduction in unnecessary regeneration Real-World Example from Production Logs:
- No breaking changes - fully backward compatible with 2.1.0
- Pre-2.1.1 cached files without metadata automatically regenerate once (get fresh stamps)
- After initial regeneration, normal TTL-based freshness checking applies
- No manual intervention required Why This Matters:
php
define('STCW_CACHE_TTL', 3600); // See changes within an hour
Staging (6-hour TTL):
php
define('STCW_CACHE_TTL', 21600); // Balance freshness vs. performance
Production (24-hour TTL - default):
php
// No configuration needed - 24 hours is sensible default
High-availability failover (1-week TTL):
php
define('STCW_CACHE_TTL', 604800); // Very stable, rarely regenerate
Archive/preservation (never expire):
php
define('STCW_CACHE_TTL', 0); // Only regenerate on plugin upgrades
Technical Implementation:
Staleness detection is highly optimized:
- Reads only first 512 bytes of cached file (not entire file)
- Regex pattern:
/<!--\s*StaticCacheWrangler:\s*generated=([^;]+);\s*plugin=([^\s;]+)\s*-->/ - Validates timestamp format (ISO 8601)
- Compares plugin versions (semantic versioning aware)
- Calculates age and compares against TTL
- Decision made in ~1-2ms average No external storage required:
- No database tables
- No WordPress options
- No transients
- No cron jobs
- Metadata lives in HTML files themselves (self-contained) Developer Benefits:
- Rsync to failover servers with confidence files are current
- Deploy to CDN knowing cache reflects recent WordPress state
- Monitor cache hit rates via debug logs
- Tune TTL per environment for optimal balance
- Zero-impact when cache is fresh (no database queries, no filesystem writes)
- NEW: Static sitemap generation from cached files (CLI-only)
- NEW:
wp scw sitemapcommand generates sitemap.xml and sitemap.xsl - NEW:
wp scw sitemap-deletecommand removes sitemap files - NEW: File system-based approach - scans cached files instead of database
- NEW: Automatic priority calculation based on URL depth
- NEW: Smart change frequency assignment (homepage = daily, pages = monthly)
- NEW: XSL stylesheet for browser-viewable sitemaps
- NEW: Developer hook:
stcw_sitemap_changefreqfilter for customization - IMPROVED: Sitemaps work in static exports without WordPress/PHP/database
- IMPROVED: Perfect accuracy - sitemap reflects actual exported content
- IMPROVED: Multisite compatible with isolated sitemaps per site
- PERFORMANCE: ~50-100ms scan time per 100 cached files, ~2MB memory for 1,000+ pages
- FIX: Fixed CSS mismatches resulting in admin card layout
- COMPATIBLE: WordPress 6.8.3, PHP 7.4-8.3
- NOTE: GUI interface planned for v2.2.0 (currently CLI-only) Why File System-Based? Traditional WordPress sitemap plugins (Yoast SEO, Rank Math) query the database dynamically. This works great for live sites, but fails for static exports because there's no PHP or database available. Static Cache Wrangler scans your actual cached index.html files to build the sitemap, ensuring perfect accuracy and true portability.
- Generates sitemaps.org compliant XML sitemap
- Creates XSL stylesheet for browser viewing
- Calculates priorities automatically (homepage = 1.0, deeper pages = 0.4)
- Assigns smart change frequencies based on URL patterns
- Includes last modification times from file metadata
- Multisite compatible with isolated sitemaps per site
- Fast performance: ~50-100ms per 100 cached files New WP-CLI Commands
-
wp scw sitemap- Generate sitemap from cached files wp scw sitemap-delete- Remove sitemap files Typical Workflow
wp scw enable # Enable generation
wp scw process # Process assets
wp scw sitemap # Generate sitemap (NEW!)
wp scw zip # Export with sitemap included
View your sitemap at https://your-site.com/sitemap.xml - the XSL stylesheet transforms it into a readable HTML table.
Technical Implementation
- New STCW_Sitemap_Generator class scans cached directory recursively
- Uses WordPress Filesystem API for all file operations
- Proper output escaping and sanitization throughout
- Developer filter hook for customization
- No database queries - pure file system operations
- GUI interface planned for version 2.2.0
- Major Compatibility Enhancement Release
- Version 2.0.7 delivers extensive improvements to Kadence Blocks support and significantly enhances compatibility with all Gutenberg block plugins that rely on dynamically printed JavaScript and CSS.
-
Ensures accurate static exports by capturing all front-end assets output by WordPress during rendering—including assets printed via
wp_print_scripts()andwp_print_footer_scripts()—preserving full block interactivity outside of WordPress. Compatibility Improvements - Full Kadence Blocks compatibility – Global front-end scripts and styles are now correctly captured, enabling complete functionality for JS-dependent components (accordions, buttons, icons, Lottie animations, progress bars, etc.).
- Enhanced Gutenberg block suite support – Reliable detection and export of dynamic assets from Spectra, Stackable, GenerateBlocks, CoBlocks, Otter, and other major block libraries.
- Improved dynamic script capture logic – Scripts enqueued conditionally based on block presence are now collected earlier, preventing missing-asset issues.
- Better preservation of interactive behavior – Tooltips, animations, scroll effects, responsive scripting, and block initialization logic now export more consistently.
- Resolved rare blank-page rendering issues caused by timing conflicts in WordPress’s script-printing lifecycle. Technical Enhancements
- Implemented an early script-queue flush to capture output from:
wp_print_head_scripts()wp_print_scripts()wp_print_footer_scripts()- Captured script output is now injected into the main buffer before asset parsing, ensuring regex scanners detect all JS/CSS printed during rendering.
- Improved isolation of script-capture routines from theme templates to avoid lifecycle interference.
- Better support for plugins that enqueue front-end assets only when specific blocks are present.
- Increased reliability for mixed-content layouts and advanced interactive block patterns. Compatibility
- Tested with WordPress 6.9 and PHP 8.3.6
- Fully backward compatible with 2.0.6 Migration Notes
- No configuration changes required.
- Recommended: Regenerate static exports after update to ensure full compatibility with updated asset-capture behavior.
- WordPress.org Compliance Release – “Moving Goal Post”
- Version 2.0.6 is a WordPress.org compliance update ensuring full compatibility with the latest repository validation standards introduced in 2025
- Implemented prefix standardization – all template variables, global references, and filters now use the
stcw_prefix for WordPress.NamingConventions.PrefixAllGlobals compliance - Achieved 100% pass on the updated “Check Plugin” API validation scans
- Enhanced namespace isolation and improved code safety for plugin interoperability
- Improved inline documentation for better code clarity and compliance traceability
- Developer Enhancements
- Introduced new developer hooks to support the forthcoming Static Cache Wrangler Performance Profiler MU plugin available here: Performance Profiler
- Added foundations for advanced performance profiling and benchmarking via WP‑CLI integration
- Enhanced developer experience with cleaner structure for extending cache behavior
- Improvements
- Non‑functional update focused on long‑term maintainability and ecosystem compliance
- Verified adherence to current WordPress.org repository and coding‑standards checks
- Refined internal structure to support future diagnostic and profiling modules
- Compatibility
- Tested with WordPress 6.8.3 and PHP 7.4 – 8.3
- Fully backward compatible with 2.0.5
- Migration Notes
- No functional changes to caching logic
- Recommended: Regenerate static files after update for clean metadata
- Enhanced Static HTML Output
- Implemented hybrid WordPress meta tag removal using native
remove_action()with regex safety net - Removed 7+ WordPress-specific meta tags from static output (RSD, wlwmanifest, shortlinks, generator, REST API, oEmbed discovery)
- Stripped
data-wp-strategyattributes from script tags for cleaner HTML - Reduced HTML file size by 3.1% and generation time by 2.3%
- Improved security by hiding WordPress version information from static exports
- New Developer Hooks
- Added
stcw_remove_wp_head_tagsaction hook - remove additional WordPress head tags before generation - Added
stcw_process_static_htmlfilter hook - modify HTML output before saving to file - Added
STCW_Generator::remove_wordpress_meta_tags()method for centralized tag removal - Improvements
- Enhanced code documentation with comprehensive PHPDoc comments
- Better extensibility for companion plugins and theme integration
- Follows WordPress coding standards and best practices
- More maintainable code with clear separation of concerns
- Compatibility
- Tested with WordPress 6.8.3
- Compatible with PHP 7.4, 8.0, 8.1, 8.2, 8.3
- Works with all major themes, page builders, and SEO plugins
- Migration Notes
- No breaking changes - fully backward compatible with 2.0.4
- Recommended: Clear and regenerate static files for cleanest output (
wp scw clear && wp scw enable) - Optional: Review new hooks for customization opportunities
- Major WordPress.org Compliance & Refactor Release\ This update brings the plugin fully in line with current WordPress.org Plugin Directory requirements and coding standards. Nearly every internal file, reference, and namespace was audited, renamed, or rewritten for long-term maintainability and compliance.
- Plugin slug, text domain, and directory renamed from
static-cache-generator→static-cache-wranglerto meet naming and trademark guidelines. - All file, class, and function prefixes updated from
STCG→STCWfor consistent 4-character namespace compliance. - Text domain and translation calls unified across all PHP files for proper i18n validation.
- Folder structure and includes modernized for autoloading consistency and WP.org scanning compatibility.
- Admin interface and view templates refactored for cleaner markup and translation readiness.
- CLI namespace and command base confirmed as
scw(formerlyscg) with backward compatibility removed for clarity. - All GitHub and asset references updated to reflect the new canonical project name and repository.
- Packaging and distribution scripts updated for compliance (clean
.zipexports excluding dev files). - BREAKING CHANGE: Sites upgrading from earlier builds must deactivate the old “Static Cache Generator” plugin, delete it, and install/activate “Static Cache Wrangler.” Data and generated files can be safely regenerated once activated.
- WordPress.org Compliance Update
- Changed all PHP prefixes from SCG_ to STCW_ (4+ character requirement)
- Properly enqueued all scripts and styles (removed inline code)
- Extracted CSS to admin/css/admin-style.css
- Extracted JavaScript to admin/js/admin-script.js and includes/js/auto-process.js
- WP-CLI commands unchanged for user convenience (still
wp scw) - BREAKING CHANGE: Requires clearing and regenerating static files after update
- All option names changed (scw_enabled → stcw_enabled, etc.)
- All WordPress hooks changed (scw_process_assets → stcw_process_assets, etc.)
- See full migration guide on GitHub for technical details
- Enhanced stability and performance
- Improved CLI feedback and logging
- Refined asset handling and path rewriting
- Clean uninstall now clears all options, transients, and cron events
- Minor UI and accessibility improvements
- Complete rewrite with modern coding standards
- WP_Filesystem support for all operations
- Stronger security and sanitization
- Modern admin UI with real-time asset tracking
- Full WP-CLI integration
- Fixed Plugin Check and PHPCS compliance
- Initial release