FirePunch | Instant AVIF & WebP images for ACF developers

<?php echo wp_get_attachment_image( $attachment_id, 'large' ); ?>

<?php echo firepunch_img( $attachment_id, $size, $attr ); ?>

// 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'
) );

<figure>
   <?php if($acf_img_field): ?>
      <?php if ( function_exists('wp_avif_img') ) {
         $img_id = $acf_img_field['ID'];
         echo wp_avif_img($img_id, 'large', 'lazy');
      } else { ?>
         <img loading="lazy" src="<?php echo esc_url($acf_img_field['url']); ?>" alt="<?php echo esc_attr( $acf_img_field['alt'] ); ?>" />
      <?php } ?>
   <?php endif; ?>
</figure>

Changelog

2.2.5

Behavior changes worth knowing before you update:

• GIF images are no longer converted. Imagick and GD write only the first frame into WebP and AVIF, so inside the picture tag the browser preferred a still image over the animated original and the animation was lost. The plugin has always documented JPG and PNG as its scope, and now the code matches the documentation.
• AVIF variants are generated at quality 60 instead of 82. The AVIF and JPEG quality scales are not comparable, and 82 sat well past the point where extra bytes stop buying visible quality. Expect noticeably lighter AVIF files. Use the new firepunch_variant_quality filter to change it.
• A generated variant is now kept only when it is genuinely lighter than the source image. On small PNGs, logos, icons and tiny crops a next-gen variant can end up larger than the original, and the browser would still have chosen it, downloading more bytes than doing nothing at all. Such variants are now discarded. This applies to newly generated files only: variants already sitting in your uploads folder are left untouched.
• The picture tag is no longer injected in the WordPress admin, in REST API responses or in RSS feeds. It is only useful while the theme renders the page, and elsewhere it could break code that expects a single img tag.

Fixes:

• Fixed a race condition that could permanently stop a newly uploaded image from ever receiving a picture tag. If a visitor loaded the image while the background conversion was still running, the frontend could write “no variants available” over the values the background job had just saved, and the result was never checked again.
• Variants left behind by regenerating thumbnails, or by editing an image from the WordPress editor (crop, rotate), are now removed instead of staying in the uploads folder forever, invisible to both the frontend and the media library.
• Variants belonging to image edits stored in the attachment backup sizes are now deleted together with the attachment.
• The metadata filter can no longer stay detached when a conversion fails. With Action Scheduler, which processes a whole batch in a single request, one failure used to disable the picture tag for every remaining image in that batch.
• The uploads directory containment check is now case insensitive on Windows, where a mismatched drive or folder case could silently disable the entire plugin.
• Uploads that are not images (archives, audio, video) no longer queue a background job that had nothing to do. PDF previews are still processed.
• Conversions interrupted by a PHP timeout are now picked up and finished. On shared hosting a background run could be killed halfway through a large image, leaving some sizes without variants and nothing to restart them. The plugin now marks a run as started, and an hourly check re-queues anything that never reached the end, resuming from where it stopped. After three incomplete attempts an image is left alone instead of being retried forever. The scheduled check is removed when you deactivate the plugin.
• Fixed the markup of the settings page: three section headings were closed with the wrong tag, and the verification steps list sat inside a paragraph, which made the browser drop its intended styling.
• Fixed the spacing of background jobs during bulk uploads. The queue spaces conversions ten seconds apart, but the value tracking the queue position expired after one hour, so any queue longer than an hour lost its place and every following job piled onto the same moment: exactly the burst the spacing exists to prevent. The queue position now lives as long as the queue itself, and the queue can no longer be pushed more than six hours into the future, so the last images of a large import are not left waiting for days.

Performance:

• The frontend no longer writes to the database while rendering the page. Detecting variants for older media used to run a database update per image inside the visitor’s response; those writes now happen after the response has been sent.
• The memory limit is raised before the primary image library opens the file, instead of only inside the GD fallback, which is exactly where large PNG files were most likely to exhaust the available memory.
• New firepunch_variant_image_sizes filter to restrict which registered image sizes get converted. A typical installation registers 12 to 18 sizes, which means up to about 38 encodings per upload, and most of them never end up in a picture tag. Restricting this list is also the most effective way to avoid timeouts on slower hosting.
• The per-request cache used while detecting variants for older media is now capped, so a long running process such as wp media regenerate cannot grow it without limit.

Developer notes:

• New global function firepunch_img(), the correctly prefixed canonical name. wp_avif_img() keeps working as an alias, so no template change is required.
• Conversion failures are now written to the error log when WP_DEBUG is enabled, so “this server cannot produce AVIF” and “the conversion failed” are no longer indistinguishable.
• The tutorial video on the settings page now loads from the privacy friendly youtube-nocookie.com domain, and only once it scrolls into view.
• The plugin file now declares “Requires at least: 6.2”, matching what readme.txt has always stated, so WordPress warns you before installing on an older release instead of letting the picture tag silently stop working.
• Removed a dead regular expression HTML parser. WP_HTML_Tag_Processor has been part of WordPress core since 6.2, the minimum version this plugin requires, so the fallback branch could never run: about 35 lines of hand written HTML parsing that carried maintenance and review cost for nothing.
• Release hygiene: .DS_Store files are no longer shipped inside the plugin package, and the deploy workflow pins the release action to a fixed commit.

2.2.4

• Extended the path traversal protection to the variant generation routine, so conversions are written only inside the uploads directory.
• Newly registered image sizes are now detected on existing media instead of being permanently excluded from the picture tag.
• Faster picture tag rendering: variant lookup for srcset candidates now uses an index instead of rescanning every registered image size for each candidate.

2.2.3

• Hardened the path traversal protection used during variant cleanup: the containment check no longer matches sibling directories sharing the uploads prefix, and is now separator and case normalized for Windows hosts.
• Reduced database writes and disk I/O on the frontend: variant detection for legacy media is now cached per request and persisted only once per attachment, guarded against concurrent duplicate writes on servers with a persistent object cache.
• Runtime-only metadata changes made by other plugins are no longer written permanently to the database when caching variant availability.
• Replaced the temporary filter removal with a re-entrancy guard, so the metadata filter can no longer stay detached if a save fails mid-process.

2.2.2

• readme.txt fix

2.2.1

• readme.txt fix

2.2

• readme.txt YT video

2.1

• Added admin page to show current settings, plugin status and some debug information to diagnose issues.
• Fixed blurry header banner on desktop screens.
• Updated readme.txt documentation.

1.2

• Replaced the old regex parser with the native WP_HTML_Tag_Processor API for robust and safe HTML rewriting.
• Resolved a potential PHP Warning in the file cleanup method caused by manually deleted upload subdirectories.
• Optimized readme markup syntax for 100% compliance with the WordPress.org validator.

1.1

• Introduced the hybrid conversion workflow (Imagick + GD) featuring dynamic memory allocation adjustments for heavy PNG files.

1.0

• Initial plugin release.