[wp-trac] [WordPress Trac] #64915: Media: Enable HEIC/HEIF uploads when server lacks image editor support

[WordPress Trac]

#64915: Media: Enable HEIC/HEIF uploads when server lacks image editor support
-----------------------------+--------------------
 Reporter:  adamsilverstein  |      Owner:  (none)
     Type:  defect (bug)     |     Status:  new
 Priority:  normal           |  Milestone:  7.1
Component:  Media            |    Version:  trunk
 Severity:  normal           |   Keywords:
  Focuses:                   |
-----------------------------+--------------------
 == Description ==

 HEIC (HEIF with HEVC codec) is the default photo format on iPhones. When
 users upload HEIC images via the REST API and the server's image editor
 (ImageMagick/GD) doesn't support HEIC, the upload is blocked entirely by
 the `wp_prevent_unsupported_mime_type_uploads` check in
 `WP_REST_Attachments_Controller::create_item_permissions_check()`,
 returning a `rest_upload_image_type_not_supported` error.

 With the client-side media processing feature, the browser can decode HEIC
 images natively using `createImageBitmap()` — which leverages the
 OS/browser's licensed HEVC codecs (Safari everywhere, Chrome on macOS,
 Chrome on Windows with codec extension) — and convert them to JPEG for
 sub-size generation via canvas. However, this requires the server to first
 accept the HEIC upload.

 == Proposed Change ==

 Bypass the `$prevent_unsupported_uploads` check for HEIC/HEIF MIME types
 (detected via the existing `wp_is_heic_image_mime_type()` helper) so the
 file can be stored on the server even when the image editor can't process
 it.

 The flow becomes:

 1. Upload HEIC to server — server tries to process and generate sub-sizes
 2. If server has HEIC support → everything works as before
 3. If server lacks HEIC support → file is stored, `missing_image_sizes` is
 populated in the REST response
 4. Client detects missing sizes and uses browser-native
 `createImageBitmap()` + `OffscreenCanvas` to decode and convert to JPEG
 5. JPEG is sideloaded as the `scaled` version, sub-sizes are generated
 from the JPEG via the existing client-side resize pipeline

 This approach:
 - Is backwards compatible (servers with HEIC support are unaffected)
 - Leverages browser-licensed HEVC decoding rather than shipping a decoder
 - Uses the existing `wp_is_heic_image_mime_type()` function already in
 core

 == Change Summary ==

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

 {{{
 // Always allow HEIC/HEIF uploads through even if the server's image
 // editor doesn't support them. The client-side canvas fallback will
 // handle processing using the browser's native HEVC decoder.
 if (
     $prevent_unsupported_uploads &&
     ! empty( $files['file']['type'] ) &&
     wp_is_heic_image_mime_type( $files['file']['type'] )
 ) {
     $prevent_unsupported_uploads = false;
 }
 }}}

 == Testing ==

 1. Use a WordPress environment where ImageMagick does NOT have HEIC
 support
 2. Upload a HEIC image via the REST API media endpoint (`POST
 /wp/v2/media`)
 3. Verify the upload succeeds (previously returned
 `rest_upload_image_type_not_supported` error)
 4. Verify `missing_image_sizes` is populated in the response

 == Related ==

 - Core PR: https://github.com/WordPress/wordpress-develop/pull/11323
 - Gutenberg PR: https://github.com/WordPress/gutenberg/pull/76731
 - Gutenberg issue: https://github.com/WordPress/gutenberg/issues/76732

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/64915>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform