REST API: Add finalize endpoint to WP_REST_Attachments_Controller by adamsilverstein · Pull Request #11168 · WordPress/wordpress-develop

adamsilverstein · 2026-03-05T06:52:04Z

Summary

Adds a POST /wp/v2/media/{id}/finalize REST API endpoint to WP_REST_Attachments_Controller
The endpoint triggers the wp_generate_attachment_metadata filter with context 'update' after client-side media processing completes
Ensures server-side plugins (watermarking, CDN sync, custom sizes, etc.) can post-process attachments when client-side processing is active
Only registered when wp_is_client_side_media_processing_enabled() returns true

Context

When client-side media processing handles image uploads (resizing, thumbnail generation, format conversion), server-side WordPress hooks like wp_generate_attachment_metadata are bypassed. This endpoint is called after all client-side operations (upload, thumbnail generation, sideloads) are complete, re-triggering the filter so plugins continue to work.

Hook usage example

add_filter( 'wp_generate_attachment_metadata', function( $metadata, $attachment_id, $context ) {
  // $context is 'update' when called from the finalize endpoint.
  if ( 'update' === $context ) {
    // Add watermark, sync to CDN, generate custom sizes, etc.
    my_plugin_process_attachment( $attachment_id, $metadata );
  }
  return $metadata;
}, 10, 3 );

Changes

File	Change
`class-wp-rest-attachments-controller.php`	Add `finalize` route registration, `finalize_item_permissions_check()`, and `finalize_item()` methods
`rest-attachments-controller.php` (tests)	Add tests for finalize endpoint (success, auth required, invalid ID)
`rest-schema-setup.php`	Add finalize route to expected routes list
`wp-api-generated.js`	Add finalize route to API fixtures

Test plan

Verify finalize endpoint returns 200 with valid attachment
Verify wp_generate_attachment_metadata filter fires with context 'update'
Verify 401 when not authenticated
Verify 404 for invalid attachment ID
Run full REST API test suite

Add a `POST /wp/v2/media/{id}/finalize` endpoint that triggers the `wp_generate_attachment_metadata` filter after client-side media processing completes. This ensures server-side plugins (e.g., for watermarking, CDN sync, custom sizes) can post-process attachments when client-side processing is active. The endpoint: - Reuses `edit_media_item_permissions_check` for authorization - Re-applies `wp_generate_attachment_metadata` with context 'update' - Updates attachment metadata and returns the updated attachment - Is only registered when client-side media processing is enabled Props adamsilverstein. See #62243. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

github-actions · 2026-03-05T06:53:28Z

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.

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

github-actions · 2026-03-05T07:03:13Z

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.

westonruter · 2026-03-06T02:51:22Z

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

+
+			register_rest_route(
+				$this->namespace,
+				'/' . $this->rest_base . '/(?P<id>[\d]+)/finalize',


The brackets aren't necessary.

Suggested change

'/' . $this->rest_base . '/(?P<id>[\d]+)/finalize',

'/' . $this->rest_base . '/(?P<id>\d+)/finalize',

But I guess the other endpoints have the similar pattern.

westonruter · 2026-03-06T02:53:00Z

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

+	 * @param WP_REST_Request $request Full details about the request.
+	 * @return true|WP_Error True if the request has access, WP_Error object otherwise.
+	 */
+	public function finalize_item_permissions_check( $request ) {


Suggested change

public function finalize_item_permissions_check( $request ) {

public function finalize_item_permissions_check( WP_REST_Request $request ) {

westonruter · 2026-03-06T02:54:57Z

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

+
+		return $this->prepare_item_for_response( get_post( $attachment_id ), $response_request );
+	}
+


Suggested change

westonruter · 2026-03-06T02:55:16Z

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

+			$response_request['_fields'] = $request['_fields'];
+		}
+
+		return $this->prepare_item_for_response( get_post( $attachment_id ), $response_request );


Can this re-use the $post which was obtained above?

Suggested change

return $this->prepare_item_for_response( get_post( $attachment_id ), $response_request );

return $this->prepare_item_for_response( $post, $response_request );

westonruter · 2026-03-06T02:55:27Z

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

+
+		$this->assertErrorResponse( 'rest_post_invalid_id', $response, 404 );
+	}
+


Suggested change

westonruter · 2026-03-06T02:56:15Z

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

+		$attachment_id = $request['id'];
+
+		$post = $this->get_post( $attachment_id );
+


Suggested change

westonruter · 2026-03-06T02:56:23Z

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

+		}
+
+		$metadata = wp_get_attachment_metadata( $attachment_id );
+


Suggested change

westonruter · 2026-03-06T02:58:02Z

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

+		/** This filter is documented in wp-admin/includes/image.php */
+		$metadata = apply_filters( 'wp_generate_attachment_metadata', $metadata, $attachment_id, 'update' );
+
+		wp_update_attachment_metadata( $attachment_id, $metadata );


I guess it doesn't make sense to check the return value here for failure since it returns false if the updated post meta is the same.

mukeshpanchal27 · 2026-03-06T04:56:33Z

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

+					array(
+						'methods'             => WP_REST_Server::CREATABLE,
+						'callback'            => array( $this, 'finalize_item' ),
+						'permission_callback' => array( $this, 'finalize_item_permissions_check' ),


Shell we use edit_media_item_permissions_check directly as the new method class that function and return the value?

westonruter reviewed Mar 6, 2026

View reviewed changes

mukeshpanchal27 reviewed Mar 6, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

REST API: Add finalize endpoint to WP_REST_Attachments_Controller#11168

REST API: Add finalize endpoint to WP_REST_Attachments_Controller#11168
adamsilverstein wants to merge 1 commit intoWordPress:trunkfrom
adamsilverstein:backport-finalize-endpoint

adamsilverstein commented Mar 5, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 5, 2026

Uh oh!

github-actions bot commented Mar 5, 2026

Uh oh!

westonruter Mar 6, 2026

Uh oh!

westonruter Mar 6, 2026

Uh oh!

westonruter Mar 6, 2026

Uh oh!

westonruter Mar 6, 2026

Uh oh!

westonruter Mar 6, 2026

Uh oh!

westonruter Mar 6, 2026

Uh oh!

westonruter Mar 6, 2026

Uh oh!

westonruter Mar 6, 2026

Uh oh!

westonruter Mar 6, 2026

Uh oh!

mukeshpanchal27 Mar 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	'/' . $this->rest_base . '/(?P<id>[\d]+)/finalize',
	'/' . $this->rest_base . '/(?P<id>\d+)/finalize',

	public function finalize_item_permissions_check( $request ) {
	public function finalize_item_permissions_check( WP_REST_Request $request ) {


		return $this->prepare_item_for_response( get_post( $attachment_id ), $response_request );
		}


		$this->assertErrorResponse( 'rest_post_invalid_id', $response, 404 );
		}

		$attachment_id = $request['id'];

		$post = $this->get_post( $attachment_id );

Conversation

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

Uh oh!

Summary

Context

Hook usage example

Changes

Test plan

Related

Uh oh!

github-actions bot commented Mar 5, 2026

Uh oh!

github-actions bot commented Mar 5, 2026

Test using WordPress Playground

Some things to be aware of

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!

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!

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!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

adamsilverstein commented Mar 5, 2026 •

edited

Loading