https://github.com/gbsimon/keycdn-webp-optimizer
Modern WebP delivery for WordPress media libraries offloaded via WP Offload Media + KeyCDN.
https://github.com/gbsimon/keycdn-webp-optimizer
cdn image-processing keycdn optimization performance webp wp-offload-media
Last synced: 4 months ago
JSON representation
Modern WebP delivery for WordPress media libraries offloaded via WP Offload Media + KeyCDN.
- Host: GitHub
- URL: https://github.com/gbsimon/keycdn-webp-optimizer
- Owner: gbsimon
- Created: 2025-11-11T18:03:13.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-11-11T18:53:32.000Z (7 months ago)
- Last Synced: 2025-11-11T20:21:09.466Z (7 months ago)
- Topics: cdn, image-processing, keycdn, optimization, performance, webp, wp-offload-media
- Language: PHP
- Homepage: https://tomtom.design
- Size: 31.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
README
# tom & tom Image Optimization for CDN
> Modern WebP delivery for WordPress media libraries offloaded via WP Offload Media + KeyCDN.
| Meta | Value |
| ---------------- | --------------------------------------------------------------------- |
| **Contributors** | `tomtomdesign` |
| **Tags** | webp, optimization, keycdn, cdn, images |
| **Requires** | WordPress 5.0+ · PHP 7.4+ |
| **Tested up to** | WordPress 6.8 |
| **Stable tag** | 1.0.4 |
| **License** | GPLv2 or later ([license](https://www.gnu.org/licenses/gpl-2.0.html)) |
Automatically converts WordPress images to WebP using picture elements. Works with WP Offload Media and KeyCDN for on-the-fly conversion.
---
## Table of Contents
- [Highlights](#highlights)
- [Quick Start](#quick-start)
- [Feature Spotlight](#feature-spotlight)
- [Example Output](#example-output)
- [Workflow](#workflow)
- [Installation](#installation)
- [Prerequisites](#prerequisites)
- [FAQ](#faq)
- [Changelog](#changelog)
- [Upgrade Notice](#upgrade-notice)
- [Technical Details](#technical-details)
- [Support](#support)
- [Privacy](#privacy)
---
## Highlights
- **Edge-Powered WebP:** CDN performs real-time WebP conversions—no duplicate files or background jobs.
- **WordPress Native:** Targets core/ACF images only; plugin assets and external embeds are left untouched.
- **Responsive-Ready:** Maintains `srcset`, `sizes`, lazy-loading, and editor-defined dimensions.
- **Debug-Friendly:** Optional HTML comments give you a transparent audit trail during development.
---
## Quick Start
- [ ] Configure **WP Offload Media** to push uploads to S3-compatible storage (DigitalOcean Spaces, Amazon S3, etc.).
- [ ] Point **KeyCDN (or another compatible CDN)** at the bucket and enable format conversion via `?format=webp`.
- [ ] Install & activate **tom & tom Image Optimization for CDN**.
- [ ] Visit **Settings → tom & tom Image Optimization** to toggle features such as Enhanced Mode and Debug Mode.
> [!TIP]
> Keep a browser console open with DevTools when first testing—it's the quickest way to verify the in-page `` markup and CDN responses.
---
## Feature Spotlight
| Feature | What it delivers |
| ------------------------ | --------------------------------------------------------------------------------------------------- |
| **Automatic Conversion** | Upgrades `![]()
` tags into `` blocks with WebP-first `` elements. |
| **Smart Detection** | Validates WordPress classes, uploads paths, and ACF data before rewriting to avoid false positives. |
| **CDN Integration** | Appends WebP and width parameters that mirror the requested WordPress size variant. |
| **Browser Fallback** | Leaves the original image as the final `![]()
` element, ensuring compatibility everywhere. |
---
## Example Output
```
```
---
## Workflow
1. **Detection** – Identify WordPress images via core classes, uploads paths, and ACF metadata.
2. **Conversion** – Wrap each image in a `` element, preserving `srcset`, `sizes`, lazy-loading, and data attributes.
3. **CDN Rewrite** – Append `?format=webp&quality=X` plus WordPress-aware resize parameters.
4. **Delivery** – Browsers that support WebP consume the new source; older browsers use the fallback `![]()
`.
---
## Installation
1. Upload the plugin to `/wp-content/plugins/tomtomdesign-image-optim-for-cdn/` or install via WP-CLI:
```
wp plugin install tomtomdesign-image-optim-for-cdn --activate
```
2. Activate through the **Plugins** screen.
3. Configure settings under **Settings → tom & tom Image Optimization**.
4. Confirm WP Offload Media is offloading uploads successfully.
5. Verify your CDN honors both `?format=webp` and resize (`?width=`) query parameters.
---
## Prerequisites
**WP Offload Media**
- Installed, licensed, and configured to offload to S3-compatible storage.
**KeyCDN (or compatible CDN)**
- Supports on-the-fly format conversion via URL parameters (like `?format=webp`).
- Can respect width directives for WordPress size variants.
---
## FAQ
**Do I need WP Offload Media?**
Yes—this plugin assumes your media library is offloaded. Local-only libraries won't benefit from the CDN rewrite logic.
**Which CDNs are supported?**
Any CDN that understands format/resize parameters, including KeyCDN, Cloudflare, Amazon CloudFront, Fastly, BunnyCDN, and similar services.
**Will this change my original images?**
No. The plugin only adjusts markup. Source files remain untouched and serve as fallbacks.
**Can I exclude certain images?**
Yes. Instagram feeds, third-party plugin assets, existing WebP files, and images without WordPress metadata are skipped automatically.
**What’s the difference between Basic and Enhanced Mode?**
Basic Mode rewrites simple `![]()
` tags. Enhanced Mode also carries over `srcset`, `sizes`, and custom data attributes for responsive layouts.
**How do I confirm it’s working?**
Check the settings page status cards, enable debug comments temporarily, inspect markup via DevTools, and monitor CDN logs for `?format=webp` requests.
---
## Changelog
### 1.0.3
- Security: Fixed all output escaping issues to prevent XSS vulnerabilities.
- Security: Replaced all `_e()` calls with `esc_html_e()` for proper escaping.
- Security: Escaped all URLs, variables, and translated strings.
- Code quality: Removed discouraged `load_plugin_textdomain()` function (WordPress handles translations automatically since 4.6).
- Code quality: Removed invalid `Network` header from plugin file.
- Documentation: Created proper `readme.txt` file for WordPress.org compatibility.
- Documentation: Fixed short description length to meet WordPress.org requirements.
### 1.0.2
- Enhancement: Derive CDN resize parameters from the attachment variant so thumbnails request correctly sized assets.
- Enhancement: Preserve editor-defined dimensions while clamping requests to the original file’s max size.
### 1.0.1
- Fix: Mirror responsive `sizes` and `data-sizes` attributes into `` nodes for proper responsive behavior.
### 1.0.0
- Initial release of tom & tom Image Optimization for CDN with automatic `![]()
` to `` conversion, WP Offload Media integration, CDN support, admin settings, smart detection, enhanced mode, and debug tooling.
---
## Upgrade Notice
- **1.0.3** – Security and code quality improvements. All output is now properly escaped, and the plugin follows WordPress.org coding standards.
- **1.0.2** – Honors WordPress size variants (including custom crops) so smaller images don't fall back to the full-size asset.
- **1.0.1** – Copies `sizes`/`data-sizes` into `` elements to maintain responsive rendering.
- **1.0.0** – Initial release.
---
## Technical Details
**Settings Options**
- `keycdn_webp_enabled` — Toggle site-wide WebP conversion.
- `keycdn_webp_enhanced` — Enable enhanced `srcset` handling.
- `keycdn_webp_debug` — Surface HTML comments for debugging.
- `keycdn_webp_quality` — Define WebP quality (1-100).
**Detection Logic**
- WordPress attachment classes (`wp-image-123`).
- WordPress size classes (`size-thumbnail`, etc.).
- Advanced Custom Fields data attributes.
- Uploads directory checks (`/wp-content/uploads/`).
- Focal point styles (`object-position`).
- Descriptive alt text (10+ characters).
**Exclusions**
- Instagram feed images (`sb-instagram-feed-images`).
- Existing WebP assets (`.webp` extension).
- Plugin or static assets within `/plugins/`.
- Images lacking WordPress metadata.
---
## Support
Open an issue or pull request on GitHub for feature requests, bug reports, or documentation tweaks. Contributions are welcome.
---
## Privacy
The plugin does not collect, store, or transmit personal data. All processing happens within your WordPress installation.