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

ramonjd · 2025-09-24T04:29:50Z

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.

Resolves #71863

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

Why?

As outlined in #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.

How?

Adds new controller and override existing endpoint
Avoids conflicts with existing media endpoint extension for the media processing experiment by renaming it to Gutenberg_Media_Processing_REST_Attachments_Controller.

Testing Instructions

For the new tests:

npm run test:unit:php:base -- --filter Gutenberg_REST_Attachments_Controller_Test

Ensure that all tests pass (after updates to media processing tests)

npm run test:unit:php

Manual testing

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

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

Media processing experiment smoke testing

If you have time, smoke test the media processing experiment since this PR changes a few of the hooks and class names:

(Taken from #70623)

Ensure experiments->client side media is enabled
Upload an image in the block editor
Monitor the network panel for activity as each image is updated. Check the files saved to the server and compare them to the files generated when the feature is not enabled.

…erride existing endpoint - Introduced `Gutenberg_Media_Processing_REST_Attachments_Controller` to manage attachment endpoints. - Updated `gutenberg_filter_attachment_post_type_args` to use the new controller. - Added functionality to override the REST controller for the `attachment` post type. - Removed the deprecated `Gutenberg_REST_Attachments_Controller` and its associated tests. This change improves the handling of media processing in the Gutenberg editor.

…ng and consistency - Updated PHP files to ensure consistent indentation and formatting in `Gutenberg_REST_Attachments_Controller`, `rest-api.php`, and associated test files. - Enhanced readability by aligning comments and code structure. - Ensured all files end with a newline for better compatibility. These changes contribute to cleaner code and maintainability in the Gutenberg REST API for attachments.

github-actions · 2025-09-24T04:38:39Z

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: ramonjd <[email protected]>
Co-authored-by: andrewserong <[email protected]>
Co-authored-by: swissspidy <[email protected]>

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

- Added exclusion for `mock-image-editor.php` in `phpcs.xml.dist` to prevent linting errors. - Enhanced documentation in `mock-image-editor.php` to clarify its purpose and usage in tests, including a reference to the corresponding class in WordPress Core. These changes improve code quality and maintainability in the testing environment.

…and update filter - Removed the unused `$post_type` parameter from `gutenberg_filter_attachment_post_type_args` function. - Updated the `add_filter` call to reflect the change in the number of accepted arguments. These changes enhance code clarity and maintainability in the Gutenberg media processing functionality.

ramonjd · 2025-09-24T04:53:13Z

lib/experimental/media/class-gutenberg-media-processing-rest-attachments-controller.php

+ * Class Gutenberg_Media_Processing_REST_Attachments_Controller.
 */
-class Gutenberg_REST_Attachments_Controller extends WP_REST_Attachments_Controller {
+class Gutenberg_Media_Processing_REST_Attachments_Controller extends Gutenberg_REST_Attachments_Controller {


Extending non-experimental attachment class to avoid naming conflicts.

ramonjd · 2025-09-24T04:53:41Z

phpunit/includes/mock-image-editor.php

+<?php
+
+/**
+ * Mock image editor for testing.


Required to mock the image editor class.

ramonjd · 2025-09-24T04:54:55Z

lib/experimental/media/load.php

 	return $args;
 }

-add_filter( 'register_post_type_args', 'gutenberg_filter_attachment_post_type_args', 10, 2 );


The register_attachment_post_type_args filter is more specific and runs after the general register_post_type_args filter.

This ensures the integrity of the inheritance chain:

WP_REST_Attachments_Controller ↓ Gutenberg_REST_Attachments_Controller (WordPress 6.9 compatibility) ↓ Gutenberg_Media_Processing_REST_Attachments_Controller (Media experiment)

cc @swissspidy or @adamsilverstein for a confidence check and whether you needed register_post_type_args specifically. I smoke tested the media processing experiment and couldn't find any issues.

ramonjd · 2025-09-24T04:55:30Z

phpunit/experimental/media/media-processing-test.php

-		$this->assertSame(
-			array(),
-			gutenberg_filter_attachment_post_type_args( array(), 'post' )
-		);


No longer required due to switch to register_attachment_post_type_args

ramonjd · 2025-09-24T04:57:25Z

lib/compat/wordpress-6.9/class-gutenberg-rest-attachments-controller.php

+				case 'flip':
+					/*
+					 * Flips the current image.
+					 * The vertical flip is the first argument (flip along horizontal axis), the horizontal flip is the second argument (flip along vertical axis).
+					 * See: WP_Image_Editor::flip()
+					 */
+					$result = $image_editor->flip( 0 !== (int) $args['flip']['vertical'], 0 !== (int) $args['flip']['horizontal'] );
+					if ( is_wp_error( $result ) ) {
+						return new WP_Error(
+							'rest_image_flip_failed',
+							__( 'Unable to flip this image.', 'gutenberg' ),
+							array( 'status' => 500 )
+						);
+					}
+					break;


Flips image.

ramonjd · 2025-09-24T04:58:08Z

lib/compat/wordpress-6.9/class-gutenberg-rest-attachments-controller.php

+		$original_attachment_post = get_post( $attachment_id );
+
+		// Check request fields and assign default values.
+		$new_attachment_post                 = $this->prepare_item_for_database( $request );


Sets and sanitizes any incoming caption, description, and title, post and alt_text fields

lib/compat/wordpress-6.9/class-gutenberg-rest-attachments-controller.php

github-actions · 2025-09-24T05:18:44Z

Flaky tests detected in 2904c80.
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/17967475714
📝 Reported issues:

[Flaky Test] should refresh the page when stylesheet loading fails #71722 in /test/e2e/specs/interactivity/router-styles.spec.ts

…ntroller - Updated the `Gutenberg_REST_Attachments_Controller` to handle both vertical and horizontal flipping of images by modifying the request structure. - Refactored the test case to reflect the new functionality, adding a separate test for vertical flipping.

swissspidy · 2025-09-24T06:44:36Z

Since this doesn't affect any functionality in Gutenberg, I don't see why the PR is made against this repo. I strongly suggest making a PR for WP core directly.

ramonjd · 2025-09-24T07:01:52Z

Since this doesn't affect any functionality in Gutenberg, I don't see why the PR is made against this repo.

Yet.

It's here for the case where follow up experiments, that rely on these changes, are added to the plugin. There are a couple of things we'd like to try so best to be flexible.

Edit: if it's looking like we run out of time to do any of these things before 6.9 beta then I can revert if eventually gets in.

ramonjd · 2025-09-24T07:19:47Z

There are a couple of things we'd like to try so best to be flexible.
making a PR for WP core directly

On reflection, looking at the back-of-the-napkin list (try flip controls in the block editor, experimental new media library package just for example), I think I've changed my mind. I'll get the backport up tomorrow and close this PR given the 6.9 timeline.

Any development can be done on the back of the WordPress trunk branch I suppose.

Thanks for the nudge.

ramonjd · 2025-09-25T05:10:47Z

Closing in favor of WordPress/wordpress-develop#10041

ramonjd self-assigned this Sep 24, 2025

ramonjd requested a review from spacedmonkey as a code owner September 24, 2025 04:29

ramonjd added REST API Interaction Related to REST API [Block] Image Affects the Image Block Needs PHP backport Needs PHP backport to Core labels Sep 24, 2025

ramonjd requested review from andrewserong, swissspidy, talldan and tellthemachines September 24, 2025 04:30

ramonjd added the [Type] Enhancement A suggestion for improvement. label Sep 24, 2025

ramonjd added 2 commits September 24, 2025 14:47

ramonjd commented Sep 24, 2025

View reviewed changes

ramonjd changed the title ~~Media Editor: update attachments controller to support flip and to customize attachment fields.~~ Media / Attachments REST API endpoint: update attachments controller to support flip and to customize attachment fields. Sep 24, 2025

andrewserong reviewed Sep 24, 2025

View reviewed changes

lib/compat/wordpress-6.9/class-gutenberg-rest-attachments-controller.php Outdated Show resolved Hide resolved

ramonjd mentioned this pull request Sep 24, 2025

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

Closed

ramonjd closed this Sep 25, 2025

ramonjd deleted the update/attachments-controller-edit-flip-editable-fields branch September 25, 2025 05:10

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

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

Uh oh!

Conversation

ramonjd commented Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Testing Instructions

Manual testing

Media processing experiment smoke testing

Uh oh!

github-actions bot commented Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ramonjd Sep 24, 2025

Choose a reason for hiding this comment

Uh oh!

ramonjd Sep 24, 2025

Choose a reason for hiding this comment

Uh oh!

ramonjd Sep 24, 2025

Choose a reason for hiding this comment

Uh oh!

ramonjd Sep 24, 2025

Choose a reason for hiding this comment

Uh oh!

ramonjd Sep 24, 2025

Choose a reason for hiding this comment

Uh oh!

ramonjd Sep 24, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

swissspidy commented Sep 24, 2025

Uh oh!

ramonjd commented Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ramonjd commented Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ramonjd commented Sep 25, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ramonjd commented Sep 24, 2025 •

edited

Loading

github-actions bot commented Sep 24, 2025 •

edited

Loading

github-actions bot commented Sep 24, 2025 •

edited

Loading

ramonjd commented Sep 24, 2025 •

edited

Loading

ramonjd commented Sep 24, 2025 •

edited

Loading