Media: Enable HEIC/HEIF uploads when server lacks image editor support by adamsilverstein · Pull Request #11323 · WordPress/wordpress-develop

adamsilverstein · 2026-03-20T16:59:45Z

Trac ticket: https://core.trac.wordpress.org/ticket/64915

Note: merge after client side media is restored in core.

What?

Allow HEIC/HEIF image uploads to succeed even when the server's image editor (ImageMagick/GD) doesn't support HEIC. Currently, wp_prevent_unsupported_mime_type_uploads blocks these uploads entirely.

Gutenberg PR: WordPress/gutenberg#76731

Why?

HEIC is the default photo format on iPhones. When users upload HEIC images and the server can't process them, the upload fails with an unhelpful error. With the client-side media processing feature, the browser can decode HEIC using its native createImageBitmap() API (leveraging OS-licensed HEVC codecs) and convert to JPEG for sub-size generation. But first, the server needs to accept the upload.

How?

In WP_REST_Attachments_Controller::create_item_permissions_check(), bypass the $prevent_unsupported_uploads check when the uploaded file is HEIC/HEIF (detected via the existing wp_is_heic_image_mime_type() helper). This allows the file to be stored on the server, after which the client-side canvas fallback generates a JPEG version and all required sub-sizes.

A new original-heic sideload image-size token records the source-format original under a dedicated source_image metadata key (so it never collides with original_image), and wp_delete_attachment_heic_companion_file() cleans that companion file up on attachment delete.

Behavior note

The HEIC bypass is unconditional for the HEIC/HEIF mime family — it does not require generate_sub_sizes === false. As a result, a non-browser REST client uploading HEIC to a server without HEIC support now receives a stored attachment with empty missing_image_sizes instead of the previous rest_upload_image_type_not_supported error. This is intentional: the browser can always decode HEIC client-side, and raw API consumers can generate sub-sizes themselves. Flagging it as a deliberate contract change for POST /wp/v2/media.

PHPStan type coverage extracted to Code Quality: Add PHPStan type coverage for media and upload functions #12313. The @phpstan-return/@phpstan-param annotations and the phpstan-phpunit extension that previously lived on this branch were moved to Code Quality: Add PHPStan type coverage for media and upload functions #12313 so the static-analysis work can be reviewed independently. When both land, the affected code passes PHPStan rule level 10.
The typed-property hints on the attachments-controller test class remain here because they share a file with the new HEIC tests and cannot be cleanly separated.

Testing Instructions

