About this plugin
FirePunch is a lightweight, 100% free plugin designed to optimize image management in WordPress by automatically converting them into next-generation AVIF and WebP formats.
This tool is built specifically for web developers working with custom themes and image fields (such as ACF – Advanced Custom Fields or Gutenberg blocks ).
How does it work?
- Automatic conversion: The plugin intercepts JPG and PNG media uploads and generates variants asynchronously in the background, ensuring zero impact on server performance during your daily workflow.
- Predictable URL Structure: Converted AVIF and WebP variants are saved directly alongside the original media, making them instantly accessible by simply appending.avif or.webp to the original image URL. For example: https://example.com/wp-content/uploads/immagine.jpg.webp and https://example.com/wp-content/uploads/immagine.jpg.avif
- Effortless Theme Integration: Simply call them inside your custom theme using the standard WordPress function wp_get_attachment_image() or the plugin’s dedicated helper function wp_avif_img().
- Smart HTML5 Fallback: The plugin automatically rewrites the frontend output into a robust <picture> tag. The browser will dynamically load the best possible format based on user compatibility, seamlessly prioritizing AVIF, falling back to WebP, and using the original JPG or PNG as the ultimate safety fallback.
Key Features:
- Asynchronous Background Processing: Leverages Action Scheduler (or WP-Cron with a safety offset) to process images sequentially without locking up the server or triggering execution timeouts. If a run is cut short by a server timeout anyway, it is detected and resumed automatically from where it stopped.
- Smart Hybrid Engine: Tries ImageMagick first for premium encoding and seamlessly falls back to GD when necessary, dynamically boosting memory limits to prevent crashes on large files.
- Zero Disk I/O Abuse: Caches the status of all available file variants directly inside the attachment metadata in the database. No endless file system lookups on every single page load.
- Modern HTML5 Rewriting: Utilizes the native WP_HTML_Tag_Processor (introduced in WP 6.2) to safely rewrite <img> tags into multi-source <picture> structures.
- Automatic Cleanup: When an image is deleted from the media library, all associated AVIF and WebP variants are permanently removed, featuring path traversal protection.
- Zero ACF Dependencies: Built 100% WordPress-native with absolutely no reliance on Advanced Custom Fields, making it perfectly compatible with any custom theme workflow.
Developer Guide (Custom Themes & ACF)
This plugin offers total flexibility for custom theme development. You can display optimized images using three different approaches:
1. Native Automatic Integration
If your theme already uses standard WordPress functions, you do not need to change a single line of code. The plugin automatically filters the output and injects the AVIF/WebP sources:
>
2. Using the Helper Function firepunch_img()
If you need granular control—such as stripping away default WordPress layout classes or easily overriding loading behavior—use the plugin’s global helper function:
>
5 the canonical name of this function is firepunch_img(). The original name wp_avif_img() is still available and behaves identically, so no existing template needs to change: the wp_ prefix is reserved for WordPress core, and the new name avoids any future collision. Both names accept the same arguments.
- $attachment_id (int): The attachment ID of the image (Required).
- $size (string|array): The requested image size (‘thumbnail’, ‘medium’, ‘large’, ‘full’). Default: ‘full’.
- $attr (string|array): Simplifies attributes. You can pass ‘lazy’ or ‘eager’ directly as a string, or supply a custom HTML attribute array.
Practical Examples:
// Standard output in 'large' size with native lazy loading echo wp_avif_img( $image_id, 'large', 'lazy' );
// Advanced output with custom CSS classes and specific Alt text echo wp_avif_img( $image_id, 'full', array( 'class' => 'hero-banner-image', 'alt' => 'Optimized hero cover background' ) );
3. Advanced Custom Fields (ACF) Integration
When creating an Image field in ACF, leave the Return Format to Array. This approach allows you to dynamically extract the attachment ID for the optimization engine while safely preserving a native standard HTML fallback. In your template file, write:
> </figure>