Media: Add hooks and extension points for client-side media processing

backport-changelog/7.0/11168.md

@@ -0,0 +1,3 @@
+https://github.com/WordPress/wordpress-develop/pull/11168
+
+* https://github.com/WordPress/gutenberg/pull/74913

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

@@ -58,6 +58,26 @@ public function register_routes(): void {
 			),
 			true // Override core's route so 'scaled' is included in the enum.
 		);
+
+		register_rest_route(
+			$this->namespace,
+			'/' . $this->rest_base . '/(?P<id>[\d]+)/finalize',
+			array(
+				array(
+					'methods'             => WP_REST_Server::CREATABLE,
+					'callback'            => array( $this, 'finalize_item' ),
+					'permission_callback' => array( $this, 'edit_media_item_permissions_check' ),
+					'args'                => array(
+						'id' => array(
+							'description' => __( 'Unique identifier for the attachment.', 'gutenberg' ),
+							'type'        => 'integer',
+						),
+					),
+				),
+				'allow_batch' => $this->allow_batch,
+				'schema'      => array( $this, 'get_public_item_schema' ),
+			)
+		);
 	}
 
 	/**
@@ -232,6 +252,60 @@ public function create_item( $request ) {
 		return $response;
 	}
 
+	/**
+	 * Finalizes an attachment after client-side media processing.
+	 *
+	 * Triggers the {@see 'wp_generate_attachment_metadata'} filter so that
+	 * server-side plugins can process the attachment after all client-side
+	 * operations (upload, thumbnail generation, sideloads) are complete.
+	 *
+	 * @param WP_REST_Request $request Full details about the request.
+	 * @return WP_REST_Response|WP_Error Response object on success, WP_Error object on failure.
+	 */
+	public function finalize_item( WP_REST_Request $request ) {
+		$attachment_id = $request['id'];
+
+		$post = $this->get_post( $attachment_id );
+
+		if ( is_wp_error( $post ) ) {
+			return $post;
+		}
+
+		$metadata = wp_get_attachment_metadata( $attachment_id );
+
+		if ( ! is_array( $metadata ) ) {
+			$metadata = array();
+		}
+
+		/**
+		 * Filters the attachment metadata after client-side processing.
+		 *
+		 * This re-applies the wp_generate_attachment_metadata filter so that
+		 * server-side plugins (e.g. those adding custom image sizes or
+		 * processing metadata) can run after client-side uploads are complete.
+		 *
+		 * @param array  $metadata      Attachment metadata.
+		 * @param int    $attachment_id Attachment ID.
+		 * @param string $context       Context: 'create' or 'update'.
+		 */
+		// phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound
+		$metadata = apply_filters( 'wp_generate_attachment_metadata', $metadata, $attachment_id, 'update' );
+
+		wp_update_attachment_metadata( $attachment_id, $metadata );
+
+		$response_request = new WP_REST_Request(
+			WP_REST_Server::READABLE,
+			rest_get_route_for_post( $attachment_id )
+		);
+
+		$response_request['context'] = 'edit';
+
+		if ( isset( $request['_fields'] ) ) {
+			$response_request['_fields'] = $request['_fields'];
+		}
+
+		return $this->prepare_item_for_response( get_post( $attachment_id ), $response_request );
+	}
 
 	/**
 	 * Checks if a given request has access to sideload a file.

packages/block-editor/src/components/provider/use-media-upload-settings.js

@@ -15,6 +15,7 @@ function useMediaUploadSettings( settings = {} ) {
 		() => ( {
 			mediaUpload: settings.mediaUpload,
 			mediaSideload: settings.mediaSideload,
+			mediaFinalize: settings.mediaFinalize,
 			maxUploadFileSize: settings.maxUploadFileSize,
 			allowedMimeTypes: settings.allowedMimeTypes,
 			allImageSizes: settings.allImageSizes,

packages/editor/src/components/provider/use-block-editor-settings.js

@@ -24,6 +24,7 @@ import {
 import inserterMediaCategories from '../media-categories';
 import { mediaUpload } from '../../utils';
 import { default as mediaSideload } from '../../utils/media-sideload';
+import { default as mediaFinalize } from '../../utils/media-finalize';
 import { store as editorStore } from '../../store';
 import { unlock } from '../../lock-unlock';
 import { useGlobalStylesContext } from '../global-styles-provider';
@@ -337,6 +338,7 @@ function useBlockEditorSettings( settings, postType, postId, renderingMode ) {
 				: undefined,
 			mediaUpload: hasUploadPermissions ? mediaUpload : undefined,
 			mediaSideload: hasUploadPermissions ? mediaSideload : undefined,
+			mediaFinalize: hasUploadPermissions ? mediaFinalize : undefined,
 			__experimentalBlockPatterns: blockPatterns,
 			[ selectBlockPatternsKey ]: ( select ) => {
 				const { hasFinishedResolution, getBlockPatternsForPostType } =

packages/editor/src/utils/media-finalize/index.js

@@ -0,0 +1,11 @@
+/**
+ * WordPress dependencies
+ */
+import apiFetch from '@wordpress/api-fetch';
+
+export default async function mediaFinalize( id ) {
+	await apiFetch( {
+		path: `/wp/v2/media/${ id }/finalize`,
+		method: 'POST',
+	} );
+}

