wp_media_upload_handler()
云策文档标注
概述
wp_media_upload_handler() 是 WordPress 中处理媒体上传的核心函数，负责管理上传流程、表单提交和媒体插入到编辑器。它根据不同的 POST 请求参数执行相应操作，如文件上传、URL 插入或保存设置。
关键要点
- 函数返回类型为 null 或 string，用于输出上传页面的 iframe 内容或错误信息。
- 处理两种主要上传方式：通过“Upload File”按钮上传文件（使用 media_handle_upload()）和通过“Insert from URL”插入媒体链接。
- 针对非图像媒体（如音频、视频、文件），使用动态过滤器 {$type}_send_to_editor_url 处理 URL 发送到编辑器；图像则使用 image_send_to_editor_url 过滤器。
- 包含安全检查（如 check_admin_referer()）和错误处理（如 is_wp_error()），确保上传过程安全可靠。
- 函数内部调用多个相关函数，如 media_send_to_editor()、wp_iframe() 和 media_upload_form_handler()，以完成特定任务。
代码示例
// 示例：函数的基本调用场景（基于源码逻辑）
// 当用户点击“Upload File”按钮时，触发文件上传
if ( isset( $_POST['html-upload'] ) && ! empty( $_FILES ) ) {
check_admin_referer( 'media-form' );
$id = media_handle_upload( 'async-upload', $_REQUEST['post_id'] );
if ( is_wp_error( $id ) ) {
$errors['upload_error'] = $id;
}
}注意事项
- 此函数主要用于后台媒体上传页面，涉及大量 $_POST 和 $_GET 参数处理，开发者需确保参数安全验证。
- 动态过滤器 {$type}_send_to_editor_url 允许根据媒体类型（audio、video、file）自定义发送到编辑器的 HTML 内容。
- 函数自 WordPress 2.5.0 引入，属于核心上传系统的一部分，修改时需注意向后兼容性。
原文内容
Handles the process of uploading media.
Source
function wp_media_upload_handler() {
$errors = array();
$id = 0;
if ( isset( $_POST['html-upload'] ) && ! empty( $_FILES ) ) {
check_admin_referer( 'media-form' );
// Upload File button was clicked.
$id = media_handle_upload( 'async-upload', $_REQUEST['post_id'] );
unset( $_FILES );
if ( is_wp_error( $id ) ) {
$errors['upload_error'] = $id;
$id = false;
}
}
if ( ! empty( $_POST['insertonlybutton'] ) ) {
$src = $_POST['src'];
if ( ! empty( $src ) && ! strpos( $src, '://' ) ) {
$src = "http://$src";
}
if ( isset( $_POST['media_type'] ) && 'image' !== $_POST['media_type'] ) {
$title = esc_html( wp_unslash( $_POST['title'] ) );
if ( empty( $title ) ) {
$title = esc_html( wp_basename( $src ) );
}
if ( $title && $src ) {
$html = "<a href='" . esc_url( $src ) . "'>$title</a>";
}
$type = 'file';
$ext = preg_replace( '/^.+?.([^.]+)$/', '$1', $src );
if ( $ext ) {
$ext_type = wp_ext2type( $ext );
if ( 'audio' === $ext_type || 'video' === $ext_type ) {
$type = $ext_type;
}
}
/**
* Filters the URL sent to the editor for a specific media type.
*
* The dynamic portion of the hook name, `$type`, refers to the type
* of media being sent.
*
* Possible hook names include:
*
* - `audio_send_to_editor_url`
* - `file_send_to_editor_url`
* - `video_send_to_editor_url`
*
* @since 3.3.0
*
* @param string $html HTML markup sent to the editor.
* @param string $src Media source URL.
* @param string $title Media title.
*/
$html = apply_filters( "{$type}_send_to_editor_url", $html, sanitize_url( $src ), $title );
} else {
$align = '';
$alt = esc_attr( wp_unslash( $_POST['alt'] ) );
if ( isset( $_POST['align'] ) ) {
$align = esc_attr( wp_unslash( $_POST['align'] ) );
$class = " class='align$align'";
}
if ( ! empty( $src ) ) {
$html = "<img src='" . esc_url( $src ) . "' alt='$alt'$class />";
}
/**
* Filters the image URL sent to the editor.
*
* @since 2.8.0
*
* @param string $html HTML markup sent to the editor for an image.
* @param string $src Image source URL.
* @param string $alt Image alternate, or alt, text.
* @param string $align The image alignment. Default 'alignnone'. Possible values include
* 'alignleft', 'aligncenter', 'alignright', 'alignnone'.
*/
$html = apply_filters( 'image_send_to_editor_url', $html, sanitize_url( $src ), $alt, $align );
}
return media_send_to_editor( $html );
}
if ( isset( $_POST['save'] ) ) {
$errors['upload_notice'] = __( 'Saved.' );
wp_enqueue_script( 'admin-gallery' );
return wp_iframe( 'media_upload_gallery_form', $errors );
} elseif ( ! empty( $_POST ) ) {
$return = media_upload_form_handler();
if ( is_string( $return ) ) {
return $return;
}
if ( is_array( $return ) ) {
$errors = $return;
}
}
if ( isset( $_GET['tab'] ) && 'type_url' === $_GET['tab'] ) {
$type = 'image';
if ( isset( $_GET['type'] ) && in_array( $_GET['type'], array( 'video', 'audio', 'file' ), true ) ) {
$type = $_GET['type'];
}
return wp_iframe( 'media_upload_type_url_form', $type, $errors, $id );
}
return wp_iframe( 'media_upload_type_form', 'image', $errors, $id );
}
Hooks
- apply_filters( ‘image_send_to_editor_url’, string $html, string $src, string $alt, string $align )
-
Filters the image URL sent to the editor.
- apply_filters( “{$type}_send_to_editor_url”, string $html, string $src, string $title )
-
Filters the URL sent to the editor for a specific media type.
Changelog
| Version | Description |
|---|---|
| 2.5.0 | Introduced. |