Title: Custom_Background::handle_upload
Published: April 25, 2014
Last modified: February 24, 2026

---

# Custom_Background::handle_upload()

## In this article

 * [Source](https://developer.wordpress.org/reference/classes/custom_background/handle_upload/?output_format=md#source)
 * [Hooks](https://developer.wordpress.org/reference/classes/custom_background/handle_upload/?output_format=md#hooks)
 * [Related](https://developer.wordpress.org/reference/classes/custom_background/handle_upload/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/classes/custom_background/handle_upload/?output_format=md#changelog)

[ Back to top](https://developer.wordpress.org/reference/classes/custom_background/handle_upload/?output_format=md#wp--skip-link--target)

Handles an Image upload for the background image.

## 󠀁[Source](https://developer.wordpress.org/reference/classes/custom_background/handle_upload/?output_format=md#source)󠁿

    ```php
    public function handle_upload() {
    	if ( empty( $_FILES ) ) {
    		return;
    	}

    	check_admin_referer( 'custom-background-upload', '_wpnonce-custom-background-upload' );

    	$overrides = array( 'test_form' => false );

    	$uploaded_file = $_FILES['import'];
    	$wp_filetype   = wp_check_filetype_and_ext( $uploaded_file['tmp_name'], $uploaded_file['name'] );
    	if ( ! wp_match_mime_types( 'image', $wp_filetype['type'] ) ) {
    		wp_die( __( 'The uploaded file is not a valid image. Please try again.' ) );
    	}

    	$file = wp_handle_upload( $uploaded_file, $overrides );

    	if ( isset( $file['error'] ) ) {
    		wp_die( $file['error'] );
    	}

    	$url      = $file['url'];
    	$type     = $file['type'];
    	$file     = $file['file'];
    	$filename = wp_basename( $file );

    	// Construct the attachment array.
    	$attachment = array(
    		'post_title'     => $filename,
    		'post_content'   => $url,
    		'post_mime_type' => $type,
    		'guid'           => $url,
    		'context'        => 'custom-background',
    	);

    	// Save the data.
    	$id = wp_insert_attachment( $attachment, $file );

    	// Add the metadata.
    	wp_update_attachment_metadata( $id, wp_generate_attachment_metadata( $id, $file ) );
    	update_post_meta( $id, '_wp_attachment_is_custom_background', get_option( 'stylesheet' ) );

    	set_theme_mod( 'background_image', sanitize_url( $url ) );

    	$thumbnail = wp_get_attachment_image_src( $id, 'thumbnail' );
    	set_theme_mod( 'background_image_thumb', sanitize_url( $thumbnail[0] ) );

    	/** This filter is documented in wp-admin/includes/class-custom-image-header.php */
    	$file = apply_filters( 'wp_create_file_in_uploads', $file, $id ); // For replication.

    	$this->updated = true;
    }
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-admin/includes/class-custom-background.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-admin/includes/class-custom-background.php#L512)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-admin/includes/class-custom-background.php#L512-L563)

## 󠀁[Hooks](https://developer.wordpress.org/reference/classes/custom_background/handle_upload/?output_format=md#hooks)󠁿

 [apply_filters( ‘wp_create_file_in_uploads’, string $file, int $attachment_id )](https://developer.wordpress.org/reference/hooks/wp_create_file_in_uploads/)

Filters the attachment file path after the custom header or background image is 
set.

## 󠀁[Related](https://developer.wordpress.org/reference/classes/custom_background/handle_upload/?output_format=md#related)󠁿

| Uses | Description | 
| [wp_generate_attachment_metadata()](https://developer.wordpress.org/reference/functions/wp_generate_attachment_metadata/)`wp-admin/includes/image.php` |

Generates attachment meta data and create image sub-sizes for images.

  | 
| [wp_handle_upload()](https://developer.wordpress.org/reference/functions/wp_handle_upload/)`wp-admin/includes/file.php` |

Wrapper for [_wp_handle_upload()](https://developer.wordpress.org/reference/functions/_wp_handle_upload/) .

  | 
| [set_theme_mod()](https://developer.wordpress.org/reference/functions/set_theme_mod/)`wp-includes/theme.php` |

Updates theme modification value for the active theme.

  | 
| [check_admin_referer()](https://developer.wordpress.org/reference/functions/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_check_filetype_and_ext()](https://developer.wordpress.org/reference/functions/wp_check_filetype_and_ext/)`wp-includes/functions.php` |

Attempts to determine the real file type of a file.

  | 
| [wp_get_attachment_image_src()](https://developer.wordpress.org/reference/functions/wp_get_attachment_image_src/)`wp-includes/media.php` |

Retrieves an image to represent an attachment.

  | 
| [wp_insert_attachment()](https://developer.wordpress.org/reference/functions/wp_insert_attachment/)`wp-includes/post.php` |

Inserts an attachment.

  | 
| [wp_update_attachment_metadata()](https://developer.wordpress.org/reference/functions/wp_update_attachment_metadata/)`wp-includes/post.php` |

Updates metadata for an attachment.

  | 
| [wp_match_mime_types()](https://developer.wordpress.org/reference/functions/wp_match_mime_types/)`wp-includes/post.php` |

Checks a MIME-Type against a list.

  | 
| [update_post_meta()](https://developer.wordpress.org/reference/functions/update_post_meta/)`wp-includes/post.php` |

Updates a post meta field based on the given post ID.

  | 
| [__()](https://developer.wordpress.org/reference/functions/__/)`wp-includes/l10n.php` |

Retrieves the translation of $text.

  | 
| [wp_basename()](https://developer.wordpress.org/reference/functions/wp_basename/)`wp-includes/formatting.php` |

i18n-friendly version of basename().

  | 
| [sanitize_url()](https://developer.wordpress.org/reference/functions/sanitize_url/)`wp-includes/formatting.php` |

Sanitizes a URL for database or redirect usage.

  | 
| [wp_die()](https://developer.wordpress.org/reference/functions/wp_die/)`wp-includes/functions.php` |

Kills WordPress execution and displays HTML page with an error message.

  | 
| [apply_filters()](https://developer.wordpress.org/reference/functions/apply_filters/)`wp-includes/plugin.php` |

Calls the callback functions that have been added to a filter hook.

  | 
| [get_option()](https://developer.wordpress.org/reference/functions/get_option/)`wp-includes/option.php` |

Retrieves an option value based on an option name.

  |

[Show 11 more](https://developer.wordpress.org/reference/classes/custom_background/handle_upload/?output_format=md#)
[Show less](https://developer.wordpress.org/reference/classes/custom_background/handle_upload/?output_format=md#)

## 󠀁[Changelog](https://developer.wordpress.org/reference/classes/custom_background/handle_upload/?output_format=md#changelog)󠁿

| Version | Description | 
| [3.0.0](https://developer.wordpress.org/reference/since/3.0.0/) | Introduced. |

## User Contributed Notes

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Fclasses%2Fcustom_background%2Fhandle_upload%2F)
before being able to contribute a note or feedback.