Use a WordPress environment where ImageMagick does NOT have HEIC support
Upload a HEIC image via the REST API media endpoint
Verify the upload succeeds (previously would return rest_upload_image_type_not_supported error)
Verify missing_image_sizes is populated in the response (server couldn't generate sub-sizes)

Bypass the `wp_prevent_unsupported_mime_type_uploads` check for HEIC/HEIF images so they can be stored even when the server's image editor doesn't support them. The client-side canvas fallback handles processing using the browser's native HEVC decoder via createImageBitmap().

github-actions · 2026-03-20T16:59:57Z

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, westonruter, ramonopoly.

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

github-actions · 2026-03-20T17:03:52Z

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.

…back # Conflicts: # src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php

adamsilverstein · 2026-04-22T20:02:49Z

Note for follow-up: when r62081 (commit c863860, "Media: Remove client-side media processing feature for now") is reverted to reintroduce client-side media processing in 7.1, the generate_sub_sizes === false skip in WP_REST_Attachments_Controller::create_item_permissions_check() should be restored alongside the HEIC/HEIF allowance added here.

Original block from this PR (dropped during the trunk merge since generate_sub_sizes no longer exists on trunk):

// When the client handles image processing (generate_sub_sizes is false),
// skip the server-side image editor support check.
if ( false === $request['generate_sub_sizes'] ) {
    $prevent_unsupported_uploads = false;
}

ramonjd · 2026-05-12T01:31:02Z

Heads up, there was a follow up to WordPress/gutenberg#76731:

Media: Guard gutenberg_delete_heic_companion_file() against non-string $metadata['original'] gutenberg#78128

Adds an is_string() guard to gutenberg_delete_heic_companion_file() so it bails on attachments whose wp_get_attachment_metadata()['original'] is not a string filename.

Not sure if it needs a core sync at all since it's a GB load.php change. 🤔

adamsilverstein · 2026-05-12T15:50:58Z

Not sure if it needs a core sync at all since it's a GB load.php change

Possibly, I will review once the 7.1 branch is open and I am able to reintroduce the feature in core.

Thanks for cross linking this ticket!

…back # Conflicts: # src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php

Extends the /wp/v2/media/<id>/sideload route so the client-side media flow can upload a HEIC/HEIF companion original alongside the JPEG derivative: - Adds 'original-heic' to the allowed image_size enum. The companion filename is recorded under $metadata['original'] so it never collides with 'original_image', which the scaled-sideload flow owns. - Adds a 'generate_sub_sizes' boolean arg (default false) so callers that handle processing client-side can suppress server-side sub-size generation per request. - Adds 'image/heif' to the image_output_formats input list returned by the REST API root index. Backport of GB #76731.

When the client-side media flow sideloads a HEIC original alongside a JPEG derivative, the HEIC filename is stored in $metadata['original']. wp_delete_attachment_files() only tracks 'original_image', so without this hook the HEIC file would linger on disk after the attachment is removed. wp_delete_attachment_heic_companion_file() reads the meta key, guards against non-string values (e.g. arrays written by other flows), and deletes the file when present. Hooked into the delete_attachment action via default-filters.php. Backport of GB #76731, with the is_string() guard from GB #78128.

Adds REST API controller tests: - The sideload route exposes 'original-heic' in the image_size enum. - The sideload route exposes a 'generate_sub_sizes' boolean arg defaulting to false. - Sideloading an 'original-heic' image writes the filename to $metadata['original'] and leaves 'original_image' untouched. Adds wp_delete_attachment_heic_companion_file() unit tests: - The companion HEIC is removed when the attachment is deleted. - The hook is a no-op when $metadata['original'] is missing. - The hook bails when $metadata['original'] is not a string (regression coverage for the guard added in GB #78128).

…deload. The test was sending JPEG bytes with a .heic filename, which wp_check_filetype_and_ext() corrected to canola-1.jpg before the metadata assertion ran. Switch to the real test-image.heic fixture, set Content-Type accordingly, and pass convert_format=false to disable the default HEIC -> JPEG output mapping so the .heic extension is preserved.

Add 'original-heic' to the image_size enum and the missing generate_sub_sizes arg so the schema fixture matches what the live REST index now reports. Without this the test-fixtures step fails the git diff --exit-code check.

westonruter

Review from Claude Code (/code-review xhigh-effort pass), posted by @westonruter. Findings left inline; the bottom half are cleanup/altitude notes rather than bugs — dismiss anything that doesn't land.

Co-authored-by: Weston Ruter <westonruter@gmail.com>

Harden the companion-original handling surfaced in review: - Rename the companion metadata key from the over-generic 'original' to 'source_image' so unrelated plugin or theme data stored under 'original' can no longer drive file deletion on attachment delete. - Add IMAGE_SIZE_SOURCE_ORIGINAL and META_KEY_SOURCE_IMAGE class constants so the sideload image_size enum and its dispatch branch cannot drift. - Drop the unused generate_sub_sizes argument from the /sideload route schema; only create_item() reads it, so advertising it on sideload silently misleads clients. - Advertise the HEIC/HEIF -sequence variants in the REST index input formats so they match wp_is_heic_image_mime_type(). - Return a boolean from wp_delete_attachment_heic_companion_file() and strengthen the non-string guard test with a real on-disk bystander file so the regression it protects against can actually fail.

Co-authored-by: Weston Ruter <westonruter@gmail.com>

* Media: Rename HEIC companion metadata key to 'source_image' During the wordpress-develop backport review (WordPress/wordpress-develop#11323), the metadata key recording the sideloaded source-format original was renamed from the generic 'original' to the dedicated 'source_image', and the size token and the key were promoted to controller constants so the sideload schema and the metadata writer cannot drift apart. Port those changes back so the plugin and core agree on the key, and align the delete_attachment cleanup hook with the core implementation. Add PHPUnit coverage for the renamed key and the cleanup hook. * Add backport changelog entry linking to core PR #11323

* Media: Rename HEIC companion metadata key to 'source_image' During the wordpress-develop backport review (WordPress/wordpress-develop#11323), the metadata key recording the sideloaded source-format original was renamed from the generic 'original' to the dedicated 'source_image', and the size token and the key were promoted to controller constants so the sideload schema and the metadata writer cannot drift apart. Port those changes back so the plugin and core agree on the key, and align the delete_attachment cleanup hook with the core implementation. Add PHPUnit coverage for the renamed key and the cleanup hook. * Add backport changelog entry linking to core PR #11323 Source: WordPress/gutenberg@acb09cb

…into add/heic-canvas-fallback

…)/upload_from_file()

…ata()

Install phpstan/phpstan-phpunit (pinned to 2.0.16) and include its extension.neon so PHPUnit assertions such as assertArrayHasKey(), assertInstanceOf(), and assertNotNull() narrow types during analysis. Only extension.neon is included, not the extension's rules.neon, to avoid introducing new strict rules and the errors they would surface. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

westonruter · 2026-06-19T00:34:08Z

The changes in this PR now pass PHPStan rule level 10. I can cherry-pick the PHPStan-specific changes into a new core commit for Core-64898 so there's less to commit here. But I wanted to include the type definitions to reference with reviewing.

westonruter · 2026-06-19T00:35:14Z

+ *                     width: int<1, max>,
+ *                     height: int<1, max>,
+ *                     file: non-empty-string,
+ *                     source_image?: non-empty-string,


This source_image key is newly introduced in this PR.

… types The @phpstan-return shape previously required width, height, file, and sizes, which only holds for raster images. PDFs expose just sizes and filesize, while audio/video attachments produce an entirely different set of keys. Mark those keys optional so non-image attachments are typed correctly, and add the documented-but-missing filesize and image_meta keys. Unseal the per-size arrays and add their filesize key as well, since size items ride through the same metadata filters and can carry plugin-added keys such as modern-format sources. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…tself test_sideload_route_includes_and_excludes_expected_fields treated the value returned by array_first( $routes[ $path ] ) as the args map, but that value is the route endpoint whose argument definitions live under its 'args' key. As a result assertArrayHasKey( 'image_size', ... ) failed on every PHP version, turning the whole PHPUnit matrix red. Descend into ['args'] first, matching the structure the sibling scaled-enum assertions already relied on.

adamsilverstein · 2026-06-24T22:26:32Z

This should be ready to go.

Move the `@phpstan-return`/`@phpstan-param` annotations and the phpstan-phpunit extension out of this feature branch and into PR WordPress#12313 so the static-analysis work can be reviewed independently of the HEIC upload feature, per code-review feedback. Also correct the `$posts_clauses` test docblock: each recorded entry is the array of SQL clause fragments from the `posts_clauses` filter, so the type is `array[]`, not `string[]`.

adamsilverstein changed the title ~~Media: Allow HEIC/HEIF uploads when server lacks image editor support~~ Media: Enable HEIC/HEIF uploads when server lacks image editor support Mar 20, 2026

Merge remote-tracking branch 'origin/trunk' into add/heic-canvas-fall…

71a9e8b

…back # Conflicts: # src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php

ramonjd mentioned this pull request May 12, 2026

Media: Guard gutenberg_delete_heic_companion_file() against non-string $metadata['original'] WordPress/gutenberg#78128

Merged

adamsilverstein mentioned this pull request May 22, 2026

Media: Re-introduce client-side media processing feature #11324

Closed

5 tasks

adamsilverstein requested a review from westonruter May 22, 2026 21:43

Merge remote-tracking branch 'origin/trunk' into add/heic-canvas-fall…

630266f

…back # Conflicts: # src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php

adamsilverstein requested a review from andrewserong May 28, 2026 15:42

adamsilverstein added 3 commits May 28, 2026 11:54

adamsilverstein force-pushed the add/heic-canvas-fallback branch from 707d121 to b20bbca Compare May 28, 2026 16:12

adamsilverstein and others added 5 commits May 28, 2026 12:39

Add void return type hints

d01bab6

Use non-deprecated factory

f728cfb

Add assertions for successful attachment creation

d6f69d6

This was referenced May 28, 2026

Media: Add animated GIF to video sideload sizes and companion-file cleanup (backport GB #78410) #12005

Open

Media: Add JPEG XL (JXL) upload support with companion-original preservation (backport GB #77584) #12006

Open

Add types and type assertions to tests

beb9ffe

westonruter reviewed May 28, 2026

View reviewed changes

Comment thread src/wp-includes/media.php Outdated

Comment thread src/wp-includes/media.php Outdated

Comment thread src/wp-includes/media.php Outdated

westonruter reviewed May 28, 2026

View reviewed changes

adamsilverstein and others added 2 commits May 28, 2026 15:01

Update src/wp-includes/media.php

9b6b768

Co-authored-by: Weston Ruter <westonruter@gmail.com>

adamsilverstein force-pushed the add/heic-canvas-fallback branch from da64fe4 to 7f976bb Compare May 28, 2026 20:51

adamsilverstein mentioned this pull request May 28, 2026

Build/Test Tools: Bump bundled Gutenberg #12009

Open

github-actions Bot mentioned this pull request Jun 18, 2026

PHP backports for WP 7.1 WordPress/gutenberg#79304

Open

Apply suggestions from code review

c3c02f9

Co-authored-by: Weston Ruter <westonruter@gmail.com>

adamsilverstein requested a review from westonruter June 18, 2026 07:50

adamsilverstein mentioned this pull request Jun 18, 2026

Media: Rename HEIC companion metadata key to source_image WordPress/gutenberg#79307

Merged

westonruter and others added 11 commits June 18, 2026 16:37

Merge branch 'trunk' of https://github.com/WordPress/wordpress-develop …

ef1767d

…into add/heic-canvas-fallback

Fix Squiz.WhiteSpace.SuperfluousWhitespace.EndLine

a07580e

Incorporate file.php phpstan-return types from WordPress#12003

9f40ed4

Add return types for wp_get_upload_dir() and wp_upload_dir()

b11a774

Add types to get_file_params()/set_file_params() in WP_REST_Request

18cc9e3

Add return type for WP_REST_Attachments_Controller::upload_from_data(…

509309f

…)/upload_from_file()

Add return type definition for wp_get_attachment_metadata()

546d470

Add source_image to possible keys returned by wp_get_attachment_metad…

08b4fa5

…ata()

Combine sideload route tests to avoid having to re-assert shape

6dfdba3

Add assertions that response is array with id key

5b2b81b

westonruter reviewed Jun 19, 2026

View reviewed changes

westonruter and others added 6 commits June 18, 2026 17:37

Restore return description

1e42037

Add missing nullable original_image to metadata array shape

707326c

Indicate attachment metadata shape is unsealed (since filterable)

1b7c752

Fix unsealed array syntax

be9dd94

adamsilverstein mentioned this pull request Jun 25, 2026

Code Quality: Add PHPStan type coverage for media and upload functions #12313

Open

adamsilverstein added 2 commits June 24, 2026 17:45

Merge branch 'trunk' into add/heic-canvas-fallback

4ff3b5b

Uh oh!

Conversation

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

Uh oh!

What?

Why?

How?

Behavior note

Related

Testing Instructions

Uh oh!

github-actions Bot commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Mar 20, 2026

Test using WordPress Playground

Some things to be aware of

Uh oh!

adamsilverstein commented Apr 22, 2026 • edited by westonruter Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ramonjd commented May 12, 2026

Uh oh!

adamsilverstein commented May 12, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

westonruter left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

westonruter commented Jun 19, 2026

Uh oh!

westonruter Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

adamsilverstein commented Jun 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

adamsilverstein commented Mar 20, 2026 •

edited

Loading

github-actions Bot commented Mar 20, 2026 •

edited

Loading

adamsilverstein commented Apr 22, 2026 •

edited by westonruter

Loading