[wp-trac] [WordPress Trac] #64737: REST API: Add 'scaled' image size to the sideload route

[WordPress Trac]

#64737: REST API: Add 'scaled' image size to the sideload route
-----------------------------+-----------------------------
 Reporter:  adamsilverstein  |      Owner:  adamsilverstein
     Type:  defect (bug)     |     Status:  assigned
 Priority:  normal           |  Milestone:  7.0
Component:  General          |    Version:  trunk
 Severity:  normal           |   Keywords:  has-patch
  Focuses:                   |
-----------------------------+-----------------------------
 The REST API sideload route (`/wp/v2/media/<id>/sideload`) currently
 supports sideloading sub-sizes (thumbnails, medium, large, etc.), the
 original image, and PDF thumbnails — but it does not support sideloading
 the '''scaled''' version of an image.

 When WordPress processes a large image upload, it creates a "scaled"
 version (via the big image size threshold) and stores the original
 filename in `original_image` metadata. For client-side media processing,
 the client needs to be able to sideload this scaled image in the same way
 it sideloads other sizes.

 == Problem ==

 Without `scaled` in the `image_size` enum, client-side media processing
 cannot replicate the server-side big image threshold behavior. The client
 has no way to:

 * Upload a scaled-down version of a large image and have WordPress treat
 it as the primary attached file
 * Record the original filename in `original_image` metadata, matching
 server-side behavior
 * Update the attachment metadata (`width`, `height`, `filesize`, `file`)
 to reflect the scaled version

 == Solution ==

 This patch adds `'scaled'` to the `image_size` enum on the sideload route
 and implements the corresponding logic in `sideload_item()`:

 1. '''Route registration:''' Adds `'scaled'` to the `$valid_image_sizes`
 array so the sideload endpoint accepts it.
 2. '''Sideload handling:''' When `image_size` is `'scaled'`:
    * Records the current attached file as `original_image` in metadata
 (preserving the original).
    * Calls `update_attached_file()` to point the attachment to the new
 scaled file.
    * Updates `width`, `height`, `filesize`, and `file` in the attachment
 metadata.
    * Validates that `get_attached_file()` returns a valid path before
 proceeding.
 3. '''Unique filename handling:''' Updates the `filter_wp_unique_filename`
 regex to recognize the `-scaled` suffix (alongside the existing
 `-{width}x{height}` pattern), preventing WordPress from appending numeric
 disambiguators to scaled filenames.
 4. '''Tests:''' Adds unit tests covering:
    * Successful sideload of a scaled image with correct metadata updates.
    * Authentication requirement enforcement.
    * Verification that `'scaled'` is present in the route's `image_size`
 enum.
    * Correct unique filename behavior with the `-scaled` suffix.
 5. '''JS fixtures:''' Updates the auto-generated JS API fixture to reflect
 the new enum value.

 == References ==

 * PR: [https://github.com/WordPress/wordpress-develop/pull/11015 #11015]

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