| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Source view] [Print] [Project Stats]
Shared glue for routing classic admin uploads through the client-side media pipeline. The media frames (media-frame-upload.js) and the Add New Media File screen (media-new-upload.js) both intercept plupload and hand files to @wordpress/upload-media instead. Everything that is not specific to one screen's UI lives here: feature detection, configuring the upload-media store once, the REST sideload/finalize/delete helpers the store needs, queueing a file with success, error, and progress callbacks, the error text shown for a failed upload, and the guard that warns before leaving while uploads are in flight.
| File Size: | 739 lines (24 kb) |
| Included or required: | 0 times |
| Referenced: | 0 times |
| Includes or requires: | 0 files |
| flattenFormData( formData, key, data ) X-Ref |
| Recursively appends data to a FormData object, supporting nested objects. Mirrors flattenFormData() in the media-utils package. param: {FormData} formData The form data to append to. param: {string} key The key to append under. param: {*} data The value to append. |
| mediaSideload( args ) X-Ref |
| Sideloads a client-generated thumbnail to an existing attachment. Reimplements the private sideloadMedia() helper from the media-utils package as a thin apiFetch wrapper. param: {Object} args The sideload arguments. param: {File} args.file The sub-size to sideload. param: {number} args.attachmentId The attachment to sideload it to. param: {Record<string, unknown>} [args.additionalData] Extra fields to send with it. param: {AbortSignal} [args.signal] Signal aborting the request. param: {( subSize: Object ) => void} [args.onSuccess] Called with the sideloaded sub-size. param: {( error: Error ) => void} [args.onError] Called when the sideload failed. |
| mediaDelete( id ) X-Ref |
| Deletes an attachment whose client-side processing failed outright. The queue calls this when every sub-size sideload for an upload fails: without it the original file is left behind as an attachment with no metadata, visible in the Media Library after the next page load. The block editor passes the same setting. param: {number} id The attachment ID to delete. return: {Promise<unknown>} Resolves once the attachment is deleted. |
| hasDependencies() X-Ref |
| Whether every script the pipeline relies on is present. return: {boolean} True when the dependencies loaded. |
| isSupported() X-Ref |
| Whether the browser can run the client-side pipeline on this page. False when the isolation headers did not land (the page is not cross-origin isolated) or the browser lacks the required features, in which case classic plupload keeps handling uploads. return: {boolean} True when client-side processing is available. |
| estimateProgress( item, entry ) X-Ref |
| Estimates the progress (0-100) of a queue item. The pipeline never reports a numeric `progress` on its queue items (nothing dispatches updateItemProgress), so estimate one from the item's operation queue instead: each finished operation (prepare, transcode, upload, thumbnails, finalize) advances the bar, and the sub-sizes sideloaded so far advance it within thumbnail generation. `item.progress` is preferred whenever it is present. param: {QueueItem} item The upload-media queue item. param: {UploadEntry} entry The pipeline's bookkeeping for the upload. return: {number} Estimated progress. |
| onStoreChange() X-Ref |
| Tracks queued uploads on every change to the upload-media store. Reports progress, which holds at 99 until the upload's success callback has run so nothing looks finished before the screen has synced the result, and notes the attachment once the original is uploaded. Sub-size children are skipped; only top-level items matter. The store can also remove an item without calling either of its callbacks (it only calls onSuccess when the item has an attachment), so an upload that was seen in the store and is gone fails here instead of staying in flight, and holding the unload guard, for good. |
| isStoreConfigured() X-Ref |
| Whether something else already configured the store on this page. The block editor renders its own MediaUploadProvider into the same store. Neither `mediaSideload` nor `mediaFinalize` has a default, so their presence proves a provider's settings landed, whichever one rendered them. return: {boolean} True when the store carries a provider's settings. |
| configure() X-Ref |
| Configures the upload-media store for this page, once. Rendering the provider with useSubRegistry: false wires the settings into the store that wp.data.dispatch/select address. The block editor does the same for its own uploads, so on its screens no second provider is rendered: whichever committed last would win, and this one could replace the editor's mediaUpload. Uploads wait for the editor's settings instead (see isReady()). return: {boolean} True when the pipeline is configured and usable. |
| addUnloadGuard() X-Ref |
| Warns before leaving while uploads are in flight. Thumbnails that have not been sideloaded yet are lost and the attachment is left unfinalized, unlike classic uploads that complete server-side once the bytes arrive. |
| isReady() X-Ref |
| Whether the store has received a provider's settings. A provider renders asynchronously, so a file added before its settings land must be left to classic plupload - a degradation, never data loss. The store's default state already carries a no-op `mediaUpload`, so only settings a provider alone supplies prove the real ones have landed: a file queued before that would be handed to the no-op and never upload. On block editor screens only the editor's provider supplies them. return: {boolean} True when the store is ready to accept files. |
| partitionBatch( up, files ) X-Ref |
| Splits a batch of plupload files between the pipeline and classic plupload. Audio files stay classic so they keep the title and description that media_handle_upload() derives from their ID3 tags, which the REST endpoint does not do. So do JPEG and PNG images while plupload's own client-side resize is enabled (the "Scale images" setting, or a `resize` passed through `plupload_init`): plupload scales those down before uploading them, the pipeline would not. The whole batch stays classic when a file cannot be re-queued on plupload or is already plupload's: plupload returns no native File for sources it cannot expose as one (the html4 runtime, say), and a file the pipeline handed back (see handOffToClassic()) is plupload's to upload. param: {plupload.Uploader} up The plupload uploader the files were added to. param: {plupload.File[]} files Files added to the plupload queue. return: {{ pipeline: plupload.File[], classic: plupload.File[] }|null} The split, |
| addClassicFile( up, nativeFile ) X-Ref |
| Hands a file to classic plupload, whose own FilesAdded handler queues and starts the upload. param: {plupload.Uploader} up The plupload uploader. param: {File} nativeFile The file to upload. |
| handOffBatchToClassic( up, files ) X-Ref |
| Re-queues the classic share of a batch on plupload. Suppressing plupload's built-in FilesAdded handler covers the whole batch, so the files partitionBatch() left to plupload are removed and added back on their own. param: {plupload.Uploader} up The plupload uploader. param: {plupload.File[]} files The files to upload classically. |
| handOffToClassic( up, error, nativeFile ) X-Ref |
| Re-queues a file on classic plupload when the server can do what the browser could not. The pipeline converts HEIC in the browser and fails outright when the platform has no HEIC decoder (Linux, and Windows without the HEVC extension), whereas the classic upload lets the server convert it. When the server's image editor supports HEIC - plupload carries no `heic_upload_error` setting then - the file goes back to plupload, whose own FilesAdded handler queues and starts the classic upload. Nothing else can convert it, so any other failure stands. param: {plupload.Uploader} up The plupload uploader the file came from. param: {UploadError} error Why the pipeline gave up on it. param: {File} nativeFile The file the pipeline was given. return: {boolean} True when the file was handed to classic plupload. |
| additionalDataFromParams( params, postId ) X-Ref |
| Builds the extra fields to send with an upload from plupload's multipart params. Anything a plugin added through the `plupload_default_params` filter or wp.Uploader.param() reached the classic upload as $_POST fields, so it is forwarded to the REST request the same way. The classic transport's own fields are dropped: `action` and `_wpnonce` belong to async-upload.php, and `post_id` is spelled `post` by the REST API and passed separately after the screen has validated it. param: {Record<string, string>} params Plupload's multipart_params. param: {number} postId The validated post to attach the upload to, or 0. return: {Record<string, unknown>} Additional data for the upload. |
| queueFile( nativeFile, additionalData, callbacks = {} ) X-Ref |
| Queues a file for client-side processing and upload. param: {File} nativeFile The file to upload. param: {Record<string, unknown>} additionalData Extra fields to send with the attachment. param: {QueueFileCallbacks} [callbacks] Lifecycle callbacks. |
| onSuccess( attachments ) X-Ref |
| Handles successful upload. param: {PipelineAttachment[]} attachments The uploaded attachments. |
| routeBatch( up, files, options ) X-Ref |
| Routes a batch of files added to a plupload uploader through the pipeline. Returns undefined (not false) when the pipeline cannot take the batch so plupload's built-in FilesAdded handler runs and uploads it server-side - a degradation, never data loss. Otherwise queues the files the pipeline can take, re-queues the rest on plupload, and returns false to suppress the built-in handler, which would otherwise start a classic upload of every file. The classic flow posts plupload's multipart params to async-upload.php, so they are forwarded to the REST request for plugins reading $_POST, with `post_id` replaced by `options.postId`. param: {plupload.Uploader} up The plupload uploader the files were added to. param: {plupload.File[]} files Files added to the queue. param: {RouteBatchOptions} options The screen's hooks. return: {boolean|undefined} False to suppress the built-in handler. |
| getErrorText( error, fileName ) X-Ref |
| Builds the display text for a failed upload. wp.uploadMedia.getErrorMessage() maps an error *code* and a file name to a { title, description, action } object, so it can neither be handed the Error itself nor used as a string. Only codes it actually maps are worth using: its fallback (and the GENERAL code) says nothing the error's own message does not, and preferring the message there keeps a server-supplied reason instead of replacing it with "Please try again." param: {UploadError} error The upload error. param: {string} fileName Name of the file that failed to upload. return: {string} A human-readable message. |
| Generated : Tue Oct 20 08:20:34 2026 | Cross-referenced by PHPXref |