Add initial design document for WP Recache
This commit is contained in:
@@ -0,0 +1,226 @@
|
|||||||
|
# WP Recache — Open Source Performance Plugin
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Create a commercial-grade WordPress performance plugin with feature parity to WP Rocket, implemented via clean-room methodology. The plugin will be open source (GPL-2.0+) and provide page caching, file optimization, and image optimization.
|
||||||
|
|
||||||
|
## Clean-Room Methodology
|
||||||
|
|
||||||
|
### Rules
|
||||||
|
|
||||||
|
1. **No code reuse.** Never copy, paste, or adapt any PHP/JS/CSS from WP Rocket.
|
||||||
|
2. **Feature specs only.** Document what WP Rocket does from a *user perspective* (UI behavior, options, output), not how it's implemented.
|
||||||
|
3. **Independent implementation.** All code written from scratch using WordPress APIs and standard libraries.
|
||||||
|
4. **Documentation trail.** Keep records of the specification process to prove independent development.
|
||||||
|
|
||||||
|
### What We Study (User Perspective)
|
||||||
|
|
||||||
|
- WP Rocket admin UI: what settings exist, what they control
|
||||||
|
- Frontend output: what HTML/JS/CSS changes appear after activation
|
||||||
|
- Behavior: when cache clears, what gets optimized, what's excluded by default
|
||||||
|
- Performance: what metrics improve
|
||||||
|
|
||||||
|
### What We Ignore
|
||||||
|
|
||||||
|
- PHP source code structure
|
||||||
|
- Internal class/function naming
|
||||||
|
- Specific implementation patterns
|
||||||
|
- Hook naming conventions
|
||||||
|
|
||||||
|
## Feature Specifications
|
||||||
|
|
||||||
|
### 1. Page Cache
|
||||||
|
|
||||||
|
**User-facing behavior:**
|
||||||
|
- On first anonymous visit, generates static HTML file
|
||||||
|
- Subsequent anonymous visits serve the static file directly
|
||||||
|
- Cache auto-purges when content is published/updated
|
||||||
|
- Manual purge available from admin bar and settings page
|
||||||
|
- Excludes logged-in users, cart/checkout pages, specific URLs
|
||||||
|
- Separate cache for mobile devices (optional)
|
||||||
|
- Preload/crawl sitemap to warm cache
|
||||||
|
|
||||||
|
**Technical approach (independent implementation):**
|
||||||
|
- Use WordPress `advanced-cache.php` drop-in
|
||||||
|
- Output buffering via `ob_start()` / `ob_get_contents()` / `ob_end_flush()`
|
||||||
|
- Cache files stored in `wp-content/cache/`
|
||||||
|
- Serve cached files via direct file read before WordPress loads
|
||||||
|
- Use WordPress rewrite rules for cache detection
|
||||||
|
|
||||||
|
### 2. File Optimization — CSS
|
||||||
|
|
||||||
|
**User-facing behavior:**
|
||||||
|
- Minify CSS files (remove whitespace, comments)
|
||||||
|
- Combine CSS files into fewer requests
|
||||||
|
- Defer non-critical CSS loading
|
||||||
|
- Remove unused CSS (RUCSS — Remove Unused CSS)
|
||||||
|
- Inline critical CSS for above-the-fold content
|
||||||
|
- Async CSS loading
|
||||||
|
|
||||||
|
**Technical approach:**
|
||||||
|
- Use CSS minification library (e.g., `natanielrodman/css-minify` or similar)
|
||||||
|
- Parse CSS to identify critical path selectors
|
||||||
|
- Output buffering to detect and modify `<link>` tags
|
||||||
|
- Generate critical CSS via headless browser or parser
|
||||||
|
|
||||||
|
### 3. File Optimization — JavaScript
|
||||||
|
|
||||||
|
**User-facing behavior:**
|
||||||
|
- Minify JavaScript files
|
||||||
|
- Combine JavaScript files
|
||||||
|
- Defer JavaScript loading (load after HTML parsed)
|
||||||
|
- Delay JavaScript execution (load on user interaction)
|
||||||
|
- Remove jQuery Migrate
|
||||||
|
- Delay inline scripts
|
||||||
|
|
||||||
|
**Technical approach:**
|
||||||
|
- Use JavaScript minification (e.g., `tedivm/jshrink` or similar)
|
||||||
|
- Output buffering to modify `<script>` tags
|
||||||
|
- Add `defer` or `async` attributes
|
||||||
|
- Wrap scripts in event listeners for delay functionality
|
||||||
|
|
||||||
|
### 4. Image Optimization
|
||||||
|
|
||||||
|
**User-facing behavior:**
|
||||||
|
- Lazy load images (load when entering viewport)
|
||||||
|
- Convert images to WebP/AVIF format
|
||||||
|
- Optimize image compression
|
||||||
|
- Add missing width/height attributes (CLS prevention)
|
||||||
|
- Placeholder images while loading
|
||||||
|
|
||||||
|
**Technical approach:**
|
||||||
|
- Use `loading="lazy"` attribute (native lazy loading)
|
||||||
|
- Use WordPress `wp_image_editor` APIs for format conversion
|
||||||
|
- Use Imagick/GD for compression
|
||||||
|
- Generate WebP/AVIF variants on upload
|
||||||
|
|
||||||
|
### 5. Additional Features
|
||||||
|
|
||||||
|
**Critical CSS:**
|
||||||
|
- Generate critical CSS for above-the-fold content
|
||||||
|
- Inline critical CSS, defer full stylesheet
|
||||||
|
- Per-page critical CSS generation
|
||||||
|
|
||||||
|
**Preload:**
|
||||||
|
- Preload key requests (fonts, critical resources)
|
||||||
|
- DNS prefetch for external domains
|
||||||
|
- Prefetch for likely next pages
|
||||||
|
|
||||||
|
**Database Optimization:**
|
||||||
|
- Clean post revisions
|
||||||
|
- Clean auto-drafts
|
||||||
|
- Clean trashed posts
|
||||||
|
- Optimize database tables
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
### Plugin Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
wp-recache/
|
||||||
|
├── wp-recache.php # Main plugin file
|
||||||
|
├── uninstall.php # Clean uninstall
|
||||||
|
├── composer.json # Dependencies
|
||||||
|
├── readme.txt # WordPress.org readme
|
||||||
|
├── assets/
|
||||||
|
│ ├── css/
|
||||||
|
│ │ └── admin.css # Admin UI styles
|
||||||
|
│ └── js/
|
||||||
|
│ └── admin.js # Admin UI scripts
|
||||||
|
├── includes/
|
||||||
|
│ ├── Activator.php # Plugin activation
|
||||||
|
│ ├── Deactivator.php # Plugin deactivation
|
||||||
|
│ ├── Plugin.php # Main plugin class
|
||||||
|
│ ├── Admin/
|
||||||
|
│ │ ├── Admin.php # Admin functionality
|
||||||
|
│ │ ├── Settings.php # Settings page
|
||||||
|
│ │ └── Assets.php # Admin assets
|
||||||
|
│ ├── Cache/
|
||||||
|
│ │ ├── WPCache.php # Core page cache
|
||||||
|
│ │ ├── Purge.php # Cache purge logic
|
||||||
|
│ │ └── Preloader.php # Cache preloading
|
||||||
|
│ ├── Optimization/
|
||||||
|
│ │ ├── CSS/
|
||||||
|
│ │ │ ├── Minify.php # CSS minification
|
||||||
|
│ │ │ ├── Combine.php # CSS combination
|
||||||
|
│ │ │ └── CriticalCSS.php # Critical CSS generation
|
||||||
|
│ │ ├── JS/
|
||||||
|
│ │ │ ├── Minify.php # JS minification
|
||||||
|
│ │ │ ├── Combine.php # JS combination
|
||||||
|
│ │ │ └── Defer.php # JS defer/delay
|
||||||
|
│ │ └── RemoveUnusedCSS.php # RUCSS
|
||||||
|
│ ├── Media/
|
||||||
|
│ │ ├── Lazyload.php # Image lazy loading
|
||||||
|
│ │ ├── ImageFormat.php # WebP/AVIF conversion
|
||||||
|
│ │ └── ImageOptimize.php # Image compression
|
||||||
|
│ ├── Database/
|
||||||
|
│ │ └── Optimizer.php # Database cleanup
|
||||||
|
│ └── Common/
|
||||||
|
│ ├── FileSystem.php # File system utilities
|
||||||
|
│ ├──钩子/钩子.php # Hook utilities
|
||||||
|
│ └── HTTP.php # HTTP utilities
|
||||||
|
├── views/
|
||||||
|
│ ├── admin-settings.php # Settings page template
|
||||||
|
│ └── admin-bar.php # Admin bar menu
|
||||||
|
└── languages/
|
||||||
|
└── wp-recache.pot # Translation template
|
||||||
|
```
|
||||||
|
|
||||||
|
### Key Design Decisions
|
||||||
|
|
||||||
|
1. **No vendor dependencies for core features.** Use WordPress built-in APIs wherever possible.
|
||||||
|
2. **Modular architecture.** Each feature (cache, CSS, JS, images) is independent and can be disabled.
|
||||||
|
3. **WordPress standards.** Follow WordPress coding standards and hook system.
|
||||||
|
4. **Performance first.** Minimal overhead, no unnecessary database queries.
|
||||||
|
|
||||||
|
## Implementation Strategy
|
||||||
|
|
||||||
|
### Phase 1: Core Page Cache
|
||||||
|
- Implement `advanced-cache.php` drop-in
|
||||||
|
- Output buffering for HTML generation
|
||||||
|
- Cache file management (create, serve, purge)
|
||||||
|
- Admin settings page (basic)
|
||||||
|
- Admin bar purge button
|
||||||
|
|
||||||
|
### Phase 2: File Optimization
|
||||||
|
- CSS minification
|
||||||
|
- JS minification
|
||||||
|
- CSS/JS combination
|
||||||
|
- Defer/delay scripts
|
||||||
|
- Critical CSS generation
|
||||||
|
|
||||||
|
### Phase 3: Image Optimization
|
||||||
|
- Lazy loading
|
||||||
|
- WebP/AVIF conversion
|
||||||
|
- Image compression
|
||||||
|
- CLS prevention (width/height)
|
||||||
|
|
||||||
|
### Phase 4: Advanced Features
|
||||||
|
- Remove unused CSS
|
||||||
|
- Database optimization
|
||||||
|
- Preloading
|
||||||
|
- CDN support
|
||||||
|
|
||||||
|
## Legal Considerations
|
||||||
|
|
||||||
|
1. **Document everything.** Keep records of the specification process.
|
||||||
|
2. **Never access WP Rocket source** while implementing.
|
||||||
|
3. **Use different naming.** Don't use "rocket" prefixes or similar naming.
|
||||||
|
4. **Independent architecture.** Design your own class structure.
|
||||||
|
5. **Different defaults.** Choose different default settings where possible.
|
||||||
|
|
||||||
|
## Open Source Strategy
|
||||||
|
|
||||||
|
1. **License:** GPL-2.0-or-later (same as WordPress)
|
||||||
|
2. **Repository:** GitHub with public access
|
||||||
|
3. **WordPress.org:** Submit to plugin directory
|
||||||
|
4. **Community:** Accept contributions, maintain active development
|
||||||
|
5. **Commercial model:** Open core with premium features or SaaS add-ons
|
||||||
|
|
||||||
|
## Success Criteria
|
||||||
|
|
||||||
|
1. Feature parity with WP Rocket for page cache, file optimization, image optimization
|
||||||
|
2. No code overlap (verified by code review)
|
||||||
|
3. Performance benchmarks comparable to or better than WP Rocket
|
||||||
|
4. Clean, maintainable code following WordPress standards
|
||||||
|
5. Active open source community
|
||||||
Reference in New Issue
Block a user