Media REST API: Fix sideload and finalize for EXIF rotated images

[andrewserong]

What?

Part of:

• Media: Where should EXIF rotation belong — server, client, or hybrid? #77582

Update the logic for 'original' sized images in sideload and finalize to account for rotated images. To do so, essentially reuse the same logic that we have for the scaled size.

My thinking here is: when the client uploads a rotated image to upload as the original, it's very similar to the scaled logic, which is that we're effectively saying "please use this one, but point back to the original".

Part of this is also at the finalize step, declaring that the image has been rotated and that the image rotation should be treated as 1 (i.e. already handled).

Note: I haven't put up a backport of this PR just yet as I'm still a little unsure if it's the right approach. If it looks okay, happy to do that, though!

Why?

Fixes a bug described in #77582 (comment)

Basically, with some EXIF rotated images (e.g. 6), we'd get a 400 error from sideload requests for the original size because the dimensions did not match what the server expected.

But, in the client-side media upload flow, we expect something like:

• The client uploads the original file (which might be unrotated)
• The client then proceeds to process that original file and performs rotation and sub-size generation, etc
• The client then sideloads those sub-sizes and rotated original
• The client then fires off a finalize request
• So, at the end of all that, the REST API requests should treat the finalize / original sideload as "the client gave us the final version of these where the rotation has occurred"... or something like that

I'm a little hesitant about this PR because I don't fully understand the implications of re-using the logic like this. So I'll likely need to lean on @adamsilverstein for verification here!

How?

• In the sideload and finalize steps, treat

Testing Instructions

Download the raw version of this file: https://github.com/WordPress/gutenberg/blob/trunk/packages/vips/src/test/fixtures/exif-rotated-90cw.jpg

• Add an image block to a post
• Upload that file to the post

In trunk this fails with a 400 error. In this PR, it should successfully upload.

With your network inspector open, select the block after upload, and look for the media REST API request that returns the attachment response. Double-check the response and that the image sizes and other metadata look correct, including original_image.

Screenshots or screencast

Before

After

Use of AI Tools

Claude Code and then Codex to verify the fix from Claude. This seemed to confirm that the fix needs to happen on the PHP side and not the JS side.

[Copilot]

Pull request overview

Updates the Gutenberg Media REST API client-side upload flow so the original sideload/finalize path correctly handles EXIF quarter-turn rotations (where width/height are transposed), aligning behavior more closely with WordPress core’s “replace original” semantics and preventing rest_upload_dimension_mismatch 400s.

Changes:

• Treat image_size=original sideloads like scaled: swap the attachment’s main file and track the replaced file as original_image.
• In finalize, apply original sub-size metadata to the attachment (including resetting stored EXIF orientation to 1 to avoid re-rotation on refetch).
• Relax original dimension validation to accept either exact dimensions or a width/height transpose.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
lib/media/class-gutenberg-rest-attachments-controller.php	Updates sideload/finalize handling for original, resets orientation to avoid double-rotation, and allows transposed dimensions in validation.
phpunit/media/class-gutenberg-rest-attachments-controller-test.php	Renames/updates the existing original sideload test and adds regression/behavioral tests covering transposed dimensions and parity with server-side rotation behavior.

[github-actions]

Flaky tests detected in 409b1e1.
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/29472952588
📝 Reported issues:

• [Flaky Test] adds and activates a new tab when pressing Enter at the end of a tab label #80106 in /test/e2e/specs/editor/blocks/tabs.spec.js

[ramonjd]

Did a quick test, and it fixes the 400. But so far it's also fixing the rotation bug I was trying to address over in WordPress/wordpress-develop#12492

2 birds with one stone!

[ramonjd]

But so far it's also fixing the rotation bug I was trying to address over in WordPress/wordpress-develop#12492

2 birds with one stone!

Sorry, I withdraw that. I was testing with the wrong image. No 400s though!

