wp_delete_attachment() │ WP 2.0.0

Trash or delete an attachment.

When an attachment is permanently deleted, the file will also be removed. Deletion removes all post meta fields, taxonomy, comments, etc. associated with the attachment (except the main post).

The attachment is moved to the Trash instead of permanently deleted unless Trash for media is disabled, item is already in the Trash, or $force_delete is true.

Uses: wp_delete_attachment_files()

Hooks from the function

pre_delete_attachment

delete_attachment

delete_post

deleted_post

Return

WP_Post|false|null. Post data on success, false or null on failure.

Usage

wp_delete_attachment( $post_id, $force_delete );

$post_id(int) (required): Attachment ID.
$force_delete(true|false): Whether to bypass Trash and force deletion.
Default: false

Examples

#1 Deleting an attachment

We will irrevocably delete the attachment with ID 54:

wp_delete_attachment( 54, true );

#2 Delete all post attachments (attached files), along with the deletion of the post

On some blogs it is convenient to make it so that when you delete a post, all the media files attached to it would be deleted along with it. You can do it this way:

// Deletes all post attachments (attached media files) along with the post(s)
add_action( 'before_delete_post', 'wpkama_delete_attaches_with_post' );
function wpkama_delete_attaches_with_post( $post_id ) {
	$post = get_post( $post_id );

	$post_types = [ 'article', 'question' ]; // delete attachments only for these post types

	if( ! $post || ! in_array( $post->post_type, $post_types ) ){
		return;
	}

	$attaches = get_children( [
		'post_type'   => 'attachment',
		'post_parent' => $post_id,
	] );

	if( ! $attaches ){
		return;
	}

	foreach( $attaches as $attach ){
		wp_delete_attachment( $attach->ID, true );
	}
}

The hook before_delete_post, because when the post is deleted, all attachments take the status unattached, i.e. the post_parent value is deleted, and the post attachments are selected by it. So the hooks delete_post and after_delete_post will not work.

#3 Deleting a media file with verification

Let's delete the attachment and check if the specified media file was really deleted:

if( false === wp_delete_attachment( 54, true ) ){
	 echo "Failed to delete media file";
} else {
	 echo "The media file has been deleted";
}

Notes

Global. wpdb. $wpdb WordPress database abstraction object.

Changelog

Since 2.0.0

Introduced.

`wp_delete_attachment() wp delete attachment` code ^{WP 6.6.2}

wp-includes/post.php

function wp_delete_attachment( $post_id, $force_delete = false ) {
	global $wpdb;

	$post = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->posts WHERE ID = %d", $post_id ) );

	if ( ! $post ) {
		return $post;
	}

	$post = get_post( $post );

	if ( 'attachment' !== $post->post_type ) {
		return false;
	}

	if ( ! $force_delete && EMPTY_TRASH_DAYS && MEDIA_TRASH && 'trash' !== $post->post_status ) {
		return wp_trash_post( $post_id );
	}

	/**
	 * Filters whether an attachment deletion should take place.
	 *
	 * @since 5.5.0
	 *
	 * @param WP_Post|false|null $delete       Whether to go forward with deletion.
	 * @param WP_Post            $post         Post object.
	 * @param bool               $force_delete Whether to bypass the Trash.
	 */
	$check = apply_filters( 'pre_delete_attachment', null, $post, $force_delete );
	if ( null !== $check ) {
		return $check;
	}

	delete_post_meta( $post_id, '_wp_trash_meta_status' );
	delete_post_meta( $post_id, '_wp_trash_meta_time' );

	$meta         = wp_get_attachment_metadata( $post_id );
	$backup_sizes = get_post_meta( $post->ID, '_wp_attachment_backup_sizes', true );
	$file         = get_attached_file( $post_id );

	if ( is_multisite() && is_string( $file ) && ! empty( $file ) ) {
		clean_dirsize_cache( $file );
	}

	/**
	 * Fires before an attachment is deleted, at the start of wp_delete_attachment().
	 *
	 * @since 2.0.0
	 * @since 5.5.0 Added the `$post` parameter.
	 *
	 * @param int     $post_id Attachment ID.
	 * @param WP_Post $post    Post object.
	 */
	do_action( 'delete_attachment', $post_id, $post );

	wp_delete_object_term_relationships( $post_id, array( 'category', 'post_tag' ) );
	wp_delete_object_term_relationships( $post_id, get_object_taxonomies( $post->post_type ) );

	// Delete all for any posts.
	delete_metadata( 'post', null, '_thumbnail_id', $post_id, true );

	wp_defer_comment_counting( true );

	$comment_ids = $wpdb->get_col( $wpdb->prepare( "SELECT comment_ID FROM $wpdb->comments WHERE comment_post_ID = %d ORDER BY comment_ID DESC", $post_id ) );
	foreach ( $comment_ids as $comment_id ) {
		wp_delete_comment( $comment_id, true );
	}

	wp_defer_comment_counting( false );

	$post_meta_ids = $wpdb->get_col( $wpdb->prepare( "SELECT meta_id FROM $wpdb->postmeta WHERE post_id = %d ", $post_id ) );
	foreach ( $post_meta_ids as $mid ) {
		delete_metadata_by_mid( 'post', $mid );
	}

	/** This action is documented in wp-includes/post.php */
	do_action( 'delete_post', $post_id, $post );
	$result = $wpdb->delete( $wpdb->posts, array( 'ID' => $post_id ) );
	if ( ! $result ) {
		return false;
	}
	/** This action is documented in wp-includes/post.php */
	do_action( 'deleted_post', $post_id, $post );

	wp_delete_attachment_files( $post_id, $meta, $backup_sizes, $file );

	clean_post_cache( $post );

	return $post;
}