Media: Enable HEIC/HEIF uploads when server lacks image editor support

src/wp-includes/default-filters.php

@@ -562,6 +562,7 @@
 add_action( 'transition_post_status', '_wp_customize_publish_changeset', 10, 3 );
 add_action( 'admin_enqueue_scripts', '_wp_customize_loader_settings' );
 add_action( 'delete_attachment', '_delete_attachment_theme_mod' );
+add_action( 'delete_attachment', 'wp_delete_attachment_heic_companion_file' );
 add_action( 'transition_post_status', '_wp_keep_alive_customize_changeset_dependent_auto_drafts', 20, 3 );
 
 // Block Theme Previews.

src/wp-includes/media.php

@@ -5760,6 +5760,45 @@ function wp_show_heic_upload_error( $plupload_settings ) {
 	return $plupload_settings;
 }
 
+/**
+ * Deletes the HEIC companion file when its attachment is deleted.
+ *
+ * When the client-side media flow sideloads a HEIC original alongside a
+ * JPEG derivative, the HEIC filename is recorded in $metadata['original'].
+ * WordPress only tracks 'original_image' in wp_delete_attachment_files(),
+ * so without this hook the HEIC file would linger on disk after the
+ * attachment is deleted.
+ *
+ * @since 7.1.0
+ *
+ * @param int $post_id Attachment ID being deleted.
+ */
+function wp_delete_attachment_heic_companion_file( $post_id ) {
+	$metadata = wp_get_attachment_metadata( $post_id, true );
+
+	if ( empty( $metadata['original'] ) || ! is_string( $metadata['original'] ) ) {
+		return;
+	}
+
+	$attached_file = get_attached_file( $post_id, true );
+
+	if ( ! $attached_file ) {
+		return;
+	}
+
+	$uploads = wp_get_upload_dir();
+
+	if ( empty( $uploads['basedir'] ) ) {
+		return;
+	}
+
+	$heic_path = path_join( dirname( $attached_file ), wp_basename( (string) $metadata['original'] ) );
+
+	if ( file_exists( $heic_path ) ) {
+		wp_delete_file_from_directory( $heic_path, $uploads['basedir'] );
+	}
+}
+
 /**
  * Allows PHP's getimagesize() to be debuggable when necessary.
  *

src/wp-includes/rest-api/class-wp-rest-server.php

@@ -1380,7 +1380,7 @@ public function get_index( $request ) {
 			$available['image_size_threshold'] = (int) apply_filters( 'big_image_size_threshold', 2560, array( 0, 0 ), '', 0 );
 
 			// Image output formats.
-			$input_formats  = array( 'image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/avif', 'image/heic' );
+			$input_formats  = array( 'image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/avif', 'image/heic', 'image/heif' );
 			$output_formats = array();
 			foreach ( $input_formats as $mime_type ) {
 				/** This filter is documented in wp-includes/media.php */

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

