media_upload_form_handler()

💡 云策文档标注

概述

media_upload_form_handler() 函数用于处理传统媒体上传器的表单提交，主要处理附件数据的更新和错误返回。它验证用户权限，更新附件内容、标题、摘要、菜单顺序等字段，并处理图像替代文本和分类法。

关键要点

函数处理传统媒体上传器的表单提交，返回错误信息数组（键为附件ID）或在成功时返回null或void。
使用check_admin_referer()验证安全nonce，确保表单提交来自管理员页面。
遍历$_POST['attachments']数组，检查用户是否有edit_post权限，更新附件内容、标题、摘要、菜单顺序等字段。
如果设置了$_POST['send']，处理发送到编辑器的附件，包括更新post_parent字段。
应用attachment_fields_to_save过滤器，允许自定义保存的附件字段。
更新图像替代文本（_wp_attachment_image_alt元数据），使用wp_unslash()和wp_slash()处理转义。
处理附件分类法，使用wp_set_object_terms()设置术语关系。
如果设置了$_POST['insert-gallery']或$_POST['update-gallery']，生成HTML并应用media_send_to_editor过滤器，然后调用media_send_to_editor()函数。
相关函数包括media_send_to_editor()、wp_update_post()、update_post_meta()等，用于媒体处理和数据库操作。

代码示例

// 示例调用（基于函数逻辑）
// 假设在表单提交后调用此函数
$errors = media_upload_form_handler();
if ( $errors ) {
    // 处理错误
    foreach ( $errors as $attachment_id => $error ) {
        echo "附件ID $attachment_id 错误: " . $error;
    }
} else {
    // 成功处理
    echo "表单提交成功。";
}

注意事项

此函数是传统媒体上传器的一部分，可能不适用于新的块编辑器（Gutenberg）环境。
函数依赖于$_POST全局变量，确保在调用前表单数据已正确设置。
使用current_user_can()检查用户权限，避免未授权访问。
错误处理：返回的数组键为附件ID，值为错误消息，需在调用后检查。
过滤器attachment_fields_to_save和media_send_to_editor允许开发者自定义行为。

📄 原文内容

Handles form submissions for the legacy media uploader.

Return

null|array|void Array of error messages keyed by attachment ID, null or void on success.

Source

