Prevent transparency loss in AVIF by falling back to WebP on older ImageMagick #2245

b1ink0 · 2025-10-30T21:17:07Z

Summary

Fixes #2237

Relevant technical choices

Prevents transparent backgrounds from being lost when converting PNG images to AVIF format on older ImageMagick

TODO:

Site health test
Add tests

codecov · 2025-10-30T21:26:06Z

Codecov Report

❌ Patch coverage is 16.49485% with 81 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.17%. Comparing base (7eab9ca) to head (fdf65ec).
⚠️ Report is 2 commits behind head on trunk.

Files with missing lines	Patch %	Lines
...ploads/class-webp-uploads-image-editor-imagick.php	0.00%	24 Missing ⚠️
...ealth/imagick-avif-transparency-support/helper.php	0.00%	23 Missing ⚠️
plugins/webp-uploads/helper.php	35.48%	20 Missing ⚠️
plugins/webp-uploads/hooks.php	40.00%	6 Missing ⚠️
...health/imagick-avif-transparency-support/hooks.php	0.00%	5 Missing ⚠️
plugins/webp-uploads/site-health/load.php	0.00%	2 Missing ⚠️
plugins/webp-uploads/load.php	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##            trunk    #2245      +/-   ##
==========================================
- Coverage   68.85%   68.17%   -0.68%     
==========================================
  Files          90       94       +4     
  Lines        7612     7705      +93     
==========================================
+ Hits         5241     5253      +12     
- Misses       2371     2452      +81