packages/editor/src/utils/media-finalize/test/index.js

@@ -0,0 +1,34 @@
+/**
+ * WordPress dependencies
+ */
+import apiFetch from '@wordpress/api-fetch';
+
+/**
+ * Internal dependencies
+ */
+import mediaFinalize from '..';
+
+jest.mock( '@wordpress/api-fetch', () => jest.fn() );
+
+describe( 'mediaFinalize', () => {
+	beforeEach( () => {
+		jest.clearAllMocks();
+	} );
+
+	it( 'should call the finalize endpoint with the correct path and method', async () => {
+		apiFetch.mockResolvedValue( {} );
+
+		await mediaFinalize( 123 );
+
+		expect( apiFetch ).toHaveBeenCalledWith( {
+			path: '/wp/v2/media/123/finalize',
+			method: 'POST',
+		} );
+	} );
+
+	it( 'should propagate errors from apiFetch', async () => {
+		apiFetch.mockRejectedValue( new Error( 'Network error' ) );
+
+		await expect( mediaFinalize( 456 ) ).rejects.toThrow( 'Network error' );
+	} );
+} );

packages/upload-media/package.json

@@ -49,7 +49,6 @@
 		"build-module/store/index.mjs"
 	],
 	"dependencies": {
-		"@wordpress/api-fetch": "file:../api-fetch",
 		"@wordpress/blob": "file:../blob",
 		"@wordpress/compose": "file:../compose",
 		"@wordpress/data": "file:../data",

packages/upload-media/src/store/private-actions.ts

@@ -8,7 +8,6 @@ import { v4 as uuidv4 } from 'uuid';
  */
 import { createBlobURL, isBlobURL, revokeBlobURL } from '@wordpress/blob';
 import type { createRegistry } from '@wordpress/data';
-
 type WPDataRegistry = ReturnType< typeof createRegistry >;
 
 /**
@@ -74,6 +73,7 @@ type ActionCreators = {
 	rotateItem: typeof rotateItem;
 	transcodeImageItem: typeof transcodeImageItem;
 	generateThumbnails: typeof generateThumbnails;
+	finalizeItem: typeof finalizeItem;
 	updateItemProgress: typeof updateItemProgress;
 	revokeBlobUrls: typeof revokeBlobUrls;
 	< T = Record< string, unknown > >( args: T ): void;
@@ -380,6 +380,15 @@ export function processItem( id: QueueItemId ) {
 					return;
 				}
 
+				// If parent has pending operations (like Finalize), trigger them.
+				if (
+					parentItem.operations &&
+					parentItem.operations.length > 0
+				) {
+					dispatch.processItem( parentId );
+					return;
+				}
+
 				if ( attachment ) {
 					parentItem.onSuccess?.( [ attachment ] );
 				}
@@ -403,6 +412,14 @@ export function processItem( id: QueueItemId ) {
 			return;
 		}
 
+		// For Finalize, wait until all child sideloads are complete.
+		if (
+			operation === OperationType.Finalize &&
+			select.hasPendingItemsByParentId( id )
+		) {
+			return;
+		}
+
 		dispatch< OperationStartAction >( {
 			type: Type.OperationStart,
 			id,
@@ -446,6 +463,10 @@ export function processItem( id: QueueItemId ) {
 			case OperationType.ThumbnailGeneration:
 				dispatch.generateThumbnails( id );
 				break;
+
+			case OperationType.Finalize:
+				dispatch.finalizeItem( id );
+				break;
 		}
 	};
 }
@@ -735,7 +756,8 @@ export function prepareItem( id: QueueItemId ) {
 
 			operations.push(
 				OperationType.Upload,
-				OperationType.ThumbnailGeneration
+				OperationType.ThumbnailGeneration,
+				OperationType.Finalize
 			);
 		} else {
 			operations.push( OperationType.Upload );
@@ -1108,6 +1130,11 @@ export function generateThumbnails( id: QueueItemId ) {
 			attachment.missing_image_sizes &&
 			attachment.missing_image_sizes.length > 0
 		) {
+			const settings = select.getSettings();
+			const allImageSizes = settings.allImageSizes || {};
+			const sizesToGenerate: string[] =
+				attachment.missing_image_sizes as string[];
+
 			// Use sourceFile for thumbnail generation to preserve quality.
 			// WordPress core generates thumbnails from the original (unscaled) image.
 			// Vips will auto-rotate based on EXIF orientation during thumbnail generation.
@@ -1116,8 +1143,6 @@ export function generateThumbnails( id: QueueItemId ) {
 				: item.sourceFile;
 			const batchId = uuidv4();
 
-			const settings = select.getSettings();
-			const allImageSizes = settings.allImageSizes || {};
 			const { imageOutputFormats } = settings;
 
 			// Check if thumbnails should be transcoded to a different format.
@@ -1141,7 +1166,7 @@ export function generateThumbnails( id: QueueItemId ) {
 				);
 			}
 
-			for ( const name of attachment.missing_image_sizes ) {
+			for ( const name of sizesToGenerate ) {
 				const imageSize = allImageSizes[ name ];
 				if ( ! imageSize ) {
 					// eslint-disable-next-line no-console
@@ -1255,6 +1280,40 @@ export function generateThumbnails( id: QueueItemId ) {
 	};
 }
 
+/**
+ * Finalizes an uploaded item by calling the server's finalize endpoint.
+ *
+ * This triggers the wp_generate_attachment_metadata filter so that PHP
+ * plugins can process the attachment after all client-side operations
+ * (including thumbnail sideloads) are complete.
+ *
+ * @param id Item ID.
+ */
+export function finalizeItem( id: QueueItemId ) {
+	return async ( { select, dispatch }: ThunkArgs ) => {
+		const item = select.getItem( id );
+		if ( ! item ) {
+			return;
+		}
+
+		const attachment = item.attachment;
+		const { mediaFinalize } = select.getSettings();
+
+		// Only finalize if we have an attachment ID and a mediaFinalize callback.
+		if ( attachment?.id && mediaFinalize ) {
+			try {
+				await mediaFinalize( attachment.id );
+			} catch ( error ) {
+				// Log but don't fail the upload if finalization fails.
+				// eslint-disable-next-line no-console
+				console.warn( 'Media finalization failed:', error );
+			}
+		}
+
+		dispatch.finishOperation( id, {} );
+	};
+}
+
 /**
  * Revokes all blob URLs for a given item, freeing up memory.
  *