Media uploading - declare convert_format as boolean arg on sideload route

[adamsilverstein]

What

Declares convert_format as a boolean arg on the /wp/v2/media/<id>/sideload route so REST coerces the incoming value before it reaches the handler.

Why

The sideload handler reads $request['convert_format'] at class-gutenberg-rest-attachments-controller.php:548 and the client sends convert_format: false in additionalData when uploading a HEIC companion. Because the arg was not declared, multipart/form-data delivered the value as the string "false", which evaluates truthy, so if ( ! $request['convert_format'] ) never fired and add_filter( 'image_editor_output_format', '__return_empty_array', 100 ) was skipped.

With the filter skipped, wp_unique_filename() retained the default HEIC→JPEG output-format mapping and ran its alt-extension collision check — which bumped the .heic original to -1 even though the JPEG derivative stayed at no suffix. On subsequent uploads of the same HEIC, the two filenames drifted further apart (HEIC -3, JPEG -2).

Declaring the arg mirrors what is already done for create_item's endpoint args and lets REST coerce "false" → PHP false. The filter fires, alt-ext is skipped during the sideload, and the HEIC and JPEG end up sharing the same numeric suffix on every upload.

How

• lib/media/class-gutenberg-rest-attachments-controller.php — add the convert_format boolean arg (default true) to the sideload route's args array, alongside generate_sub_sizes.
• phpunit/media/class-gutenberg-rest-attachments-controller-test.php — two new tests:
  • test_sideload_route_declares_convert_format_boolean asserts the route schema.
  • test_sideload_convert_format_false_suppresses_alt_ext_suffix simulates the HEIC-companion flow (PNG stand-in + PNG→JPEG mapping) and verifies the companion keeps the shared basename with no numeric suffix.

Both tests fail on trunk and pass with this change.

Testing instructions

1. npx wp-env run --env-cwd='wp-content/plugins/gutenberg' wordpress vendor/bin/phpunit -c phpunit.xml.dist --filter 'Gutenberg_REST_Attachments_Controller_Test'
2. Manually upload the same HEIC twice through the media library; verify the .heic original and .jpg derivative share the same numeric suffix (no suffix the first time, -1 the second, etc.) on the filesystem.

Closes #77564

cc @andrewserong

AI use

I prompted Claude Code to write this PR and reviewed and tested it manually.

[github-actions]

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.

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

Co-authored-by: adamsilverstein <adamsilverstein@git.wordpress.org>
Co-authored-by: andrewserong <andrewserong@git.wordpress.org>

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

[adamsilverstein]

I will plan to backport this to WordPress core once client side media is restored to core in WordPress/wordpress-develop#11324

[github-actions]

Flaky tests detected in f0b7ac5.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/24790568579
📝 Reported issues:

• [Flaky Test] post title and content are editable and blocks can be inserted #76524 in /test/e2e/specs/editor/various/post-content-focus-mode.spec.js
• [Flaky Test] should show the edited content after revert, clicking undo in the header toolbar, save and reload #67172 in /test/e2e/specs/site-editor/template-revert.spec.js

[adamsilverstein]

I verified this fixes the naming issue for the original heic upload. Uploading IMG_4301.HEIC, I see these files:

And this meta:

array (
  'width' => 1440,
  'height' => 2560,
  'file' => '2026/04/IMG_4301-scaled.jpg',
  'filesize' => 475361,
  'sizes' =>
  array (
    'thumbnail' =>
    array (
      'width' => 150,
      'height' => 150,
      'file' => 'IMG_4301-150x150.jpg',
      'mime-type' => 'image/jpeg',
      'filesize' => 6563,
    ),
    'medium' =>
    array (
      'width' => 168,
      'height' => 300,
      'file' => 'IMG_4301-168x300.jpg',
      'mime-type' => 'image/jpeg',
      'filesize' => 10117,
    ),
    'medium_large' =>
    array (
      'width' => 768,
      'height' => 1365,
      'file' => 'IMG_4301-768x1365.jpg',
      'mime-type' => 'image/jpeg',
      'filesize' => 151370,
    ),
    'large' =>
    array (
      'width' => 576,
      'height' => 1024,
      'file' => 'IMG_4301-576x1024.jpg',
      'mime-type' => 'image/jpeg',
      'filesize' => 89131,
    ),
    '1536x1536' =>
    array (
      'width' => 864,
      'height' => 1536,
      'file' => 'IMG_4301-864x1536.jpg',
      'mime-type' => 'image/jpeg',
      'filesize' => 190404,
    ),
    '2048x2048' =>
    array (
      'width' => 1152,
      'height' => 2048,
      'file' => 'IMG_4301-1152x2048.jpg',
      'mime-type' => 'image/jpeg',
      'filesize' => 321690,
    ),
    'custom-500' =>
    array (
      'width' => 500,
      'height' => 500,
      'file' => 'IMG_4301-500x500.jpg',
      'mime-type' => 'image/jpeg',
      'filesize' => 51923,
    ),
    'post-thumbnail' =>
    array (
      'width' => 1568,
      'height' => 2788,
      'file' => 'IMG_4301-1568x2788.jpg',
      'mime-type' => 'image/jpeg',
      'filesize' => 551148,
    ),
  ),
  'image_meta' =>
  array (
    'aperture' => '0',
    'credit' => '',
    'camera' => '',
    'caption' => '',
    'created_timestamp' => '0',
    'copyright' => '',
    'focal_length' => '0',
    'iso' => '0',
    'shutter_speed' => '0',
    'title' => '',
    'orientation' => '0',
    'keywords' =>
    array (
    ),
    'alt' => '',
  ),
  'original' => 'IMG_4301.heic',
  'original_image' => 'IMG_4301.jpg',
)

[andrewserong]

Looking good, and nice test coverage. Glad it was a simple fix!

Confirmed that the incrementing is now consistent across all files including the heic stored alongside all the generated image sizes: