WordPress 7.2 extends client-side media processing beyond the block Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor, stops rewriting crossorigin attributes on the editor page, and generates animated sub-sizes for animated GIF and WebP uploads.
In short:
- Image uploads from the Media Library grid, the Add New Media File screen and the media modal now go through the client-side pipeline in supported browsers.
wp_start_cross_origin_isolation_output_buffer() and wp_add_crossorigin_attributes() are deprecated. wp_send_document_isolation_policy_header() replaces the first; the second has no replacement.
- Sub-sizes of animated GIF and WebP images keep their animation on the client-side path. The new
wp_generate_animated_image_subsizes filter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. turns that off.
Client-side media processing now covers the Media Library and media modal
WordPress 7.1 introduced client-side media processing: in a cross-origin isolated page, the block editor uploads the original image through the REST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”)
https://developer.wordpress.org/rest-api/, generates the sub-sizes in the browser with wasm-vips, then sideloads them and finalizes the attachment. This takes image processing off the server and gives the same results regardless of which image libraries the server has.
In 7.1 this only ran in the block editor. The Media Library grid, the Add New Media File screen and the media modal still uploaded through wp.Uploader and plupload to async-upload.php, with all processing on the server. A HEIC file that converted when dropped on an Image block could fail in the media modal on a server without HEIC support (#65661, #66220).
What changed in 7.2
Uploads from these three places now use the same pipeline as the editor:
- The Media Library grid (
upload.php in grid mode).
- The Add New Media File screen (
media-new.php).
- The media modal, meaning every
wp.media frame that uploads through wp.Uploader: the Image block’s “Media Library” button, the featured image A featured image is the main image used on your blog archive page and is pulled when the post or page is shared on social media. The image can be used to display in widget areas on your site or in a summary list of posts. panel, and the same frame in the site editor and the block widgets screen.
The existing UI User interface is reused, so progress bars, grid tiles and error notices look and behave as before. Error messages come from the pipeline, so the platform-specific HEIC wording from the editor shows up on these screens too. While an upload is in flight, the page warns before navigating away, since an interrupted client-side upload could lose sub-sizes that were not yet sideloaded.
Cross-origin isolation on more screens
wp_set_up_cross_origin_isolation() now also runs on load-upload.php and load-media-new.php. The Media Library is only isolated in grid mode, since list mode uploads go through the Add New Media File screen. The action query parameter check that skips third-party editors does not apply to these screens.
New functions:
wp_is_document_isolation_policy_supported() returns whether the requesting browser honors the header The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes., based on its User-Agent. Today that means Chromium 137 or newer.
wp_is_cross_origin_isolated_request() returns whether core Core is the set of software required to run WordPress. The Core Development Team builds WordPress. isolated the current response, meaning wp_send_document_isolation_policy_header() (see below) sent the header. A header a plugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party. sends itself does not count.
wp_get_media_library_mode() returns grid or list using the same resolution as upload.php, without updating the saved user option.
wp_get_media_library_upload_settings() returns the settings the pipeline needs: maximum upload size, allowed mime types, the registered image sub-sizes, and the image processing settings described below.
wp_enqueue_media_frame_upload() and wp_enqueue_media_new_upload() enqueue the screen scripts. wp_enqueue_media() calls the first one, so most code never needs to.
The image processing settings pass through the same filters the server uses: big_image_size_threshold, image_strip_meta and image_max_bit_depth. A plugin that changes them affects client-side uploads too. Because the server never decodes the image on this path, image_max_bit_depth receives 16, the maximum the client encoder can produce, as both its value and the current depth.
Three scripts were added: media-upload-pipeline, which configures the @wordpress/upload-media store and exposes wp.mediaUploadPipeline, plus media-frame-upload and media-new-upload, which hand files added to the existing uploader to the pipeline. They are only enqueued when client-side media processing is enabled, the browser supports Document-Isolation-Policy and core isolated the request.
What still uses the classic upload
When client-side processing is turned off with the wp_client_side_media_processing_enabled filter, or the browser does not support it (Firefox and Safari today), uploads work as they did in 7.1 through async-upload.php. Some uploads stay on the classic path even in a supported browser:
- Anything that is not an image the pipeline can process (JPEG, PNG, GIF, WebP, AVIF, HEIC/HEIF). Audio, video, PDF, SVG, JSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. and archives upload through
async-upload.php as before. So does an image whose type is not in the allowed mime types the page was rendered with, which leaves the decision to the server.
- Uploaders that do not post attachments. Only uploaders using
async-upload.php with the upload-attachment action are intercepted, so a plugin’s own wp.Uploader pointed elsewhere is left alone.
- JPEG and PNG files while plupload resizing is enabled, through the “Scale images” setting or a
resize value passed through plupload_init.
- A HEIC file the browser cannot decode (Linux, and Windows without the HEVC extension), when the server’s image editor supports HEIC. When neither can convert it, the pipeline’s error is shown.
- Screens core did not isolate: the Customizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings., the Site Icon picker, the classic editor’s media modal, and any screen where a plugin sends its own
Document-Isolation-Policy header.
Extra multipart params added through plupload_default_params or wp.Uploader.param() are forwarded to the REST request, so they still arrive in $_POST.
Multisite Used to describe a WordPress installation with a network of multiple blogs, grouped by sites. This installation type has shared users tables, and creates separate database tables for each blog (wp_posts becomes wp_0_posts). See also network, blog, site: sub-sizes count against the site’s upload space
On a multisite network (versus site, blog) with the “Site upload space” limit turned on, client-side media checks every file (including generated sub-sizes) against the site’s storage quota, not just the original.
On the classic path, only the original upload is checked (through check_upload_size() on wp_handle_upload_prefilter). The server then writes the sub-sizes straight to disk, so they never hit the quota check. With client-side media, each sub-size generated in the browser is a separate request to /wp/v2/media/{id}/sideload, and each one is checked for space left, the network’s maximum upload file size (fileupload_maxk) and the site quota.
In practice this only matters for a site that is close to its limit: the original fits, then some or all of the sub-sizes are rejected with rest_upload_limited_space or rest_upload_user_quota_exceeded.
When that happens:
- If some sub-sizes fit, the image is saved with only those sizes. The missing sizes are not currently reported to the user.
- If none fit, the upload fails: the attachment is deleted and the block resets. The error shown is the server’s message for the rejected sub-size, eg. “Not enough space to upload. 2 KB needed.”
Better handling for both cases is being worked on in #86834.
Note that networks with the upload space check disabled (the upload_space_check_disabled site option) are not affected.
A site that needs the old behavior can turn off client-side media processing:
add_filter( 'wp_client_side_media_processing_enabled', '__return_false' );
Sub-sizes in the attachment’s output format are allowed
Sideloaded sub-sizes also go through the network’s “Upload file types” setting (upload_filetypes). Networks created before 5.8 have no webp in that list and those created before 6.5 have no avif, so with a plugin filtering image_editor_output_format to either format, every sub-size was rejected and the upload failed.
In 7.2, the attachment’s output format is added to upload_filetypes for the duration of a sideload only, matching the classic path where the server writes sub-sizes in any output format. Other formats are still checked against the network setting, and a type removed through upload_mimes is still blocked. Single site is not affected.
Related: #66680, #66681, r65533.
Running the pipeline on a plugin’s own screen
The media frame integration only loads on a screen where wp_send_document_isolation_policy_header() sent the header. A Document-Isolation-Policy header a plugin sends itself does not count, so a page builder that isolates its editor for its own reasons keeps classic uploads in every wp.media frame on that screen, as in 7.1.
To opt a screen into the client-side pipeline, send the header through core before wp_enqueue_media() runs:
add_action( 'load-toplevel_page_my-plugin', function () {
if ( wp_is_client_side_media_processing_enabled() ) {
wp_send_document_isolation_policy_header();
}
} );
The function returns false and sends nothing when headers were already sent or the browser does not support the header. Isolating a screen blocks same-origin access to iframes that are not isolated too, so test the screen before opting in.
The Gutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc.
https://wordpress.org/gutenberg/ plugin sends the header itself on the editor screens, so its media modal uses classic uploads until the site runs a Gutenberg release that includes #86542. Uploads made in the block editor itself are not affected.
Related: #66490, r65356, r65532.
What changes for upload hooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same.
Pipeline uploads go to the REST API (POST /wp/v2/media, then /sideload per sub-size and /finalize) instead of async-upload.php. Most upload hooks still run, but a few things differ:
- Extra params added through
plupload_default_params or wp.Uploader.param() are sent as POST fields, so they still arrive in $_POST and $_REQUEST. action, _wpnonce and post_id are not forwarded: the attachment’s parent is sent as post.
$_POST['action'] is not upload-attachment and DOING_AJAX is not defined. Code that detects media uploads that way will miss pipeline uploads; check for a REST request, or hook the upload filters directly.
- The original file goes through
wp_handle_upload(), so wp_handle_upload_prefilter and upload_mimes run as before. Sub-sizes generated in the browser go through wp_handle_sideload(), so they run wp_handle_sideload_prefilter.
Related: r64588, #12585, Gutenberg #82409.
The editor no longer rewrites crossorigin attributes
In 7.1 the editor page was buffered with ob_start() and rewritten with WP_HTML_Tag_Processor to add crossorigin="anonymous" to cross-origin scripts, stylesheets, audio and video, alongside the Document-Isolation-Policy: isolate-and-credentialless header. That caused two problems:
- Running the tag A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.) processor inside an output buffer display handler could end in a fatal error and a blank screen on Chromium 137+ when the page loaded any cross-origin resource (#65930).
- Forcing
crossorigin="anonymous" turns a subresource load into a CORS request, which fails for any host that does not send Access-Control-Allow-Origin, such as media offloaded to a CDN (#65673).
With isolate-and-credentialless, cross-origin subresources load without credentials instead of being blocked, so the attribute was never needed. In testing with current Chromium builds, resources without the attribute loaded identically with and without the header.
What changed in 7.2
- The new
wp_send_document_isolation_policy_header() sends the header and returns whether it did. It returns false if headers were already sent or the browser does not support Document-Isolation-Policy.
wp_set_up_cross_origin_isolation() now returns that boolean instead of void.
- The editor page is no longer buffered or rewritten, and
wp_print_media_templates() no longer adds crossorigin="anonymous" to AUDIO and VIDEO tags in the media modal templates.
wp_start_cross_origin_isolation_output_buffer() and wp_add_crossorigin_attributes(), both added in 7.1, are deprecated. They still exist and trigger a deprecation notice. The first now only sends the header; the second returns the HTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. unchanged, so calls can be removed.
// Before (7.1).
wp_start_cross_origin_isolation_output_buffer();
// After (7.2).
wp_send_document_isolation_policy_header();
What plugin and theme developers should check
- Code that calls either deprecated function, or that parsed the editor output expecting
crossorigin attributes, needs updating. Hooking or removing wp_set_up_cross_origin_isolation on the load-* actions keeps working.
- Plugins that added their own
crossorigin injection to make cross-origin media work in the editor can drop it. Under isolate-and-credentialless it is not required, and it breaks hosts without CORS headers.
- To confirm isolation is active on a screen, check
window.crossOriginIsolated in the browser console. In browsers without Document-Isolation-Policy support, such as Firefox and Safari, it is false and uploads use the server as before.
- Safari support needs
require-corp, which does need the attribute. The Client-Side Media Everywhere plugin keeps the injection for that case.
- A response that has already sent headers before the
load-* action fires cannot receive the policy header. Debug output or early echo calls in a plugin are the usual cause.
Related: r64489, #13446, Gutenberg #82614.
Animated image sub-sizes are generated by default
Resized versions of animated GIFs have always lost their animation, because both GD and Imagick flatten animated images when resizing #28474 (open since 2014). Server-side it stalled because GD cannot preserve frames at all, Imagick is only available on some hosts, and re-encoding every frame is costly on shared CPU.
Client-side media processing changes that. Decoding, scaling and encoding happen in the uploader’s browser, so every frame can be processed regardless of the host, and the cost is paid once by the uploader #65656.
What changed in 7.2
When client-side media processing is used, every sub-size of an animated GIF or WebP keeps its animation by default, including cropped sizes such as thumbnail, where each frame is cropped with the same rectangle. If an animation is too large to decode in the browser, the pipeline falls back to a static first-frame sub-size instead of failing the upload.
Server-side uploads still produce static sub-sizes. The change only affects the client-side path.
The wp_generate_animated_image_subsizes filter
The new filter takes a boolean and defaults to true. Returning false generates static first-frame sub-sizes, matching the server-side path, which keeps upload times down on low powered devices or sites that upload many large animations.
add_filter( 'wp_generate_animated_image_subsizes', '__return_false' );
The Disable Animated Sub-sizes plugin does exactly this, for sites that prefer not to add code.
The filtered value is exposed on the REST API index as generate_animated_image_subsizes, alongside image_size_threshold and image_max_bit_depth, for users who can upload_files. The Media Library screens receive the same value through wp_get_media_library_upload_settings().
What developers should check
- Themes and plugins that assumed sub-sizes of an uploaded GIF or WebP are static first frames may now receive animated files, which are larger than a still frame.
wp_calculate_image_srcset() still declines to mix a full-size animated GIF with its sub-sizes in one srcset. With animated sub-sizes that guard is more conservative than it needs to be but harmless. Relaxing it is a possible follow-up.
- The client-side code ships through the Gutenberg package sync (Gutenberg #80385), so the filter and the REST field are the core-side surface.
Related: r64490, #12572, #28474.
Unattached images are auto-attached to posts when saved in the block editor
In the classic editor, images are auto-attached to a post as soon as a user picks them from the Media Library. This feature has been a gap in the block editor, where only images uploaded to a post were auto-attached. In WordPress 7.2 when a post is saved in the block editor, unattached images are auto-attached. This occurs later in the process than in the classic editor, so that an image added and then removed is not auto-attached.
Some details:
- This only runs on a successful manual save or publish of a post or page
- Only counts Image blocks (including within Galleries), and skips if there are more than 100 images to check
- Images already attached to another post or page are ignored
- Once a post is published, only images added since the last save are attached, so as not to unintentionally re-attach images that have been detached from a post
- Images in templates, template parts, and synced patterns are not affected
- This behaviour is editor-only as it’s part of a UX User experience workflow, so posts saved via REST API, WP-CLI WP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is http://wp-cli.org/ https://make.wordpress.org/cli/ etc are not affected
The feature is automatically disabled for sites with attachment pages enabled (the wp_attachment_pages_enabled option). On such sites, changing the attachment parent changes the attachment’s URL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org resulting in a 404 for the old URL, so the feature defaults to false.
For sites or plugins that wish to switch this feature on or off, the editor setting autoAttachMediaEnabled controls the behaviour. To turn it off, use the block_editor_settings_all filter:
add_filter( 'block_editor_settings_all', static function ( array $settings ): array {
$settings['autoAttachMediaEnabled'] = false;
return $settings;
} );
A site with attachment pages enabled can switch the feature on by setting the value above to true.
References
#7-2, #client-side-media, #dev-notes, #dev-notes-7-2, #media, #media-library
You must be logged in to post a comment.