[wp-trac] [WordPress Trac] #65367: REST API: expose per-attachment output format and progressive flags for client-side media processing

[WordPress Trac]

#65367: REST API: expose per-attachment output format and progressive flags for
client-side media processing
-----------------------------+------------------------------------------
 Reporter:  adamsilverstein  |      Owner:  (none)
     Type:  defect (bug)     |     Status:  new
 Priority:  normal           |  Milestone:  Awaiting Review
Component:  REST API         |    Version:
 Severity:  normal           |   Keywords:  needs-patch needs-unit-tests
  Focuses:                   |
-----------------------------+------------------------------------------
 Client-side media processing encodes sub-sizes (and, when applicable, the
 threshold-scaled "scaled" copy) in the browser before uploading. To match
 server-side output, the browser needs two pieces of information that today
 are not exposed on the attachment response:

  * The output MIME type a given file should be saved as, per the
 [https://developer.wordpress.org/reference/hooks/image_editor_output_format/
 image_editor_output_format] filter. The filter is filename- and MIME-aware
 (`( array $formats, string $filename, string $mime_type )`), so a value
 computed in the REST index without a real filename is incorrect for any
 non-trivial site.
  * Whether progressive / interlaced encoding is requested for that MIME
 type, per the
 [https://developer.wordpress.org/reference/hooks/image_save_progressive/
 image_save_progressive] filter.

 Today these values are surfaced (in Gutenberg) on the REST API root index
 with empty filename and `image_save_progressive` evaluated against hard-
 coded MIME types. That is wrong: the filter contract requires the real
 filename and MIME of the file being saved, and plugins can return
 different decisions per file. The bypass-labelled Gutenberg PR
 [https://github.com/WordPress/gutenberg/pull/75793 #75793] moved this
 information to the per-attachment upload response in the Gutenberg plugin;
 this ticket backports the same change to Core.

 == Proposed change ==

 Add two readonly fields to `WP_REST_Attachments_Controller`, in the `edit`
 context, alongside the existing `exif_orientation` field:

 {{{#!json
 "image_output_format": "image/webp",
 "image_save_progressive": false
 }}}

  * `image_output_format` returns the resolved output MIME type when
 `image_editor_output_format` maps the source MIME to a different one (e.g.
 JPEG → WebP), or `null` when no conversion is needed. The filter is called
 with the real attached filename and MIME type, so plugins can make per-
 file decisions.
  * `image_save_progressive` returns the boolean result of the
 `image_save_progressive` filter for the attachment's MIME type.
  * Both fields are evaluated only for image attachments
 (`wp_attachment_is_image()`).
  * `prepare_item_for_response()` and the upload / sideload code paths
 recompute the values after lifting the temporary `__return_empty_array` /
 `__return_zero` guards that the controller installs around the initial
 response, so the values surfaced reflect the site's real configuration.

 This deprecates the legacy generic surfacing of `image_output_formats`,
 `jpeg_interlaced`, `png_interlaced`, and `gif_interlaced` on the REST API
 root index (which used empty filenames and hard-coded MIME types). Those
 entries should be removed when the new per-attachment fields land.

 == Patch / PRs ==

  * Gutenberg PR (merged 2026-04-23):
 https://github.com/WordPress/gutenberg/pull/75793
  * Gutenberg issue: https://github.com/WordPress/gutenberg/issues/75784
  * Core backport PR: (open after this ticket is filed; will be linked from
 PR description)
  * Related ticket — sibling `image_quality` field:
 https://core.trac.wordpress.org/ticket/65262
    (Gutenberg [https://github.com/WordPress/gutenberg/pull/78420 #78420] /
 core
    [https://github.com/WordPress/wordpress-develop/pull/11856 #11856]).
  * Context: client-side media processing was
 [https://core.trac.wordpress.org/ticket/63884 reverted and re-introduced]
 for 7.1; the Gutenberg PR was originally labelled `No Core Sync Required`
 because client-side media was Gutenberg-only at the time. The Core sync is
 now required.

 == Tests ==

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

  * `test_image_output_format_schema` - field is present, nullable string,
 `readonly`, `edit`-context.
  * `test_image_save_progressive_schema` - field is present, boolean,
 `readonly`, `edit`-context.
  * `test_image_output_format_default` - returns `null` when no filter
 remaps the source MIME.
  * `test_image_output_format_with_filter` - JPEG→WebP filter is reflected
 in the response and uses the real attached filename.
  * `test_image_save_progressive_default` - returns `false` for JPEG with
 no filter.
  * `test_image_save_progressive_with_filter` - a MIME-aware
 `image_save_progressive` filter is honored.
  * `test_get_item_schema` - property count updated to match the two new
 fields.
  * Existing `sideload` / `finalize` test coverage extended to assert the
 recomputed values after the controller's internal guards are removed.

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