function media_upload_form_handler() {
	check_admin_referer( 'media-form' );

	$errors = null;

	if ( isset( $_POST['send'] ) ) {
		$keys    = array_keys( $_POST['send'] );
		$send_id = (int) reset( $keys );
	}

	if ( ! empty( $_POST['attachments'] ) ) {
		foreach ( $_POST['attachments'] as $attachment_id => $attachment ) {
			$post  = get_post( $attachment_id, ARRAY_A );
			$_post = $post;

			if ( ! current_user_can( 'edit_post', $attachment_id ) ) {
				continue;
			}

			if ( isset( $attachment['post_content'] ) ) {
				$post['post_content'] = $attachment['post_content'];
			}

			if ( isset( $attachment['post_title'] ) ) {
				$post['post_title'] = $attachment['post_title'];
			}

			if ( isset( $attachment['post_excerpt'] ) ) {
				$post['post_excerpt'] = $attachment['post_excerpt'];
			}

			if ( isset( $attachment['menu_order'] ) ) {
				$post['menu_order'] = $attachment['menu_order'];
			}

			if ( isset( $send_id ) && $attachment_id === $send_id ) {
				if ( isset( $attachment['post_parent'] ) ) {
					$post['post_parent'] = $attachment['post_parent'];
				}
			}

			/**
			 * Filters the attachment fields to be saved.
			 *
			 * @since 2.5.0
			 *
			 * @see wp_get_attachment_metadata()
			 *
			 * @param array $post       An array of post data.
			 * @param array $attachment An array of attachment metadata.
			 */
			$post = apply_filters( 'attachment_fields_to_save', $post, $attachment );

			if ( isset( $attachment['image_alt'] ) ) {
				$image_alt = wp_unslash( $attachment['image_alt'] );

				if ( get_post_meta( $attachment_id, '_wp_attachment_image_alt', true ) !== $image_alt ) {
					$image_alt = wp_strip_all_tags( $image_alt, true );

					// update_post_meta() expects slashed.
					update_post_meta( $attachment_id, '_wp_attachment_image_alt', wp_slash( $image_alt ) );
				}
			}

			if ( isset( $post['errors'] ) ) {
				$errors[ $attachment_id ] = $post['errors'];
				unset( $post['errors'] );
			}

			if ( $post != $_post ) {
				wp_update_post( $post );
			}

			foreach ( get_attachment_taxonomies( $post ) as $t ) {
				if ( isset( $attachment[ $t ] ) ) {
					wp_set_object_terms( $attachment_id, array_map( 'trim', preg_split( '/,+/', $attachment[ $t ] ) ), $t, false );
				}
			}
		}
	}

	if ( isset( $_POST['insert-gallery'] ) || isset( $_POST['update-gallery'] ) ) {
		?>
		<script type="text/javascript">
		var win = window.dialogArguments || opener || parent || top;
		win.tb_remove();
		</script>
		$html</a>";
		}

		/**
		 * Filters the HTML markup for a media item sent to the editor.
		 *
		 * @since 2.5.0
		 *
		 * @see wp_get_attachment_metadata()
		 *
		 * @param string $html       HTML markup for a media item sent to the editor.
		 * @param int    $send_id    The first key from the $_POST['send'] data.
		 * @param array  $attachment Array of attachment metadata.
		 */
		$html = apply_filters( 'media_send_to_editor', $html, $send_id, $attachment );

		return media_send_to_editor( $html );
	}

	return $errors;
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘attachment_fields_to_save’, array $post, array $attachment ): Filters the attachment fields to be saved.
apply_filters( ‘media_send_to_editor’, string $html, int $send_id, array $attachment ): Filters the HTML markup for a media item sent to the editor.

Uses	Description
media_send_to_editor()`wp-admin/includes/media.php`	Adds image HTML to editor.
wp_strip_all_tags()`wp-includes/formatting.php`	Properly strips all HTML tags including ‘script’ and ‘style’.
check_admin_referer()`wp-includes/pluggable.php`	Ensures intent by verifying that a user was referred from another admin page with the correct security nonce.
wp_set_object_terms()`wp-includes/taxonomy.php`	Creates term and taxonomy relationships.
get_attachment_link()`wp-includes/link-template.php`	Retrieves the permalink for an attachment.
get_attachment_taxonomies()`wp-includes/media.php`	Retrieves taxonomies attached to given the attachment.
wp_update_post()`wp-includes/post.php`	Updates a post with new post data.
update_post_meta()`wp-includes/post.php`	Updates a post meta field based on the given post ID.
current_user_can()`wp-includes/capabilities.php`	Returns whether the current user has the specified capability.
wp_unslash()`wp-includes/formatting.php`	Removes slashes from a string or recursively removes slashes from strings within an array.
wp_slash()`wp-includes/formatting.php`	Adds slashes to a string or recursively adds slashes to strings within an array.
esc_attr()`wp-includes/formatting.php`	Escaping for HTML attributes.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.
get_post_meta()`wp-includes/post.php`	Retrieves a post meta field for the given post ID.
get_post()`wp-includes/post.php`	Retrieves post data given a post ID or post object.

Show 10 more Show less

Used by	Description
wp_media_upload_handler()`wp-admin/includes/media.php`	Handles the process of uploading media.
media_upload_gallery()`wp-admin/includes/media.php`	Retrieves the legacy media uploader form in an iframe.
media_upload_library()`wp-admin/includes/media.php`	Retrieves the legacy media library form in an iframe.

Changelog

Version	Description
2.5.0	Introduced.

云策 WordPress 开发者社区

函数文档

media_upload_form_handler()

概述

关键要点

代码示例

注意事项

Return

Source

Hooks

Changelog

函数文档

概述

关键要点

代码示例

注意事项

Return

Source

Hooks

Related

Changelog