[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: andrewserong <andrewserong@git.wordpress.org>
Co-authored-by: adamsilverstein <adamsilverstein@git.wordpress.org>
Co-authored-by: ramonjd <ramonopoly@git.wordpress.org>

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

[adamsilverstein]

Thanks for the PR! I will test it soon.

[adamsilverstein]

@andrewserong this tested well for me trying jpeg, heic, and avif rotated images (from packages/vips/src/test/fixtures). One small glitch I noticed with the avif - it shows faded out in the horizontal position while processing, then switches to the correct vertical alignment when completed:

initially:

after upload complete:

The other test images show the correct orientation immediately.

[adamsilverstein]

The other test images show the correct orientation immediately.

Looking into this further.

[adamsilverstein]

The other test images show the correct orientation immediately.

Looking into this further.

ps. its easy to reproduce by starting the upload while offline.

[andrewserong]

One small glitch I noticed with the avif - it shows faded out in the horizontal position while processing, then switches to the correct vertical alignment when completed:

Good catch! My best guess is that during the uploading preview, the browser is doing its best to render things as is (i.e. for jpegs, etc, it'll display with the rotation as it can, but this isn't supported for avif?)

Separately, looks like the PHP unit tests are failing due to -1 being appended. I'll take a look at that.

[adamsilverstein]

Pushed a few follow-ups after reviewing:

• Applied the orientation reset to the scaled finalize branch too and merged the two branches: core resets orientation in both its scale and rotate paths in wp_create_image_subsizes(), and vips has already applied rotation to scaled images client-side.
• Guarded finalize against original/scaled entries missing file, so a malformed payload can't blank out the main-file metadata.
• Fixed the failing PHP tests: they hardcoded canola.jpg, but wp_unique_filename() adds a numeric suffix when earlier tests in the suite upload the same fixture. They now assert against the actual attached-file basename (same fix you pushed, @andrewserong - I merged both). Also added skip guards for environments without exif/rotate support.
• Opened the core backport Media REST API: Fix sideload and finalize for EXIF rotated images wordpress-develop#12550 and added the backport-changelog/7.1/12550.md entry, which should clear the backport changelog check.

On the approach question: this is a faithful port of core's rotate path. wp_create_image_subsizes() saves a -rotated file, calls _wp_image_meta_replace_original() (attached-file swap + width/height/file/filesize + keeps the upload as original_image), then resets orientation to 1 - exactly what this PR now does across sideload/finalize. The previous behavior (rotated file stored as original_image) was backwards relative to core.

On the AVIF preview glitch I mentioned above: expected browser behavior, not a bug in this PR. The rotated AVIF fixtures signal rotation only via EXIF; per the AVIF/MIAF spec renderers apply irot/imir and ignore EXIF orientation, so Chrome renders the raw-file blob preview un-rotated while uploading, then the block switches to the rotated server file when processing completes. JPEG previews correctly because browsers do honor EXIF for JPEG, and HEIC goes through client-side conversion before preview. If we want the transient preview correct for EXIF-only AVIF/HEIF, the client could swap the preview to the vips-rotated file once it's produced - follow-up material.

[andrewserong]

Fantastic, thanks so much @adamsilverstein, much appreciated! Your updates look good to me.

Do you want to give this an approval and then I can merge it?

Opened the core backport WordPress/wordpress-develop#12550 and added the backport-changelog/7.1/12550.md entry, which should clear the backport changelog check.

Super, thanks for that. I can give that a look shortly.

[andrewserong]

Backport looks good and I've given it the ✅. Just updated a stale comment, but otherwise I think this one is good to go 🤞

[adamsilverstein]

Nice one!

[ramonjd]

LGTM - works as described, thanks folks!

[andrewserong]

Thanks for all the collaboration here! 🙇

[github-actions]

I just cherry-picked this PR to the wp/7.1 branch to get it included in the next release: b39c633

[t-hamano]

I just cherry-picked this PR to the release/23.6 branch to get it included in the next release: 6f41b85