Media / Attachments REST API endpoint: update attachments controller to support flip and to customize attachment fields

[ramonjd]

What?

This PR is the first step to enhance media editor capabilities as described in #55238 Phase 3: Collaboration > Media Library.

It adds the following functionality:

• the ability to flip an image horizontally and vertically
• the ability to send arguments to update the new image's caption, description, and title, post and alt_text fields.

Why?

As outlined in WordPress/gutenberg#55238, the extended functionality will allow folks to start experimenting with a redesigned media library.

It will also allow flip controls in the existing image block toolbar.

Testing Instructions

Unit tests

npm run test:php -- --filter WP_Test_REST_Attachments_Controller

Manual testing

Check that existing use of the media/{$id}/edit endpoint has no regressions:

1. Insert an image into a post
2. Click on the crop symbol in the toolbar of the image block
3. Edit and save the image.
4. Check in the Network tab of your browser's console that the POST to media/{$id}/edit took place with the correct payload.
5. Check that a new file has been created in the Media Library /wp-admin/upload.php

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

---

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

[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.

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

Props ramonopoly, mukesh27, isabel_brison, andrewserong.

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

[github-actions]

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

• The Plugin and Theme Directories cannot be accessed within Playground.
• 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.

[andrewserong]

I like this change, I think it's going to be really useful to be able to add both flip support and update metadata at the same time in a single API call 👍

For some of the failures, it looks like the b/tests/qunit/fixtures/wp-api-generated.js fixtures need to be updated? I'm not quite sure how to do that, but it looks like it's generated by this PHP function / test:

wordpress-develop/tests/phpunit/tests/rest-api/rest-schema-setup.php

Line 212 in 5d5235f

public function test_build_wp_api_client_fixtures() {

[andrewserong]

Ah, it looks like you can update the fixtures by running the PHP tests locally, but specifically the following appears to just run the init tests to regenerate those fixtures:

npm run test:php -- --filter "WP_Test_REST_Schema_Initialization"

[ramonjd]

For some of the failures, it looks like the b/tests/qunit/fixtures/wp-api-generated.js fixtures need to be updated?

Thanks! I had to look up a previous comment of mine to remind myself how to do it 😄

#5604 (comment)

[andrewserong]

This is testing great for me, and the code change looks good!

For testing within a JS context, I opened up the post editor, and did the following:

First, I added an image in the media library and grabbed its id from the URL. Then, opened up the block editor, and called the following in my browser console to grab the full source url (in my case the image id was 27) from media_details.sizes.full.source_url:

wp.apiFetch( { path: '/wp/v2/media/27' } );

Next, I ran the following using the url I copied above for the src param:

wp.apiFetch( { path: '/wp/v2/media/27/edit', method: 'POST', data: { flip: { 'horizontal': true, 'vertical': true }, src: 'http://localhost:8889/wp-content/uploads/2025/09/denver-airport-scaled.jpg' } } );

Then, I opened up the media library, and took a look at the newly created image, and the correct flip had been applied. I also manually tried the above snippet adding other fields (e.g. alt_text, caption, etc), and all worked nicely.

LGTM! I think between the added flip support and the ability to add metadata at the same time, it'll unlock some useful behaviour for future media library / editor explorations, but also should be useful for other kinds of consumers of the endpoint.

[andrewserong]

This is the tiniest of tiny nits (no need to change it), but when I saw the square brackets here, I thought it meant that it was indicating an array, rather than being included in the description to means the directions are horizontal and vertical. Would round brackets help the potential ambiguity?