wp_ajax_upload_attachment()
云策文档标注
概述
wp_ajax_upload_attachment() 是一个 WordPress AJAX 处理函数，用于通过 AJAX 上传附件文件。它执行权限检查、文件验证，并调用 media_handle_upload() 处理上传，最终返回 JSON 格式的响应。
关键要点
- 函数通过 check_ajax_referer() 验证 AJAX 请求，确保安全性。
- 检查当前用户是否具有 upload_files 权限，若无权限则返回错误信息。
- 如果提供了 post_id，会验证用户是否有 edit_post 权限来附加文件到该文章。
- 处理 post_data 参数，使用 _wp_translate_postdata() 和 _wp_get_allowed_postdata() 转换和过滤数据。
- 对于 custom-header 或 custom-background 上下文，验证上传文件是否为有效图像，使用 wp_check_filetype_and_ext() 和 wp_match_mime_types()。
- 调用 media_handle_upload() 上传文件并创建附件文章，处理可能的 WP_Error。
- 根据上下文更新附件的元数据，如 _wp_attachment_is_custom_background 或 _wp_attachment_is_custom_header。
- 使用 wp_prepare_attachment_for_js() 准备附件数据，并以 JSON 格式返回成功或错误响应。
- 函数不使用 wp_send_json_success()/wp_send_json_error()，以兼容旧版 IE 的 text/html Content-Type 要求。
代码示例
// 示例调用（通常通过 AJAX 触发）
// 假设通过 jQuery AJAX 发送请求
jQuery.ajax({
url: ajaxurl,
type: 'POST',
data: {
action: 'upload-attachment',
_ajax_nonce: nonce_value,
post_id: 123,
post_data: { context: 'custom-header', theme: 'mytheme' }
},
success: function(response) {
console.log(response);
}
});注意事项
- 函数依赖于 $_FILES['async-upload'] 和 $_REQUEST 参数，确保前端表单正确设置。
- 权限检查是关键，避免未授权上传或修改。
- 对于图像验证，仅针对特定上下文执行，其他文件类型可能不受限制。
- 响应格式为 JSON，但 Content-Type 可能为 text/html 以兼容旧浏览器。
原文内容
Handles uploading attachments via AJAX.
Source
function wp_ajax_upload_attachment() {
check_ajax_referer( 'media-form' );
/*
* This function does not use wp_send_json_success() / wp_send_json_error()
* as the html4 Plupload handler requires a text/html Content-Type for older IE.
* See https://core.trac.wordpress.org/ticket/31037
*/
if ( ! current_user_can( 'upload_files' ) ) {
echo wp_json_encode(
array(
'success' => false,
'data' => array(
'message' => __( 'Sorry, you are not allowed to upload files.' ),
'filename' => esc_html( $_FILES['async-upload']['name'] ),
),
)
);
wp_die();
}
if ( isset( $_REQUEST['post_id'] ) ) {
$post_id = $_REQUEST['post_id'];
if ( ! current_user_can( 'edit_post', $post_id ) ) {
echo wp_json_encode(
array(
'success' => false,
'data' => array(
'message' => __( 'Sorry, you are not allowed to attach files to this post.' ),
'filename' => esc_html( $_FILES['async-upload']['name'] ),
),
)
);
wp_die();
}
} else {
$post_id = null;
}
$post_data = ! empty( $_REQUEST['post_data'] ) ? _wp_get_allowed_postdata( _wp_translate_postdata( false, (array) $_REQUEST['post_data'] ) ) : array();
if ( is_wp_error( $post_data ) ) {
wp_die( $post_data->get_error_message() );
}
// If the context is custom header or background, make sure the uploaded file is an image.
if ( isset( $post_data['context'] ) && in_array( $post_data['context'], array( 'custom-header', 'custom-background' ), true ) ) {
$wp_filetype = wp_check_filetype_and_ext( $_FILES['async-upload']['tmp_name'], $_FILES['async-upload']['name'] );
if ( ! wp_match_mime_types( 'image', $wp_filetype['type'] ) ) {
echo wp_json_encode(
array(
'success' => false,
'data' => array(
'message' => __( 'The uploaded file is not a valid image. Please try again.' ),
'filename' => esc_html( $_FILES['async-upload']['name'] ),
),
)
);
wp_die();
}
}
$attachment_id = media_handle_upload( 'async-upload', $post_id, $post_data );
if ( is_wp_error( $attachment_id ) ) {
echo wp_json_encode(
array(
'success' => false,
'data' => array(
'message' => $attachment_id->get_error_message(),
'filename' => esc_html( $_FILES['async-upload']['name'] ),
),
)
);
wp_die();
}
if ( isset( $post_data['context'] ) && isset( $post_data['theme'] ) ) {
if ( 'custom-background' === $post_data['context'] ) {
update_post_meta( $attachment_id, '_wp_attachment_is_custom_background', $post_data['theme'] );
}
if ( 'custom-header' === $post_data['context'] ) {
update_post_meta( $attachment_id, '_wp_attachment_is_custom_header', $post_data['theme'] );
}
}
$attachment = wp_prepare_attachment_for_js( $attachment_id );
if ( ! $attachment ) {
wp_die();
}
echo wp_json_encode(
array(
'success' => true,
'data' => $attachment,
)
);
wp_die();
}
Changelog
| Version | Description |
|---|---|
| 3.3.0 | Introduced. |