Flag	Coverage Δ
multisite	`68.17% <16.49%> (-0.68%)`	⬇️
single	`35.19% <16.49%> (-0.28%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

westonruter · 2025-10-31T04:55:05Z

plugins/webp-uploads/hooks.php

+	$imagick = $image_property->getValue( $editor );
+
+	if ( $imagick instanceof Imagick ) {
+		wp_cache_set( 'webp_uploads_image_has_transparency', (bool) $imagick->getImageAlphaChannel(), 'webp-uploads' );


Is this set here in the cache since this function runs first and then later webp_uploads_get_image_output_format() runs to then read the value from the cache? This seems perhaps brittle. Normally setting and getting a cache value would happen in the context of the same function, not across separate functions, right? It feels like there may not be guarantees that the cached value would be set when it is checked for.

Yeah, it works but is definitely brittle. The other approach I can think of is using a global variable or a transient with a short expiration time to store the transparency status and hash of any uploaded file for the current request, and then using it in the webp_uploads_filter_image_editor_output_format to determine the output format. If you have any ideas for a temporary storage that can be used within the same request, I’d appreciate that.
@adamsilverstein if you also have a better idea to handle this case, I’d appreciate that as well.

If these are both part of the same request, perhaps you could apply a filter inside the webp_uploads_filter_image_editor_output_format function, then add a filter here to set the value?

There are multiple approaches. I came up with this to solve it:
The most elegant way is to replace the WP_Image_Editor_Imagick class with a custom class WebP_Uploads_Image_Editor_Imagick, which can be used to detect transparency and provide access to the protected variable.

But this will interfere with other plugins if they are trying to use their own custom class. I was thinking of just dynamically extending any custom classes extended from the WP_Image_Editor_Imagick class.

If these are both part of the same request, perhaps you could apply a filter inside the webp_uploads_filter_image_editor_output_format function, then add a filter here to set the value?

The issue I faced was with the size-image generation. The webp_uploads_filter_image_editor_output_format filter is called with an empty filename, so with this approach the sub-size images were getting generated as AVIF.

Because of that, the only way to check the current processing image calling the output-format filter is to access the $image of the image-editor instance that is processing it. But since the core does not expose the image-editor instance through globals or filters, there seems to be no way to determine the currently processed image. To solve this, the only idea I could come up with was using our own custom Image Editor class.

I have implemented the mentioned approach in this commit 2247b61.

cc: @adamsilverstein

westonruter · 2025-10-31T04:57:31Z

plugins/webp-uploads/hooks.php

+	$reflection     = new ReflectionClass( $editor );
+	$image_property = $reflection->getProperty( 'image' );
+	if ( PHP_VERSION_ID < 80100 ) {
+		$image_property->setAccessible( true );
+	}
+	$imagick = $image_property->getValue( $editor );


It's too bad that the image property is protected. Note how in the Image Placeholder plugin it actually extends WP_Image_Editor_Imagick with a Dominant_Color_Image_Editor_Imagick which it then uses. This is problematic though since multiple plugins can't each register their own editor classes.

I did try to create an anonymous class and added a method to expose the image property, but the Reflection API seemed better.

westonruter · 2025-10-31T05:00:57Z

plugins/webp-uploads/helper.php

+function webp_uploads_imagick_avif_transparency_supported(): bool {
+	if ( extension_loaded( 'imagick' ) && class_exists( 'Imagick' ) ) {
+		$imagick_version = Imagick::getVersion();
+		if ( (bool) preg_match( '/((?:[0-9]+\\.?)+)/', $imagick_version['versionString'], $matches ) ) {


Suggested change

if ( (bool) preg_match( '/((?:[0-9]+\\.?)+)/', $imagick_version['versionString'], $matches ) ) {

if ( (bool) preg_match( '/^\d+(?:\.\d+)+$/', $imagick_version['versionString'], $matches ) ) {

Updated regex to /\d+(?:\.\d+)+(?:-\d+)?/ for handling version string like this:

ImageMagick 7.1.1-15 Q16 aarch64 98eceff6a:20230729 https://imagemagick.org

Co-authored-by: Weston Ruter <westonruter@google.com>

…cy-loss

b1ink0 · 2025-11-14T12:33:18Z

plugins/webp-uploads/site-health/imagick-avif-transparency-support/hooks.php

Would it make more sense to move this Site Health test to the Modern Image Formats plugin?

Just seeing this comment. I think it makes sense to move all Site Health tests for images to the plugin. See #1781

…cy-loss

github-actions · 2025-12-26T13:05:59Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @johnmagbag1995, @wes-davis.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Unlinked contributors: johnmagbag1995, wes-davis.

Co-authored-by: b1ink0 <b1ink0@git.wordpress.org>
Co-authored-by: westonruter <westonruter@git.wordpress.org>
Co-authored-by: adamsilverstein <adamsilverstein@git.wordpress.org>
Co-authored-by: paulgibbs <djpaul@git.wordpress.org>
Co-authored-by: mindctrl <mindctrl@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

Add support for AVIF transparency checks during image uploads

ae7f22d

b1ink0 added this to the webp-uploads n.e.x.t milestone Oct 30, 2025

b1ink0 added [Type] Bug An existing feature is broken [Plugin] Modern Image Formats Issues for the Modern Image Formats plugin (formerly WebP Uploads) labels Oct 30, 2025

westonruter requested changes Oct 31, 2025

View reviewed changes

b1ink0 and others added 3 commits November 3, 2025 02:04

Improve Imagick version string regex validation

a1aff66

Co-authored-by: Weston Ruter <westonruter@google.com>

Merge branch 'trunk' into fix/imagemagick-old-version-avif-transparen…

be0817b

…cy-loss

Add site health checks for Imagick AVIF transparency support

3fe6954

b1ink0 commented Nov 14, 2025

View reviewed changes

westonruter mentioned this pull request Nov 20, 2025

Transparent backgrounds lost when converting to AVIF under certain conditions #2237

Open

b1ink0 added 3 commits December 17, 2025 19:23

Add custom image editor class to help with AVIF transparency detection

2247b61

Move Imagick AVIF transparency support site health test

1a58d1c

Merge branch 'trunk' into fix/imagemagick-old-version-avif-transparen…

fdf65ec

…cy-loss

b1ink0 marked this pull request as ready for review December 26, 2025 13:05

b1ink0 requested a review from felixarntz as a code owner December 26, 2025 13:05

	if ( (bool) preg_match( '/((?:[0-9]+\\.?)+)/', $imagick_version['versionString'], $matches ) ) {
	if ( (bool) preg_match( '/^\d+(?:\.\d+)+$/', $imagick_version['versionString'], $matches ) ) {

Prevent transparency loss in AVIF by falling back to WebP on older ImageMagick #2245

Are you sure you want to change the base?

Prevent transparency loss in AVIF by falling back to WebP on older ImageMagick #2245

Conversation

b1ink0 commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Relevant technical choices

Uh oh!

codecov bot commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

b1ink0 Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Dec 26, 2025

Unlinked Accounts

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

b1ink0 commented Oct 30, 2025 •

edited

Loading

codecov bot commented Oct 30, 2025 •

edited

Loading

b1ink0 Nov 14, 2025 •

edited

Loading