Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Plugin API/Filter Reference/attachment fields to save

This page is marked as incomplete. You can help Codex by expanding it.


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:

<?php add_filter( 'attachment_fields_to_save', 'filter_function_name', 10, 2 ) ?>

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


(array) (required) Post attributes.
Default: None
(array) (required) Attachment fields.
Default: None

Example Usage

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);


External Resources

See Also