attachment_fields_to_save

💡 云策文档标注

概述

attachment_fields_to_save 是一个 WordPress 过滤器，用于在保存附件时过滤其关联数据。它主要处理来自媒体上传屏幕的输入，并为 post_title 等字段提供默认值。

关键要点

过滤器用于过滤附件的关联数据，如标题和描述。
默认接收媒体上传屏幕的输入，并在用户未提供时设置 post_title 的默认值。
必须返回处理后的 $post 数组，供 media_upload_form_handler 函数使用。
插件或主题可以通过 add_filter 注册此过滤器来修改附件保存行为。
注意：根据 ticket #30687，通过 $post['errors'] 传递的验证错误会被静默清除，不会通知用户。

代码示例

function wpdocs_insert_custom_default_caption( $post ) {
    if ( 'image' === substr( $post['post_mime_type'], 0, 5 ) ) {
        if ( 0 === strlen( trim( $post['post_title'] ) ) ) {
            $post['post_title'] = preg_replace( '/.w+$/', '', basename( $post['guid'] ) );
            $post['errors']['post_title']['errors'][] = __( 'Empty Title filled from filename.' );
        }

        // captions are saved as the post_excerpt, so we check for it before overwriting
        // if no captions were provided by the user, we fill it with our default
        if ( 0 === strlen( trim( $post['post_excerpt'] ) ) ) {
            $post['post_excerpt'] = 'default caption';
        }
    }

    return $post;
}

add_filter( 'attachment_fields_to_save', 'wpdocs_insert_custom_default_caption' );

注意事项

过滤器函数必须返回 $post 数组，否则可能导致附件保存失败。
使用此过滤器时，需注意 $post['errors'] 的处理方式，以避免用户界面问题。

📄 原文内容

Filters the attachment fields to be saved.

Description

Parameters

$postarray: An array of post data.
$attachmentarray: An array of attachment metadata.

More Information

The attachment_fields_to_save filter is used to filter the associated data of images.

By default, it receives the input from the Media Upload screen and provides default values to the post_title, in case the user hasn’t done so.

It returns the $post array to be handled by the media_upload_form_handler function.

A plugin (or theme) can register as a content filter with the code:

Where ‘filter_function_name’ is the function WordPress should call when an attachment is being saved.

Note that the filter function must return the $post array after it is finished processing.

NOTE: per ticket #30687, any validation errors passed in via $post['errors'] array are silently unset and the attachment is processed without notifying the user

Source

$post = apply_filters( 'attachment_fields_to_save', $post, $attachment );

View all references View on Trac View on GitHub

Used by	Description
media_upload_form_handler()`wp-admin/includes/media.php`	Handles form submissions for the legacy media uploader.
edit_post()`wp-admin/includes/post.php`	Updates an existing post with values provided in `$_POST`.
wp_ajax_save_attachment_compat()`wp-admin/includes/ajax-actions.php`	Handles saving backward compatible attachment attributes via AJAX.

Changelog

Version	Description
2.5.0	Introduced.

User Contributed Notes

Skip to note 3 content

Collins Mbaka

5 years ago

To insert a default caption for images:

function wpdocs_insert_custom_default_caption( $post ) {
    if ( 'image' === substr( $post['post_mime_type'], 0, 5 ) ) {
        if ( 0 === strlen( trim( $post['post_title'] ) ) ) {
            $post['post_title'] = preg_replace( '/.w+$/', '', basename( $post['guid'] ) );
            $post['errors']['post_title']['errors'][] = __( 'Empty Title filled from filename.' );
        }

        // captions are saved as the post_excerpt, so we check for it before overwriting
        // if no captions were provided by the user, we fill it with our default
        if ( 0 === strlen( trim( $post['post_excerpt'] ) ) ) {
            $post['post_excerpt'] = 'default caption';
        }
    }

    return $post;
}

add_filter( 'attachment_fields_to_save', 'wpdocs_insert_custom_default_caption' );

Skip to note 4 content

Akira Tachibana

5 years ago

(From Codex)
To insert a default caption for images:

function insert_custom_default_caption($post, $attachment) {
if ( substr($post['post_mime_type'], 0, 5) == 'image' ) {
    if ( strlen(trim($post['post_title'])) == 0 ) {
        $post['post_title'] = preg_replace('/.w+$/', '', basename($post['guid']));
        $post['errors']['post_title']['errors'][] = __('Empty Title filled from filename.');
    }
    // captions are saved as the post_excerpt, so we check for it before overwriting
    // if no captions were provided by the user, we fill it with our default
    if ( strlen(trim($post['post_excerpt'])) == 0 ) {
        $post['post_excerpt'] = 'default caption';
    }
}

return $post;
}

add_filter('attachment_fields_to_save', 'insert_custom_default_caption', 10, 2);

云策 WordPress 开发者社区

钩子文档