FirePunch is a lightweight, high-performance 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 ID fields (such as ACF – Advanced Custom Fields). The plugin intercepts uploads and generates variants asynchronously in the background, ensuring zero impact on server performance during your daily workflow.
Thanks to its native integration with WordPress core functions, any image called via wp_get_attachment_image() will automatically be transformed into a modern, responsive HTML5 <picture> tag.
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.
- 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.
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:
<?php echo wp_get_attachment_image( $attachment_id, 'large' ); ?>
2. Using the Helper Function wp_avif_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:
<?php echo wp_avif_img( $attachment_id, $size, $attr ); ?>
- $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, set the Return Format to Image ID. In your template file, simply write:
<?php
$image_id = get_field( 'your_image_field_name' );
if ( $image_id ) {
echo wp_avif_img( $image_id, 'large', 'lazy' );
}
?>