REST API: Add 'scaled' to sideload route image_size enum by adamsilverstein · Pull Request #11015 · WordPress/wordpress-develop

adamsilverstein · 2026-02-23T11:08:46Z

Summary

When client-side media processing handles big image scaling, the client creates a -scaled version and sideloads it back via the REST API. The sideload route's image_size enum was missing scaled, causing 400 validation errors.

This PR:

Adds 'scaled' to the image_size enum in the sideload route registration
Adds handling in sideload_item() to record the original file as original_image and update the attachment to point to the scaled version
Updates the filter_wp_unique_filename() regex to recognize the -scaled suffix, preventing unwanted numeric suffixes

Test plan

Upload a large image (>2560px) with client-side media processing enabled
Confirm the scaled sideload request no longer returns a 400 error
Verify that other sideload image_sizes (thumbnail, medium, etc.) still work
Verify the attachment metadata correctly records original_image and the scaled file dimensions
Test with and without the Gutenberg plugin active

Trac ticket: https://core.trac.wordpress.org/ticket/64737

When client-side media processing handles big image scaling, the client creates a -scaled version and sideloads it back. The sideload route's image_size enum was missing 'scaled', causing 400 validation errors. This adds 'scaled' to the enum, adds handling in sideload_item() to record the original file and update the attachment to point to the scaled version, and updates the unique filename filter regex to recognize the -scaled suffix.

github-actions · 2026-02-23T11:08:58Z

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.

Core Committers: Use this line as a base for the props when committing in SVN:

Props adamsilverstein, huzaifaalmesbah, westonruter.

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

github-actions · 2026-02-23T11:16:51Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

Add 'scaled' to the image_size enum in wp-api-generated.js to match the PHP route registration change, fixing the git diff --exit-code CI check. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add tests for the new 'scaled' image_size enum value in the sideload endpoint: verifying metadata updates, authentication requirements, route schema, and unique filename handling for the -scaled suffix. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

get_attached_file() can return false when no file is attached. Add a guard to return a WP_Error before calling wp_basename() with a falsy value.

The sideload route uses edit_media_item_permissions_check which returns rest_cannot_edit_image, not rest_forbidden.

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

westonruter · 2026-03-02T05:07:50Z

src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php


 		$matches = array();
