What?

Adds hooks and extension points to ensure existing media hooks continue to run when client-side media processing is active.

Closes #74358.

Why?

When client-side media processing handles image uploads (resizing, thumbnail generation, format conversion), server-side WordPress hooks like wp_generate_attachment_metadata are bypassed. Plugins that rely on these hooks (e.g., for watermarking, CDN sync, custom sizes) stop working. This PR adds the necessary extension points.

There is significant usage of the wp_generate_attachment_metadata filter by plugins.

Changes

PHP: Finalize REST Endpoint

• POST /wp/v2/media/{id}/finalize — New endpoint that triggers wp_generate_attachment_metadata after all client-side operations complete, so server-side plugins can post-process attachments.

JS: Store Setting

• imageQuality — Store setting allowing control of image quality (0-1) for resize/crop operations, replacing the previous JS filter hook approach. Set via updateSettings().

JS: Finalize Pipeline

• OperationType.Finalize — New operation type appended to the image upload pipeline after thumbnail generation.
• Finalize gate — Waits for all child sideloads (thumbnails) to complete before calling the finalize endpoint.
• Parent trigger — When the last sideload in a batch completes, triggers the parent item's pending Finalize operation.
• finalizeItem() — Uses the injected finalizeUpload setting callback to call the finalize endpoint, following the same pattern as mediaUpload and mediaSideload.
• finalizeUpload setting — New optional setting in @wordpress/upload-media that accepts a callback (id: number) => Promise<void>. The actual REST API call (POST /wp/v2/media/{id}/finalize) lives in @wordpress/editor as mediaFinalize, keeping @wordpress/upload-media implementation-agnostic.

Architecture: Injected Callback Pattern

The finalizeItem function no longer makes a direct apiFetch call. Instead, it uses the finalizeUpload setting injected via the block editor settings, matching the existing pattern used by mediaUpload and mediaSideload. This keeps @wordpress/upload-media free of direct REST API dependencies (the @wordpress/api-fetch dependency has been removed from the package).

The callback flows through:

1. @wordpress/editor — defines mediaFinalize utility (makes the actual apiFetch call)
2. use-block-editor-settings.js — wires finalizeUpload: mediaFinalize into settings
3. @wordpress/block-editor — passes finalizeUpload through useMediaUploadSettings
4. @wordpress/upload-media — consumes finalizeUpload from settings in finalizeItem()

Hook Usage Examples

POST /wp/v2/media/{id}/finalize Endpoint

Server-side: Hook into wp_generate_attachment_metadata to process attachments after client-side uploads complete:

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 );

OperationType.Finalize Pipeline

This is an internal pipeline operation, not a public hook. When all child sideloads (thumbnails) for an uploaded image have completed, the Finalize operation fires automatically, calling the POST /wp/v2/media/{id}/finalize endpoint to re-trigger wp_generate_attachment_metadata on the server. Plugin developers do not need to interact with this directly — they should use the PHP filter above.

Backport Plan (WordPress Core)

What needs backporting (PHP only)

1. Finalize endpoint — Add register_routes() entry and finalize_item() / finalize_item_permissions_check() methods to Core's WP_REST_Attachments_Controller class (wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php).
2. No new hooks needed — The wp_generate_attachment_metadata filter already exists in Core. The finalize endpoint simply re-triggers it with context 'update'.

What does NOT need backporting

• JS store settings (imageQuality, finalizeUpload) — These live in the @wordpress/upload-media package which ships with the Gutenberg plugin, not Core.
• OperationType.Finalize — JS pipeline code, ships with Gutenberg.
• The entire client-side media processing feature must land in Core first before the finalize endpoint is useful there.

Backport PR structure

• Title: "REST API: Add finalize endpoint to WP_REST_Attachments_Controller"
• Files to modify in Core:
  • wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php — Add finalize route registration, permission check, and handler
  • tests/phpunit/tests/rest-api/rest-attachments-controller.php — Add tests for the new endpoint
• Dependencies: The backport should land alongside or after the client-side media processing feature itself is backported to Core. The finalize endpoint is only useful when client-side processing is active.

Files Changed

Testing Instructions

1. Enable client-side media processing (the experiment)
2. Upload an image in the block editor
3. Verify thumbnails are generated and the finalize endpoint is called (check Network tab for POST .../finalize)
4. Add a plugin that hooks into wp_generate_attachment_metadata and verify it fires after upload completes
5. Run JS unit tests: npm run test:unit -- --testPathPattern='packages/upload-media/src/store/test/private-actions'
6. Run editor tests: npm run test:unit -- --testPathPattern='packages/editor/src/utils/media-finalize/test'

🤖 Generated with Claude Code