ImgPress for WordPress

A WordPress plugin that compresses images, PDFs, audio, and video files through the ImgPress API — automatically on upload or manually via the media library.

Features

• Auto-compress on upload — files are compressed before the attachment post is created, so WordPress stores the optimized version from the start
• Manual & bulk compression — compress existing media one at a time from the media library, or process your entire library in bulk
• Multi-format support — images (JPEG, PNG, WebP, HEIC, AVIF, GIF), PDFs, audio (MP3/WAV/FLAC → M4A), and video (MP4/MOV/AVI → MP4)
• Configurable output — control quality, output format (WebP, AVIF, JPEG, or auto), and max image width
• Content URL migration — when conversion changes a file extension, embedded full-size and generated-size URLs are updated in WordPress content and Bricks Builder header/content/footer data; restoring the original reverses them
• Media library integration — an "⚡ ImgPress" column shows compression stats (reduction %, before/after size, date) for every attachment
• Bulk compress dashboard — progress bar, per-file results table, and aggregate stats (total saved, average reduction)
• Cloudflare R2 storage — offload media to R2 with one-click bulk uploads, optional automatic push on compress, public-hostname support via r2.dev or a custom domain, and optional local file deletion

Requirements

• WordPress 6.0+
• PHP 8.1+
• Access to an ImgPress API instance
• (Optional) Cloudflare account with R2 enabled for media storage

Installation

1. Download or clone this repository into wp-content/plugins/imgpress-wp
2. Activate the plugin from Plugins → Installed Plugins
3. Go to Settings → ImgPress and enter your API URL

Configuration

All settings live under Settings → ImgPress.

Compression Settings

Use the Test Connection button to verify the API is reachable before saving.

R2 Storage (Optional)

Use the Test R2 Connection button to verify your R2 credentials are valid.

The Cloudflare S3 API endpoint (https://{account-id}.r2.cloudflarestorage.com) is for authenticated access, not for public media delivery. ImgPress builds attachment URLs from the configured public hostname and each object's stored R2 key, so you can switch from an r2.dev development hostname to a custom domain after offloading without re-uploading the files.

ImgPress applies the configured Cache-Control policy to static images (jpg, jpeg, png, webp, avif, svg), fonts (woff, woff2), and videos (mp4, webm). Dynamic and temporary objects are left unchanged. Updating an existing object's policy preserves its content type, content disposition, content encoding, and custom metadata.

Usage

Automatic compression

With auto-compress enabled, every uploaded file is sent to the API before WordPress creates the attachment. No action required.

Media library actions

In the media library list view, select one or more attachments, choose an ImgPress action from the Bulk actions menu, then click Apply:

• Convert/Compress optimizes the selected supported files
• Restore Originals restores selected attachments that have an original backup
• Offload to R2 uploads selected attachments when R2 is configured

The ⚡ ImgPress column shows optimization and R2 status. Compact text buttons remain available for individual actions. Use the bulk actions for processing multiple attachments.

On ImgPress → R2 Offload, enable Re-offload files already uploaded to R2 to upload local copies again and refresh their R2 metadata, including the configured Cache-Control policy. Attachments without local copies fail safely without removing their existing R2 objects.

Bulk compression

Go to Media → Bulk Compress. The page shows how many files are pending, then lets you start a batch run that processes each file sequentially and displays a live progress bar and results table.

R2 Storage

To use Cloudflare R2 storage:

1. Create an R2 bucket in your Cloudflare dashboard
2. Create an API token with R2 read/write permissions and copy the credentials
3. Configure R2 in ImgPress settings:
   • Enable R2
   • Enter your Account ID, Access Key ID, and Secret Access Key
   • Specify your bucket name
   • (Optional) Add a public hostname (r2.dev for testing or a custom domain for production)
   • Test the connection with the Test R2 Connection button
4. Push files to R2 manually:
   • In the media library list, select files and use Bulk actions → Offload to R2
   • Or go to Media → Bulk Offload to R2 to upload your entire library at once
5. (Optional) Enable automatic sync:
   • Check "Auto-push compressed files to R2" to upload automatically after compression
   • Check "Auto-push uncompressed files on upload" to upload new files immediately
   • Check "Delete local files after uploading" to save server space (⚠️ ensure you have backups!)
   • Check "Rewrite content URLs" to automatically update post content with R2 URLs

Permanently deleting an attachment from the Media Library also deletes its recorded original and generated-size objects from R2. If R2 cleanup fails, ImgPress cancels the WordPress deletion and shows an error so the attachment can be retried safely.

Orphaned R2 objects

Go to ImgPress → R2 Offload → Orphaned R2 objects and click Scan bucket to preview objects at least 24 hours old that are not referenced by attachment metadata. Review the results, select only the objects you recognize as obsolete, then click Delete selected. Each selected object is rechecked immediately before deletion. Scanning never deletes objects automatically; this is especially important when the R2 bucket is shared with another application.

Data stored

For each compressed attachment the plugin saves the following post meta:

File structure

imgpress-wp/
├── imgpress-wp.php          # Bootstrap, autoloader, activation hook
├── includes/
│   ├── class-settings.php       # Admin settings page & option getters
│   ├── class-api-client.php     # HTTP client for the ImgPress API
│   ├── class-compressor.php     # Core compress-and-replace logic
│   ├── class-auto-compress.php  # Hooks into wp_handle_upload
│   ├── class-media-columns.php  # Media library column & single-compress AJAX
│   ├── class-bulk-compress.php  # Bulk compress page & AJAX handlers
│   ├── class-r2-client.php      # S3-compatible API client for Cloudflare R2
│   ├── class-r2-uploader.php    # R2 upload orchestration & meta tracking
│   ├── class-r2-bulk.php        # Bulk offload page & AJAX handlers
│   └── class-r2-url-rewriter.php # Rewrites post content URLs to R2 URLs
├── admin/
│   ├── page-settings.php        # Settings page template
│   ├── page-bulk.php            # Bulk compress page template
│   └── page-r2-bulk.php         # Bulk R2 offload page template
└── assets/
    ├── admin.js                 # jQuery for AJAX actions and progress UI
    └── admin.css                # Admin styles

License

MIT — see LICENSE for details.

Author

Hoang Kiem