Allow WebP quality to be configurable in GD2 image manipulation toolkit settings

fixed the #2 custom command failed issue for D10.1.x. Removed Aggregator module changes, as we know from D10.1.x aggregator is not a part of Drupal core. We fix separately for Aggregator module.

I have verified the changes and attached the images for reference

Does it even make sense to add this to the Drupal 6 and 7 migration? It is obvious that this value is not defined in any version before D10, so I question the need to the migration of that non-existing setting.

Also, a cursory look at the current contents of the cspell dictionary shows that file is case-insensitive being 100% lower-case, so there is certainly no need to add 2 versions of 'WEBP' to it.

And maybe a suggestion, I fear for an explosion of image_xxxx_quality, maybe instead of image_jpeg_quality and image_webp_quality, we should replace both with image_quality and use the same value for both jpeg and webp, but this last one is my personal opinion, and would benefit from the opinion of others.

Well, the introduction of lossless is most likely causing the first test to fail. And I believe the other 2 tests are failing because of the remaining change to core/modules/system/migrations/system_image_gd.yml.

This is a patch for Drupal 10 which requires PHP 8.1 as a minimum (https://www.drupal.org/docs/system-requirements/php-requirements), so no need to check if the IMG_WEBP_LOSSLESS is defined, as it should always be there.

If this is ever ported back to Drupal 9, then the check would be useful but only for the backport.

Also, please do interdiffs between the new patch and the previous one.

Hard to get the diff without interdiff ☹️

Reroll of #11 for 9.5.x and 10.1.x

Reroll #11 against 9.5.x and 10.1.x once more (#16 rerolled against older versions of those branches).

I think instead of configuration for each format core can introduce new common option

Also tests needs to be fixed

Patch for 10.2.x.

#23 works fine for me. Thanks for this great patch. Hope this functionnality will be add in future release of Drupal....

Note, this will not retain a color profile. If an image was saved out with Adobe RGB profile, it will be removed on webp conversion with image styles.

#23 works fine for me too. Thanks!

I can confirm that MR #30 works fine for Drupal 10.3.0. Thank you!

Created a patch for 10.2.x as well.

The Needs Review Queue Bot tested this issue. It no longer applies to Drupal core. Therefore, this issue status is now "Needs work".

This does not mean that the patch necessarily needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.

Consult the Drupal Contributor Guide to find step-by-step guides for working with issues.

Re-rolled patch for 10.3.x

Still appears to need upgrade path. Also any fixes please put into an MR.

Added setting webp_quality config value on form submit, to #34 10.3.x patch.

Re-roll #36 for 10.2.4

- Added upgrade path and tests for it.
- Changed the UI facing texts from "WEBP" to "WebP".
- Since Drupal 11 requires PHP 8.3, there's no need to check for support of IMG_WEBP_LOSSLESS
- Hide the outdated patches.

UI changes should be documented in the summary so tagging for that.

Once issue summary is complete will probably need usability sign off for the new UI.

Also change would need a change record

I assume usability review could think following issues:
- Position of lossless checkbox on form.
- Need for lossless checkbox on form. Since the IMG_WEBP_LOSSLESS equals to 101 value ( see: https://php.watch/versions/8.1/gd-webp-lossless). We could remove the checkbox and treat the 100 selection same as lossless selection (This is how Intervention/image does it)

Usability review

We discussed this issue at #3474035: Drupal Usability Meeting 2024-09-20. That issue will have a link to a recording of the meeting. For the record, the attendees at last Friday's usability meeting were @AaronMcHale, @anmolgoyal74, @benjifisher, @rkoller, @shaal, @simohell, and @zetagraph.

If you want more feedback from the usability team, a good way to reach out is in the #ux channel in Slack.

Recommendations

Use radio-buttons to show both the options as equal choices. This will be clearer for the user and there even is an edge case, where a Safari browser supports lossy format but not lossless. Label them “WebP quality” to match JPEG quality as equal section.

WebP quality
- Lossless compression
- Lossy compression

As "Lossy compression" is selected display the numeric field indented visually to the same level with the radio-button.

WebP quality
- Lossless compression
- Lossy compression
[ 75% ] Set the image quality for WebP manipulations. Ranges from 0 to 100. Higher values mean better image quality but bigger files.

The label text is a suggestion, it was not decided by consensus in the meetiong.

It is also suggested to change the word “define” to “set” in the compression settings description.

Updating documentation

Include the information about WebP setting into documentation at https://www.drupal.org/docs/7/core/modules/image/working-with-images#s-s...

Add a note, that in some old browsers or operating systems versions it may be, that a browser supports the lossy compression but not the lossless compression.

Thanks usability team!

Can I ask how does this affect webp conversions of jpegs in an image style?

Does the 75% get applied to the jpeg and then a further 75% when converted to webp?

In my case, I might want to decide the quality on the fly. For instance, if an image is 100x100 I'd use a 90 quality, if it's 4000x4000, I'd use a 70 quality. I might also want different qualities for webp vs jpeg. I doubt if both are rare requests.

So, it'd be great if there were an object representing ImageFormatConfiguration or similar that would hold the quality for a specific format and could also hold other things later on. Those objects could then appear on admin/config/media/image-toolkit in a list and the user could add or remove such objects and change their values.

And, it'd be great if there was something like an ImageQualityEvent that would be fired before doing an operation. The event would have getQuality/setQuality in addition to a reference to the image and contextual data like where it's going to be stored, etc. The event would be created with the default quality, and then listeners could change that based on the dimensions, size, or location of the image.

Not to distract from the above, but on a related note, GDToolkit is confusing in that it appears to mix different functionalities together, like holding an image and saving that image. IMNSHO, it'd be good to split it into GDToolkitImage and GDToolkit (or GDToolkitManager or something). It also seems more inflexible than other parts of Drupal.

The MR does not apply to D11.3.0

I've created a new merge request (!14253) that incorporates the changes from !8420, but makes the following improvements based on comment #42:

Changes implemented:

• Replaced checkbox with radio buttons for "Lossless compression" vs "Lossy compression" options
• Wrapped both JPEG and WebP settings in fieldsets to give them equal visual weight
• Used Form API #states to conditionally show/hide the quality field based on compression type selection
• Added visual indentation (margin) to associate the quality field with the "Lossy compression" option
• Removed redundant labels for cleaner UI
• Changed "Define" to "Set" in field descriptions per usability feedback

The quality field now only appears when "Lossy compression" is selected.

Response to Comment #44
Good question! No, the quality settings are not applied cumulatively. Each format uses its own quality setting:

When saving a JPEG, it uses the JPEG quality setting (75% by default)
When saving a WebP, it uses the WebP quality setting (80% by default)
If you use an image style with a "Convert" effect to change a JPEG to WebP, the WebP quality setting applies to the final output. The JPEG quality only affects images saved as JPEG format. You can verify this in the GDToolkit.php:289-370 where each format's quality is handled separately based on the current image type.

Response to Comment #45
Those are interesting feature suggestions for more advanced quality management. However, they would represent significant architectural changes to the image toolkit system and are beyond the scope of this issue, which focuses on making WebP quality configurable (similar to how JPEG quality already is).

Your suggestions about:

Dynamic quality based on image dimensions
Format-specific configuration objects
Event-driven quality determination via ImageQualityEvent
...would be excellent topics for follow-up issues. The current implementation provides the foundation by making WebP quality configurable, and future enhancements could build on this.

Test failure, setting to needs work.

I've updated the test to account for our new form structure. All new and existing tests pass now.

Here is an additional screenshot to show the lossless option selected.

Here is a snippet we could add to the change record that describes how this could break existing sites.

Backward Compatibility Changes

Form API field paths have changed on the image toolkit configuration form:

The JPEG quality field on the image toolkit configuration form (/admin/config/media/image-toolkit) has been moved into a fieldset for visual consistency with the new WebP quality settings. This changes the form field path:

• Old path: gd[image_jpeg_quality]
• New path: gd[jpeg_quality_wrapper][image_jpeg_quality]

Impact:

• Code using hook_form_alter() or hook_form_FORM_ID_alter() to modify the JPEG quality field on the toolkit configuration form must update the field path
• Custom form submit handlers that read $form_state->getValue(['gd', 'image_jpeg_quality']) from the toolkit configuration form must update to $form_state->getValue(['gd', 'jpeg_quality_wrapper', 'image_jpeg_quality'])
• Automated tests interacting with this form field must update their field selectors

Configuration keys remain unchanged:

The configuration keys stored in system.image.gd have not changed:

• jpeg_quality (unchanged)
• webp_quality (new)
• webp_lossless (new)

Only the form structure has changed, not the underlying configuration storage.

The Needs Review Queue Bot tested this issue. It fails the Drupal core commit checks. Therefore, this issue status is now "Needs work".

This does not mean that the patch necessarily needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.

Consult the Drupal Contributor Guide to find step-by-step guides for working with issues.

I am setting this back to needs review, and adding the no-needs-review-bot tag, because the review bot is testing the wrong merge request, and this MR needs maintainer review. I do not feel comfortable overwriting the existing merge request without some indication from the maintainers that this change to the form is in fact acceptable. If this one is acceptable, feel free to merge it, or say, please merge MR !14253 into MR !8420 I will do so.

MR appears to need a rebase please

As part of DrupalCon Chicago 2026 Contribution day, heddn updated the branch to main and with Rishi Kulshreshtha's help I rebased the MR as smustgrave requested. The pipeline passed, so I think it's good to re-review and test.

I also updated the Change Record with the notes from trackleft2 in comment #53.

Im at Chicago 2026, just tested the MR @jane_irwin made with a clean Drupal 11.x on simplytest.me. and i can see the changes, new form behaviors and validation.

I've posted some random thoughts on the MR that could possibly be accommodated in some comment updates. Marking NR to see if anyone else agrees.

Thanks, everyone, for your work on this so far! I have some additional comments on the MR.