-		if ( preg_match( '/(.*)(-\d+x\d+)-' . $number . '$/', $name, $matches ) ) {
+		if ( preg_match( '/(.*)(-\d+x\d+|-scaled)-' . $number . '$/', $name, $matches ) ) {


According to the PHPDoc, $number can be a string. When? What would it be in that case? Does it need to be escaped?

maybe it can't be a string, let me check. escaping is rarely a bad idea.

I decided to cast this as int for safety. According to Claude here is the logic (and why it can be a string):

Looking at wp_unique_filename() in src/wp-includes/functions.php:

$number is initialized as '' (empty string) at line 2561

Set to integer 1 at line 2588 when the filename matches a subsize pattern

Incremented via (int) $number + 1 in while loops (lines 2624, 2697, 2758)

Passed to the wp_unique_filename filter at line 2799

Possible values: empty string '' or positive integers (1, 2, 3, ...).

ae029f1ac2619570fab7398bba82b1a5143d38d7

Ah, I see. It passes an empty string in case it is not used, per the phpdoc. In that case, what about:

--- a/src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php +++ b/src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php @@ -2135,7 +2135,7 @@ class WP_REST_Attachments_Controller extends WP_REST_Posts_Controller { * @return string Filtered file name. */ private static function filter_wp_unique_filename( $filename, $dir, $number, $attachment_filename ) { - if ( empty( $number ) || ! $attachment_filename ) { + if ( ! is_int( $number ) || ! $attachment_filename ) { return $filename; } @@ -2148,7 +2148,7 @@ class WP_REST_Attachments_Controller extends WP_REST_Posts_Controller { } $matches = array(); - if ( preg_match( '/(.*)(-\d+x\d+|-scaled)-' . (int) $number . '$/', $name, $matches ) ) { + if ( preg_match( '/(.*)(-\d+x\d+|-scaled)-' . $number . '$/', $name, $matches ) ) { $filename_without_suffix = $matches[1] . $matches[2] . ".$ext"; if ( $matches[1] === $orig_name && ! file_exists( "$dir/$filename_without_suffix" ) ) { return $filename_without_suffix;

Addresses review feedback to assert the value of metadata['file'], not just its existence.

Avoids repeating the string literal for the array key in the enum assertion test.

Verifies that sideloading a scaled image retains the numeric suffix when a file with the same name already exists from a different attachment.

The $number parameter in filter_wp_unique_filename is typed as int|string. Casting to (int) before interpolation into the preg_match pattern ensures regex safety regardless of any future changes to what $number might contain.

adamsilverstein · 2026-03-03T03:45:17Z

@westonruter I believe I have addressed all of your feedback. Thanks!

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

src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php

westonruter · 2026-03-03T06:11:54Z

src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php

+
+			$metadata['width']    = $size ? $size[0] : 0;
+			$metadata['height']   = $size ? $size[1] : 0;
+			$metadata['filesize'] = wp_filesize( $path );


Note that wp_filesize() is filterable and can return 0. Does it make sense to proceed with any of this if any of these are zero?

Should these checks be done first and then if all of them aren't zero, then proceed with update_attached_file( $attachment_id, $path )? Otherwise, if one is zero, short-circuit with an error?

maybe, let me check the existing pattern in core since i'm just trying to store meta data for the image.

src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php

westonruter · 2026-03-03T06:17:01Z

src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php


 		$matches = array();
-		if ( preg_match( '/(.*)(-\d+x\d+)-' . $number . '$/', $name, $matches ) ) {
+		if ( preg_match( '/(.*)(-\d+x\d+|-scaled)-' . (int) $number . '$/', $name, $matches ) ) {


cf. changes done in #11100

I'll move the changes there here, the change belongs here

src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php

Co-authored-by: Weston Ruter <westonruter@gmail.com>

Check whether _wp_attached_file already matches $path before calling update_attached_file(), since a false return could mean the value is unchanged. Return a WP_Error when the meta value differs but the update still fails.

Per review feedback, use ! is_int( $number ) as the guard since $number is either an int or an empty string. This is more precise than empty() and allows removing the (int) cast in the regex since $number is guaranteed to be an int.

Checks image dimensions and filesize before calling update_attached_file() to avoid leaving the attachment in a bad state if the scaled file is unreadable or empty.

Move the literal dash outside the capture group so the regex reads `/(.*)-(\d+x\d+|scaled)-/` instead of alternating `(-\d+x\d+|-scaled)`. This keeps the dash handling consistent and simplifies the filename reconstruction. Props westonruter. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

westonruter

One last suggestion, but otherwise pre-approving.

westonruter · 2026-03-03T18:38:09Z

src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php

+
+			// Update the attached file to point to the scaled version.
+			if (
+				get_post_meta( $attachment_id, '_wp_attached_file', true ) !== $path &&


Gemini wisely pointed out that the _wp_attached_file post meta is stored as a relative path, whereas $path is an absolute path. So this actually will never be equal. It suggests this instead, which also looks cleaner:

Suggested change

get_post_meta( $attachment_id, '_wp_attached_file', true ) !== $path &&

get_attached_file( $attachment_id, true ) !== $path &&

The true prevents filters from applying.

adamsilverstein mentioned this pull request Feb 23, 2026

Fix client-side media file naming WordPress/gutenberg#75817

Merged

4 tasks

github-actions bot mentioned this pull request Feb 24, 2026

PHP backports for WP 7.0 WordPress/gutenberg#74043

Open

adamsilverstein and others added 5 commits February 26, 2026 18:15

Merge branch 'trunk' into add-scaled-to-sideload-route

3832e25

REST API: Update auto-generated JS fixture for sideload route.

0dcab83

Add 'scaled' to the image_size enum in wp-api-generated.js to match the PHP route registration change, fixing the git diff --exit-code CI check. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

REST API: Validate get_attached_file() in sideload

133ec0f

get_attached_file() can return false when no file is attached. Add a guard to return a WP_Error before calling wp_basename() with a falsy value.

Tests: Fix expected error code in sideload auth test

a868b57

The sideload route uses edit_media_item_permissions_check which returns rest_cannot_edit_image, not rest_forbidden.

huzaifaalmesbah reviewed Feb 26, 2026

View reviewed changes

tests/phpunit/tests/rest-api/rest-attachments-controller.php Outdated Show resolved Hide resolved

adamsilverstein mentioned this pull request Mar 1, 2026

REST API: Add dimension validation to sideload endpoint #11100

Open

2 tasks

fix ticket number for test annotations

e5baa99

adamsilverstein requested review from huzaifaalmesbah, swissspidy and westonruter and removed request for huzaifaalmesbah March 2, 2026 04:24

Merge branch 'trunk' into add-scaled-to-sideload-route

5405e38

westonruter reviewed Mar 2, 2026

View reviewed changes

adamsilverstein added 3 commits March 3, 2026 10:26

Merge branch 'trunk' into add-scaled-to-sideload-route

02a9794

Add value assertion for metadata file key

458d94c

Addresses review feedback to assert the value of metadata['file'], not just its existence.

Extract image_size key into variable

978ac79

Avoids repeating the string literal for the array key in the enum assertion test.

adamsilverstein self-assigned this Mar 3, 2026

adamsilverstein added 2 commits March 3, 2026 10:37

Add test for scaled filename numeric suffix on conflict

eeca10e

Verifies that sideloading a scaled image retains the numeric suffix when a file with the same name already exists from a different attachment.

Cast $number to int in regex for safety

ae029f1

The $number parameter in filter_wp_unique_filename is typed as int|string. Casting to (int) before interpolation into the preg_match pattern ensures regex safety regardless of any future changes to what $number might contain.

westonruter reviewed Mar 3, 2026

View reviewed changes

tests/phpunit/tests/rest-api/rest-attachments-controller.php Outdated Show resolved Hide resolved

westonruter reviewed Mar 3, 2026

View reviewed changes

src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php Outdated Show resolved Hide resolved

westonruter reviewed Mar 3, 2026

View reviewed changes

src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php Show resolved Hide resolved

westonruter reviewed Mar 3, 2026

View reviewed changes

src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php Outdated Show resolved Hide resolved

adamsilverstein and others added 7 commits March 3, 2026 16:58

Apply suggestion from @westonruter

a484e07

Co-authored-by: Weston Ruter <westonruter@gmail.com>

Apply suggestion from @westonruter

fbe7458

Co-authored-by: Weston Ruter <westonruter@gmail.com>

Handle update_attached_file failure in sideload

b30edb6

Check whether _wp_attached_file already matches $path before calling update_attached_file(), since a false return could mean the value is unchanged. Return a WP_Error when the meta value differs but the update still fails.

Use is_int check instead of empty for $number

56c05e4

Per review feedback, use ! is_int( $number ) as the guard since $number is either an int or an empty string. This is more precise than empty() and allows removing the (int) cast in the regex since $number is guaranteed to be an int.

Validate scaled image before updating attached file

d558ceb

Checks image dimensions and filesize before calling update_attached_file() to avoid leaving the attachment in a bad state if the scaled file is unreadable or empty.

Merge branch 'trunk' into add-scaled-to-sideload-route

0743a97

westonruter approved these changes Mar 3, 2026

View reviewed changes

	get_post_meta( $attachment_id, '_wp_attached_file', true ) !== $path &&
	get_attached_file( $attachment_id, true ) !== $path &&

Conversation

adamsilverstein commented Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

github-actions bot commented Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Feb 23, 2026

Test using WordPress Playground

Some things to be aware of

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamsilverstein Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamsilverstein commented Mar 3, 2026

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamsilverstein Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

westonruter left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

adamsilverstein commented Feb 23, 2026 •

edited

Loading

github-actions bot commented Feb 23, 2026 •

edited

Loading

adamsilverstein Mar 3, 2026 •

edited

Loading

adamsilverstein Mar 3, 2026 •

edited

Loading