@@ -68,6 +68,10 @@ public function register_routes() {
 			$valid_image_sizes = array_keys( wp_get_registered_image_subsizes() );
 			// Special case to set 'original_image' in attachment metadata.
 			$valid_image_sizes[] = 'original';
+			// HEIC/HEIF companion original preserved alongside the JPEG derivative.
+			// Stored under its own meta key so it never collides with 'original'
+			// (which the scaled-sideload flow also writes to).
+			$valid_image_sizes[] = 'original-heic';
 			// Used for PDF thumbnails.
 			$valid_image_sizes[] = 'full';
 			// Client-side big image threshold: sideload the scaled version.
@@ -82,21 +86,26 @@ public function register_routes() {
 						'callback'            => array( $this, 'sideload_item' ),
 						'permission_callback' => array( $this, 'sideload_item_permissions_check' ),
 						'args'                => array(
-							'id'             => array(
+							'id'                 => array(
 								'description' => __( 'Unique identifier for the attachment.' ),
 								'type'        => 'integer',
 							),
-							'image_size'     => array(
+							'image_size'         => array(
 								'description' => __( 'Image size.' ),
 								'type'        => 'string',
 								'enum'        => $valid_image_sizes,
 								'required'    => true,
 							),
-							'convert_format' => array(
+							'convert_format'     => array(
 								'type'        => 'boolean',
 								'default'     => true,
 								'description' => __( 'Whether to convert image formats.' ),
 							),
+							'generate_sub_sizes' => array(
+								'description' => __( 'Whether to generate image sub sizes from the sideloaded file.' ),
+								'type'        => 'boolean',
+								'default'     => false,
+							),
 						),
 					),
 					'allow_batch' => $this->allow_batch,
@@ -258,6 +267,17 @@ public function create_item_permissions_check( $request ) {
 			$prevent_unsupported_uploads = false;
 		}
 
+		// 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;
+		}
+
 		// If the upload is an image, check if the server can handle the mime type.
 		if (
 			$prevent_unsupported_uploads &&
@@ -2090,6 +2110,13 @@ public function sideload_item( WP_REST_Request $request ) {
 
 		if ( 'original' === $image_size ) {
 			$metadata['original_image'] = wp_basename( $path );
+		} elseif ( 'original-heic' === $image_size ) {
+			// HEIC companion original: stored under its own meta key so
+			// the scaled-sideload flow (which writes 'original_image')
+			// cannot clobber it. 'original_image' keeps pointing at the
+			// web-viewable JPEG derivative. Cleanup on attachment delete
+			// is handled by wp_delete_attachment_heic_companion_file().
+			$metadata['original'] = wp_basename( $path );
 		} elseif ( 'scaled' === $image_size ) {
 			// The current attached file is the original; record it as original_image.
 			$current_file = get_attached_file( $attachment_id, true );

tests/phpunit/tests/media/wpDeleteAttachmentHeicCompanionFile.php

@@ -0,0 +1,77 @@
+<?php
+
+/**
+ * Tests for the `wp_delete_attachment_heic_companion_file()` function.
+ *
+ * @group media
+ * @covers ::wp_delete_attachment_heic_companion_file
+ */
+class Tests_Media_wpDeleteAttachmentHeicCompanionFile extends WP_UnitTestCase {
+
+	public function tear_down() {
+		$this->remove_added_uploads();
+
+		parent::tear_down();
+	}
+
+	/**
+	 * @ticket 64915
+	 */
+	public function test_deletes_heic_file_recorded_in_metadata_original() {
+		$attachment_id = $this->factory->attachment->create_upload_object( DIR_TESTDATA . '/images/canola.jpg' );
+
+		$attached_file = get_attached_file( $attachment_id, true );
+		$dir           = dirname( $attached_file );
+		$heic_name     = 'companion-' . wp_generate_password( 6, false ) . '.heic';
+		$heic_path     = $dir . '/' . $heic_name;
+
+		// Create a dummy companion file on disk.
+		file_put_contents( $heic_path, 'test' );
+		$this->assertFileExists( $heic_path, 'Test fixture should be on disk.' );
+
+		// Record the companion under metadata['original'] as the sideload route does.
+		$metadata             = wp_get_attachment_metadata( $attachment_id, true );
+		$metadata['original'] = $heic_name;
+		wp_update_attachment_metadata( $attachment_id, $metadata );
+
+		wp_delete_attachment( $attachment_id, true );
+
+		$this->assertFileDoesNotExist( $heic_path, 'Companion HEIC file should be deleted alongside the attachment.' );
+	}
+
+	/**
+	 * @ticket 64915
+	 */
+	public function test_noop_when_metadata_original_is_missing() {
+		$attachment_id = $this->factory->attachment->create_upload_object( DIR_TESTDATA . '/images/canola.jpg' );
+
+		// Sanity: no 'original' key on freshly-created metadata.
+		$metadata = wp_get_attachment_metadata( $attachment_id, true );
+		$this->assertArrayNotHasKey( 'original', $metadata );
+
+		// Should not raise even though the hook fires.
+		wp_delete_attachment( $attachment_id, true );
+
+		$this->assertNull( get_post( $attachment_id ) );
+	}
+
+	/**
+	 * Guards against $metadata['original'] holding a non-string value (e.g.
+	 * the array form some flows write). Regression coverage for GB #78128.
+	 *
+	 * @ticket 64915
+	 */
+	public function test_noop_when_metadata_original_is_not_a_string() {
+		$attachment_id = $this->factory->attachment->create_upload_object( DIR_TESTDATA . '/images/canola.jpg' );
+		$attached_file = get_attached_file( $attachment_id, true );
+
+		$metadata             = wp_get_attachment_metadata( $attachment_id, true );
+		$metadata['original'] = array( 'file' => 'should-not-delete.heic' );
+		wp_update_attachment_metadata( $attachment_id, $metadata );
+
+		// Should not raise (no path_join() / file_exists() on an array).
+		wp_delete_attachment_heic_companion_file( $attachment_id );
+
+		$this->assertFileExists( $attached_file, 'Attached file should still be on disk; the hook must bail on non-string original.' );
+	}
+}

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

@@ -3351,6 +3351,82 @@ public function test_sideload_route_includes_scaled_enum() {
 		$this->assertContains( 'scaled', $args[ $param_name ]['enum'], 'image_size enum should include scaled.' );
 	}
 
+	/**
+	 * Tests that the sideload endpoint includes 'original-heic' in the image_size enum.
+	 *
+	 * @ticket 64915
+	 */
+	public function test_sideload_route_includes_original_heic_enum() {
+		$this->enable_client_side_media_processing();
+
+		$routes   = rest_get_server()->get_routes();
+		$endpoint = $routes['/wp/v2/media/(?P<id>[\d]+)/sideload'][0];
+		$args     = $endpoint['args'];
+
+		$this->assertArrayHasKey( 'image_size', $args, 'Route should have image_size arg.' );
+		$this->assertContains( 'original-heic', $args['image_size']['enum'], 'image_size enum should include original-heic.' );
+	}
+
+	/**
+	 * Tests that the sideload endpoint exposes the generate_sub_sizes arg.
+	 *
+	 * @ticket 64915
+	 */
+	public function test_sideload_route_includes_generate_sub_sizes_arg() {
+		$this->enable_client_side_media_processing();
+
+		$routes   = rest_get_server()->get_routes();
+		$endpoint = $routes['/wp/v2/media/(?P<id>[\d]+)/sideload'][0];
+		$args     = $endpoint['args'];
+
+		$this->assertArrayHasKey( 'generate_sub_sizes', $args, 'Route should have generate_sub_sizes arg.' );
+		$this->assertSame( 'boolean', $args['generate_sub_sizes']['type'], 'generate_sub_sizes should be a boolean.' );
+		$this->assertFalse( $args['generate_sub_sizes']['default'], 'generate_sub_sizes should default to false on sideload.' );
+	}
+
+	/**
+	 * Tests sideloading an 'original-heic' companion file alongside its JPEG
+	 * derivative. The HEIC filename is recorded under $metadata['original']
+	 * so it does not collide with 'original_image', which the scaled-sideload
+	 * flow owns.
+	 *
+	 * @ticket 64915
+	 * @requires function imagejpeg
+	 */
+	public function test_sideload_original_heic_writes_metadata_original() {
+		$this->enable_client_side_media_processing();
+
+		wp_set_current_user( self::$author_id );
+
+		// Create the JPEG attachment that the HEIC will be a companion to.
+		$request = new WP_REST_Request( 'POST', '/wp/v2/media' );
+		$request->set_header( 'Content-Type', 'image/jpeg' );
+		$request->set_header( 'Content-Disposition', 'attachment; filename=canola.jpg' );
+		$request->set_body( file_get_contents( self::$test_file ) );
+		$response      = rest_get_server()->dispatch( $request );
+		$attachment_id = $response->get_data()['id'];
+
+		$this->assertSame( 201, $response->get_status() );
+
+		// Sideload the HEIC companion using the real HEIC fixture. `convert_format`
+		// is disabled so the default HEIC -> JPEG output mapping does not rename
+		// the file or append an alt-extension suffix.
+		$request = new WP_REST_Request( 'POST', "/wp/v2/media/{$attachment_id}/sideload" );
+		$request->set_header( 'Content-Type', 'image/heic' );
+		$request->set_header( 'Content-Disposition', 'attachment; filename=canola.heic' );
+		$request->set_param( 'image_size', 'original-heic' );
+		$request->set_param( 'convert_format', false );
+		$request->set_body( file_get_contents( DIR_TESTDATA . '/images/test-image.heic' ) );
+		$response = rest_get_server()->dispatch( $request );
+
+		$this->assertSame( 200, $response->get_status(), 'Sideloading original-heic should succeed.' );
+
+		$metadata = wp_get_attachment_metadata( $attachment_id );
+		$this->assertArrayHasKey( 'original', $metadata, "Metadata should contain 'original' for the HEIC companion." );
+		$this->assertMatchesRegularExpression( '/canola.*\.heic$/', $metadata['original'], "Metadata 'original' should reference the HEIC filename." );
+		$this->assertArrayNotHasKey( 'original_image', $metadata, "Metadata 'original_image' should be untouched by the HEIC sideload." );
+	}
+
 	/**
 	 * Tests the filter_wp_unique_filename method handles the -scaled suffix.
 	 *

tests/qunit/fixtures/wp-api-generated.js

@@ -3703,6 +3703,7 @@ mockedApiResponse.Schema = {
                                 "1536x1536",
                                 "2048x2048",
                                 "original",
+                                "original-heic",
                                 "full",
                                 "scaled"
                             ],
@@ -3713,6 +3714,12 @@ mockedApiResponse.Schema = {
                             "default": true,
                             "description": "Whether to convert image formats.",
                             "required": false
+                        },
+                        "generate_sub_sizes": {
+                            "description": "Whether to generate image sub sizes from the sideloaded file.",
+                            "type": "boolean",
+                            "default": false,
+                            "required": false
                         }
                     }
                 }