[wp-trac] [WordPress Trac] #65262: REST API: expose size-aware encode quality on attachment responses

[WordPress Trac]

#65262: REST API: expose size-aware encode quality on attachment responses
-----------------------------+--------------------------------------
 Reporter:  adamsilverstein  |      Owner:  (none)
     Type:  defect (bug)     |     Status:  new
 Priority:  normal           |  Milestone:  Awaiting Review
Component:  REST API         |    Version:
 Severity:  normal           |   Keywords:  has-patch has-unit-tests
  Focuses:                   |
-----------------------------+--------------------------------------
 Client-side media processing (introduced for the editor) encodes image
 sub-sizes in the browser. To produce output consistent with server-side
 processing it needs to know the encode quality the site has configured,
 but
 that value is currently not exposed anywhere in the REST API. As a result,
 browser-side encoding falls back to a hardcoded default and the
 [https://developer.wordpress.org/reference/hooks/wp_editor_set_quality/
 wp_editor_set_quality]
 filter is silently ignored for these images.

 `wp_editor_set_quality` has been size-aware since 6.8 — its signature is
 `( int $quality, string $mime_type, array $size )` — so a site can return
 a
 different quality per dimension (for example, a lower quality for
 thumbnails). A single flat value cannot represent that.

 == Proposed change ==

 Add an `image_quality` field to the media attachment REST response
 (`WP_REST_Attachments_Controller`), in the `edit` context, alongside the
 existing `exif_orientation` field:

 {{{#!json
 "image_quality": {
   "default": 82,
   "sizes": { "thumbnail": 60 }
 }
 }}}

  * The filter is resolved against the '''output''' MIME type (after
 `image_editor_output_format`), the same way
 `WP_Image_Editor::set_quality()` does.
  * `default` is the filtered quality for the full-size image.
  * Each registered sub-size is re-filtered with that size's dimensions; a
 size is reported under `sizes` only when its value diverges from
 `default`, keeping the response payload small.
  * The field is `readonly` and limited to the `edit` context, matching
 `exif_orientation`.

 This mirrors the pattern already used for `exif_orientation`, keeping
 per-file image-processing decisions in the attachment response where the
 real filename, MIME type and dimensions are available.

 == Patch / PRs ==

  * Core PR: https://github.com/WordPress/wordpress-develop/pull/11856
  * Gutenberg consumer PR:
 https://github.com/WordPress/gutenberg/pull/78420
  * Related Gutenberg issue:
 https://github.com/WordPress/gutenberg/issues/78419
  * Follows the same approach as the earlier `image_editor_output_format`
 work (Gutenberg [https://github.com/WordPress/gutenberg/issues/75784
 #75784] / [https://github.com/WordPress/gutenberg/pull/75793 #75793]).

 == Tests ==

 `tests/phpunit/tests/rest-api/rest-attachments-controller.php`:

  * `test_image_quality_schema` — field is present, typed, `readonly`,
 `edit`-context.
  * `test_image_quality_default_in_response` — JPEG default is `82`, empty
 `sizes` with no filter.
  * `test_image_quality_with_size_aware_filter` — a size-aware
 `wp_editor_set_quality` filter is reflected per size, and only divergent
 sizes are reported.
  * `test_get_item_schema` — property count updated 32 → 33.

 All pass locally (`phpunit --filter test_image_quality`,
 `phpunit --filter test_get_item_schema`). phpcs clean.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/65262>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform