542 lines
17 KiB
Markdown
542 lines
17 KiB
Markdown
# Technical Specification: Custom Caching & Image Optimization Plugins
|
||
|
||
## Document Purpose
|
||
This spec defines the exact architecture, API, and integration points for the two replacement plugins:
|
||
1. `help4bis-performance-cache` — HTTP caching + database cleanup
|
||
2. `help4bis-image-optimizer` — Image compression, WebP, lazy load, responsive images
|
||
|
||
---
|
||
|
||
## Plugin 1: help4bis-performance-cache
|
||
|
||
### Scope
|
||
- HTTP cache headers (browser-level, not page HTML caching)
|
||
- Database cleanup (revisions, orphaned meta, expired transients)
|
||
- Cache invalidation hooks
|
||
- Elementor CSS cache integration
|
||
- Simple admin UI (settings, clear button)
|
||
|
||
### NOT in scope
|
||
- Page HTML caching (complex, low ROI given Elementor sites are mostly dynamic)
|
||
- Redis/memcached integration (single-server, not needed)
|
||
- CloudFlare integration
|
||
- Lazy loading (handled by image optimizer)
|
||
|
||
### File Structure
|
||
```
|
||
help4bis-performance-cache/
|
||
├── help4bis-performance-cache.php # Plugin header + activation hooks
|
||
├── admin/
|
||
│ ├── class-settings-page.php # WP admin page
|
||
│ ├── class-cache-manager.php # Clear cache handler
|
||
│ └── partials/
|
||
│ └── settings.html # Settings form
|
||
├── includes/
|
||
│ ├── class-cache.php # HTTP header logic
|
||
│ ├── class-exclusions.php # Minify exclusion manager
|
||
│ ├── class-elementor-integration.php # Elementor cache invalidation
|
||
│ └── class-database-cleanup.php # Revision/transient cleanup
|
||
├── hooks/
|
||
│ ├── class-invalidation.php # Post save/delete hooks
|
||
│ └── class-scheduled-cleanup.php # Cron jobs
|
||
└── tests/
|
||
├── test-cache.php
|
||
├── test-invalidation.php
|
||
└── test-elementor-integration.php
|
||
```
|
||
|
||
### Configuration (in wp_options)
|
||
```php
|
||
// Single option containing all settings
|
||
'h4b_cache_settings' => array(
|
||
'enabled' => true,
|
||
'browser_cache_css' => '1y', // CSS browser cache
|
||
'browser_cache_js' => '1y', // JS browser cache
|
||
'browser_cache_images' => '1y', // Images browser cache
|
||
'browser_cache_media' => '1y', // Media files browser cache
|
||
'browser_cache_html' => '0', // HTML (always no-cache for dynamic)
|
||
'auto_cleanup' => true,
|
||
'cleanup_frequency' => 'weekly', // weekly, biweekly, monthly
|
||
'cleanup_day' => 'friday',
|
||
'cleanup_time' => '03:00', // 3 AM AEST
|
||
'cleanup_revisions_keep' => 30, // Days of revisions to keep
|
||
'cleanup_transient_expired' => true, // Delete expired transients
|
||
'cleanup_orphaned_meta' => true, // Delete orphaned postmeta
|
||
'exclude_scripts' => array( // Scripts that skip minify (if added later)
|
||
'jquery',
|
||
'elementor-pro-app',
|
||
// ... (copy from Hummingbird config)
|
||
),
|
||
'exclude_styles' => array(), // Styles that skip minify
|
||
);
|
||
```
|
||
|
||
### HTTP Headers Set by Plugin
|
||
|
||
On all requests, set these headers:
|
||
|
||
```
|
||
Cache-Control: public, max-age=31536000 (for .css, .js, .jpg, .png, .gif, .woff, .woff2)
|
||
Cache-Control: no-cache, no-store, must-revalidate (for .html, /wp-admin/, /wp-json/)
|
||
Expires: <1 year from now>
|
||
Vary: Accept-Encoding
|
||
```
|
||
|
||
For static assets, also set:
|
||
```
|
||
ETag: "<hash-of-file>"
|
||
Last-Modified: <file-mtime>
|
||
```
|
||
|
||
### Elementor Integration
|
||
|
||
**Problem:** Elementor caches compiled CSS in `_elementor_css` and posts with CSS file at:
|
||
```
|
||
/wp-content/uploads/elementor/css/post-{POST_ID}.css
|
||
```
|
||
|
||
**Solution:** Hook into Elementor's save action and clear our cache:
|
||
|
||
```php
|
||
add_action('elementor/editor/before_save', function($post_id) {
|
||
// Clear Elementor's CSS cache for this post
|
||
delete_post_meta($post_id, '_elementor_css');
|
||
delete_post_meta($post_id, '_elementor_page_assets');
|
||
|
||
// Also clear the CSS file
|
||
$css_file = WP_CONTENT_DIR . "/uploads/elementor/css/post-{$post_id}.css";
|
||
if (file_exists($css_file)) {
|
||
unlink($css_file);
|
||
}
|
||
});
|
||
```
|
||
|
||
### Admin UI
|
||
|
||
Settings page at: **Dashboard → Performance → Cache**
|
||
|
||
Fields:
|
||
- [ ] Enable caching
|
||
- Browser cache duration (select: 6m / 1y / custom)
|
||
- [x] Auto-cleanup enabled
|
||
- Cleanup frequency (select: weekly / biweekly / monthly)
|
||
- Cleanup day + time (select day, input time)
|
||
- [x] Delete post revisions older than X days (input: 30)
|
||
- [x] Delete expired transients
|
||
- [x] Delete orphaned postmeta
|
||
- Button: "Clear cache now"
|
||
|
||
Status display:
|
||
- Last cache clear: [timestamp]
|
||
- Last cleanup run: [timestamp]
|
||
- Cache size on disk: [MB]
|
||
|
||
### Activation Checklist
|
||
|
||
On plugin activation:
|
||
- [ ] Check WordPress version >= 5.0
|
||
- [ ] Check PHP >= 7.4
|
||
- [ ] Create default settings in wp_options
|
||
- [ ] Schedule first cleanup cron job
|
||
- [ ] Log activation in error_log
|
||
|
||
On plugin deactivation:
|
||
- [ ] Unschedule cleanup cron job
|
||
- [ ] Do NOT delete settings (user might reactivate)
|
||
- [ ] Log deactivation
|
||
|
||
---
|
||
|
||
## Plugin 2: help4bis-image-optimizer
|
||
|
||
### Scope
|
||
- Lossy compression (JPEG quality adjustment)
|
||
- WebP generation on upload
|
||
- Lazy load injection (native HTML5)
|
||
- Responsive image srcset generation
|
||
- Format fallback (WebP with JPEG fallback)
|
||
- Bulk optimization for existing images
|
||
- Elementor integration (image URL rewriting)
|
||
|
||
### NOT in scope
|
||
- CDN delivery (local only)
|
||
- Advanced ML-based format detection (use simple rules: JPEG→WebP, PNG→WebP if large)
|
||
- AVIF format (too new, poor browser support)
|
||
- Responsive image srcset for post_content HTML (only for featured images + gallery)
|
||
|
||
### File Structure
|
||
```
|
||
help4bis-image-optimizer/
|
||
├── help4bis-image-optimizer.php
|
||
├── admin/
|
||
│ ├── class-settings-page.php
|
||
│ ├── class-bulk-optimizer.php # Background processing existing images
|
||
│ ├── class-status-dashboard.php # Stats: images optimized, space saved
|
||
│ └── partials/
|
||
│ ├── settings.html
|
||
│ ├── bulk-optimizer.html
|
||
│ └── dashboard.html
|
||
├── includes/
|
||
│ ├── class-upload-handler.php # Hook wp_handle_upload
|
||
│ ├── class-compressor.php # ImageMagick wrapper
|
||
│ ├── class-webp-generator.php # WebP conversion
|
||
│ ├── class-responsive-images.php # Srcset generation
|
||
│ ├── class-lazy-load.php # lazy load injection
|
||
│ ├── class-elementor-integration.php # Override Elementor image URLs
|
||
│ ├── class-image-metadata.php # Store optimization status in postmeta
|
||
│ └── class-fallback-handler.php # Graceful degradation if ImageMagick fails
|
||
├── hooks/
|
||
│ ├── class-filters.php # img tag filters
|
||
│ └── class-actions.php # Upload actions
|
||
├── vendor/
|
||
│ └── image-processor.php # ImageMagick abstraction layer
|
||
└── tests/
|
||
├── test-compression.php
|
||
├── test-webp-generation.php
|
||
├── test-lazy-load.php
|
||
└── test-elementor-integration.php
|
||
```
|
||
|
||
### Configuration (in wp_options)
|
||
```php
|
||
'h4b_image_optimizer_settings' => array(
|
||
'enabled' => true,
|
||
'compression_enabled' => true,
|
||
'jpeg_quality' => 78, // 70-85, balance quality/size
|
||
'png_aggressive' => false, // Use pngquant if available
|
||
'webp_enabled' => true,
|
||
'webp_quality' => 78, // Same as JPEG
|
||
'lazy_load_enabled' => true,
|
||
'lazy_load_threshold' => 0, // 0 = all images, 1000 = skip first 1000px
|
||
'responsive_srcset' => true, // Generate srcset for featured images
|
||
'backup_originals' => true, // Keep backup of pre-optimization images
|
||
'bulk_optimize_batch_size' => 5, // Process 5 images per cron run (don't overload)
|
||
'preserve_exif' => false, // Strip metadata
|
||
'skip_images_smaller_than' => 50000, // Don't compress tiny images (50KB)
|
||
'imagemagick_available' => true, // Auto-detected on activation
|
||
'fallback_mode' => 'preserve', // preserve=upload original, skip=don't upload
|
||
);
|
||
```
|
||
|
||
### HTTP Upload Handler
|
||
|
||
**Hook:** `wp_handle_upload_prefilter` / `wp_handle_upload`
|
||
|
||
**Process:**
|
||
1. User uploads image via WordPress media uploader
|
||
2. WordPress saves the file (e.g., `/uploads/2026/05/image.jpg`)
|
||
3. Our plugin intercepts:
|
||
```php
|
||
add_filter('wp_handle_upload', function($upload) {
|
||
if (is_image($upload['file'])) {
|
||
compress_image($upload['file']);
|
||
generate_webp($upload['file']);
|
||
update_image_metadata($upload['file']);
|
||
}
|
||
return $upload;
|
||
});
|
||
```
|
||
4. Compression + WebP generation (1-5 seconds per image)
|
||
5. Store metadata: `_h4b_optimized = true, _h4b_webp_path = ...`
|
||
|
||
### Image Compression Logic
|
||
|
||
```php
|
||
class Compressor {
|
||
public function compress_jpeg($src, $quality = 78) {
|
||
$cmd = sprintf(
|
||
"convert '%s' -quality %d -strip '%s'",
|
||
escapeshellarg($src),
|
||
intval($quality),
|
||
escapeshellarg($src)
|
||
);
|
||
exec($cmd, $output, $ret);
|
||
return $ret === 0; // 0 = success
|
||
}
|
||
|
||
public function compress_png($src, $aggressive = false) {
|
||
if ($aggressive && command_exists('pngquant')) {
|
||
// Reduce palette to 256 colors
|
||
$cmd = sprintf("pngquant 256 --strip '%s' -o '%s'",
|
||
escapeshellarg($src), escapeshellarg($src));
|
||
exec($cmd);
|
||
} else {
|
||
// Just strip metadata
|
||
$cmd = sprintf("convert '%s' -strip '%s'",
|
||
escapeshellarg($src), escapeshellarg($src));
|
||
exec($cmd);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### WebP Generation
|
||
|
||
```php
|
||
class WebpGenerator {
|
||
public function generate_webp($src) {
|
||
$webp_path = preg_replace('/\.(jpg|jpeg|png)$/i', '.webp', $src);
|
||
|
||
if (file_exists($src)) {
|
||
// Use cwebp if available (faster), else ImageMagick
|
||
if (command_exists('cwebp')) {
|
||
$cmd = sprintf("cwebp -q 78 '%s' -o '%s'",
|
||
escapeshellarg($src), escapeshellarg($webp_path));
|
||
} else {
|
||
$cmd = sprintf("convert '%s' -define webp:method=6 '%s'",
|
||
escapeshellarg($src), escapeshellarg($webp_path));
|
||
}
|
||
|
||
exec($cmd, $output, $ret);
|
||
|
||
// Check output size; if WebP isn't smaller, delete it
|
||
if ($ret === 0 && filesize($webp_path) < filesize($src)) {
|
||
return true; // WebP created and is smaller
|
||
} else {
|
||
@unlink($webp_path);
|
||
return false; // WebP not beneficial, stick with original
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Lazy Load Injection
|
||
|
||
**HTML before:**
|
||
```html
|
||
<img src="/uploads/2026/05/image.jpg" alt="..." class="wp-image-123" />
|
||
```
|
||
|
||
**HTML after (our plugin):**
|
||
```html
|
||
<img
|
||
src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg'%3E%3C/svg%3E"
|
||
data-src="/uploads/2026/05/image.jpg"
|
||
alt="..."
|
||
class="wp-image-123"
|
||
loading="lazy"
|
||
width="800"
|
||
height="600"
|
||
/>
|
||
```
|
||
|
||
**Implementation:**
|
||
```php
|
||
add_filter('the_content', function($content) {
|
||
return preg_replace_callback(
|
||
'/<img\s+([^>]*?)src="([^"]*?)"([^>]*)>/i',
|
||
function($matches) {
|
||
$attrs = $matches[1] . $matches[3];
|
||
$src = $matches[2];
|
||
|
||
// Don't lazy-load if already has loading="lazy"
|
||
if (strpos($attrs, 'loading=') !== false) {
|
||
return $matches[0];
|
||
}
|
||
|
||
// Create placeholder SVG (1x1 transparent)
|
||
$placeholder = "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg'%3E%3C/svg%3E";
|
||
|
||
return sprintf(
|
||
'<img %s src="%s" data-src="%s" loading="lazy" />',
|
||
$attrs,
|
||
$placeholder,
|
||
esc_url($src)
|
||
);
|
||
},
|
||
$content
|
||
);
|
||
});
|
||
```
|
||
|
||
**Browser native support:** `loading="lazy"` is supported in all modern browsers (2024+). Old browsers ignore the attribute and load normally.
|
||
|
||
### Responsive Images (Srcset)
|
||
|
||
For featured images, generate multiple sizes:
|
||
|
||
```php
|
||
// On upload, if it's a featured image, create these sizes:
|
||
// - thumbnail: 150×150
|
||
// - medium: 300×300
|
||
// - medium_large: 768×768
|
||
// - large: 1024×1024
|
||
// - full: original size
|
||
|
||
// Then inject into featured image markup:
|
||
$sizes_srcset = array();
|
||
foreach ([150, 300, 768, 1024, 0] as $size) {
|
||
$src = wp_get_attachment_image_src($attach_id, $size);
|
||
if ($src) {
|
||
$sizes_srcset[] = sprintf("%s %dw", $src[0], $src[1]);
|
||
}
|
||
}
|
||
|
||
// Result:
|
||
<img
|
||
src="..."
|
||
srcset="image-150.jpg 150w, image-300.jpg 300w, image-768.jpg 768w, ..."
|
||
sizes="(max-width: 600px) 100vw, (max-width: 1200px) 50vw, 33vw"
|
||
alt="..."
|
||
/>
|
||
```
|
||
|
||
### Elementor Integration
|
||
|
||
**Problem:** Elementor stores image URLs in `_elementor_data` JSON. When we show optimized images, Elementor's cache might be stale.
|
||
|
||
**Solution:** On image optimization, invalidate Elementor's post assets:
|
||
|
||
```php
|
||
add_action('h4b_image_optimized', function($attachment_id) {
|
||
// Find all Elementor posts that reference this image
|
||
$posts = get_posts(array(
|
||
'meta_query' => array(
|
||
array(
|
||
'key' => '_elementor_data',
|
||
'compare' => 'LIKE',
|
||
'value' => $attachment_id,
|
||
),
|
||
),
|
||
));
|
||
|
||
foreach ($posts as $post) {
|
||
// Clear Elementor's CSS and asset cache for this post
|
||
delete_post_meta($post->ID, '_elementor_page_assets');
|
||
delete_post_meta($post->ID, '_elementor_css');
|
||
}
|
||
});
|
||
```
|
||
|
||
Also, hook into Elementor's image rendering:
|
||
|
||
```php
|
||
add_filter('elementor/rendering/render_element/final_html', function($html) {
|
||
// Inject lazy load into all img tags within Elementor rendered output
|
||
return preg_replace_callback('/<img\s+([^>]*)>/i', function($matches) {
|
||
// Add lazy load if not present
|
||
if (strpos($matches[1], 'loading=') === false) {
|
||
return '<img ' . $matches[1] . ' loading="lazy" />';
|
||
}
|
||
return $matches[0];
|
||
}, $html);
|
||
});
|
||
```
|
||
|
||
### Bulk Optimizer for Existing Images
|
||
|
||
**Process:**
|
||
1. User clicks "Optimize all existing images" in admin
|
||
2. Plugin creates background cron task
|
||
3. Each cron run processes 5 images (configurable batch size)
|
||
4. Progress bar in admin: "Optimized 245 of 2,150 images (11%)"
|
||
5. Takes 5-10 minutes for 2000 images (spread across multiple cron runs)
|
||
|
||
**Implementation:**
|
||
```php
|
||
// On bulk optimizer start:
|
||
update_option('h4b_bulk_optimize_status', array(
|
||
'total' => $total_attachments,
|
||
'processed' => 0,
|
||
'started' => current_time('mysql'),
|
||
'batch_size' => 5,
|
||
));
|
||
|
||
// Cron job every 2 minutes:
|
||
wp_schedule_event(current_time('timestamp'), '2min', 'h4b_bulk_optimize_cron');
|
||
|
||
add_action('h4b_bulk_optimize_cron', function() {
|
||
$status = get_option('h4b_bulk_optimize_status');
|
||
if (!$status || $status['processed'] >= $status['total']) {
|
||
wp_clear_scheduled_hook('h4b_bulk_optimize_cron');
|
||
return;
|
||
}
|
||
|
||
// Get next batch
|
||
$batch = new WP_Query(array(
|
||
'post_type' => 'attachment',
|
||
'post_mime_type' => 'image',
|
||
'posts_per_page' => $status['batch_size'],
|
||
'offset' => $status['processed'],
|
||
));
|
||
|
||
foreach ($batch->posts as $attachment) {
|
||
compress_image($attachment->ID);
|
||
generate_webp($attachment->ID);
|
||
}
|
||
|
||
$status['processed'] += count($batch->posts);
|
||
update_option('h4b_bulk_optimize_status', $status);
|
||
});
|
||
```
|
||
|
||
### Fallback & Error Handling
|
||
|
||
**If ImageMagick is not available:**
|
||
|
||
On activation, check:
|
||
```php
|
||
register_activation_hook(__FILE__, function() {
|
||
$has_convert = shell_exec('which convert 2>/dev/null');
|
||
$has_magick = shell_exec('which magick 2>/dev/null');
|
||
$has_cwebp = shell_exec('which cwebp 2>/dev/null');
|
||
|
||
if (!$has_convert && !$has_magick) {
|
||
// ImageMagick not installed
|
||
update_option('h4b_imagemagick_available', false);
|
||
add_action('admin_notices', function() {
|
||
echo '<div class="notice notice-error">';
|
||
echo '<p><strong>Image Optimizer:</strong> ImageMagick not found. Install via: apt install imagemagick</p>';
|
||
echo '</div>';
|
||
});
|
||
}
|
||
});
|
||
```
|
||
|
||
**Graceful fallback:** If compression fails, upload the original image uncompressed. Log the error, but don't break the upload.
|
||
|
||
---
|
||
|
||
## Testing Strategy
|
||
|
||
### Plugin 1: Cache
|
||
- [ ] HTTP headers are set correctly on requests for .css, .js, .jpg
|
||
- [ ] Elementor CSS cache is cleared when post is saved
|
||
- [ ] Database cleanup runs on schedule and removes revisions
|
||
- [ ] Orphaned postmeta is cleaned up
|
||
- [ ] Cache clear button works
|
||
|
||
### Plugin 2: Image Optimizer
|
||
- [ ] JPEG images are compressed to target quality
|
||
- [ ] WebP is generated and is smaller than JPEG
|
||
- [ ] Lazy load tag is injected
|
||
- [ ] Elementor image URLs are rewritten
|
||
- [ ] Bulk optimizer progresses correctly
|
||
- [ ] If ImageMagick unavailable, original image is uploaded (fallback)
|
||
- [ ] Featured image srcset is generated correctly
|
||
|
||
### Integration Testing
|
||
- [ ] Disable Hummingbird, enable cache plugin → no speed regression
|
||
- [ ] Disable Smush, enable image optimizer → speed improvement or equal
|
||
- [ ] All Elementor pages still display correctly
|
||
- [ ] All image galleries still work
|
||
|
||
---
|
||
|
||
## Deployment Checklist
|
||
|
||
- [ ] Code reviewed
|
||
- [ ] All tests passing
|
||
- [ ] Ruff linter clean
|
||
- [ ] Backup of production database taken
|
||
- [ ] Staging environment mirrors production
|
||
- [ ] ImageMagick + cwebp verified installed
|
||
- [ ] Hummingbird deactivated, cache plugin activated (1 test site)
|
||
- [ ] Monitor for 72 hours
|
||
- [ ] Smush deactivated, image optimizer activated (1 test site)
|
||
- [ ] Monitor for 72 hours
|
||
- [ ] Roll out to remaining sites
|
||
- [ ] WPMU Dev subscription cancelled
|
||
|