wp_delete_attachment( int $post_id, bool $force_delete = false ): WP_Post|false|null

Description

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$post_idint

Attachment ID.

$force_deletebooloptional

Whether to bypass Trash and force deletion.
Default false.Default: false

Return value

WP_Post|false|null

Post data on success, false or null on failure.

Performance profile

How much work a call to wp_delete_attachment() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reaches the database via ->get_row().

Scaling

Scales with input

The body loops, so the work grows with what you pass in.

Instructions

17–164

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 182.

Plugin surface

4 hooks

Third-party callbacks on 'pre_delete_attachment', 'delete_attachment', 'delete_post' run inside this call, and their cost is not bounded by anything here.

Called by

4

4 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• querycontent queryget_post()called directly
• hookthird-party callbacksapply_filters()called directly
• sqldatabase query->get_row()called directly
• transienttransientget_transient()one call below wp_delete_attachment()
• serializeserialisationmaybe_serialize()one call below wp_delete_attachment()
• cacheobject cachewp_cache_delete_multiple()one call below wp_delete_attachment()

Further down the call graph this can also reach option. That is the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 8 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost wp_delete_attachment() can have, taken from its control-flow graph on PHP 8.5.

Hooks and filters fired · 4

4 hooks fire while wp_delete_attachment() runs, in this order:

1. 1
   apply_filters( pre_delete_attachment )filterline 6716 (+28 into the body)

   Filters whether an attachment deletion should take place.

2. 2
   do_action( delete_attachment )actionline 6741 (+53 into the body)

   Fires before an attachment is deleted, at the start of wp_delete_attachment().

3. 3
   do_action( delete_post )actionline 6764 (+76 into the body)

   Fires immediately before a post is deleted from the database.

4. 4
   do_action( deleted_post )actionline 6770 (+82 into the body)

   Fires immediately after a post is deleted from the database.

Uses · 18

• get_post()Retrieves post data given a post ID or post object.
• wp_trash_post()Moves a post or page to the Trash
• apply_filters()Calls the callback functions that have been added to a filter hook.
• delete_post_meta()Deletes a post meta field for the given post ID.
• wp_get_attachment_metadata()Retrieves attachment metadata for attachment ID.
• get_post_meta()Retrieves a post meta field for the given post ID.
• get_attached_file()Retrieves attached file path based on attachment ID.
• is_multisite()Determines whether Multisite is enabled.
• clean_dirsize_cache()Cleans directory size cache used by recurse_dirsize().
• do_action()Calls the callback functions that have been added to an action hook.
• wp_delete_object_term_relationships()Unlinks the object from the taxonomy or taxonomies.
• get_object_taxonomies()Returns the names or objects of the taxonomies which are registered for the requested object or object type, such as a post object or post type name.

Used by · 4

• File_Upload_Upgrader::cleanup()Deletes the attachment/uploaded file.
• wp_ajax_media_create_image_subsizes()Handles creating missing image sub-sizes for just uploaded images via AJAX.
• wp_delete_post()Trashes or deletes a post or page.
• wp_import_cleanup()Cleanup importer.

Source code

View on Trac ↗View on GitHub ↗

6688function wp_delete_attachment( $post_id, $force_delete = false ) {6689	global $wpdb;6690 6691	$post = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->posts WHERE ID = %d", $post_id ) );6692 6693	if ( ! $post ) {6694		return $post;6695	}6696 6697	$post = get_post( $post );6698 6699	if ( 'attachment' !== $post->post_type ) {6700		return false;6701	}6702 6703	if ( ! $force_delete && EMPTY_TRASH_DAYS && MEDIA_TRASH && 'trash' !== $post->post_status ) {6704		return wp_trash_post( $post_id );6705	}6706 6707	/**6708	 * Filters whether an attachment deletion should take place.6709	 *6710	 * @since 5.5.06711	 *6712	 * @param WP_Post|false|null $delete       Whether to go forward with deletion.6713	 * @param WP_Post            $post         Post object.6714	 * @param bool               $force_delete Whether to bypass the Trash.6715	 */6716	$check = apply_filters( 'pre_delete_attachment', null, $post, $force_delete );6717	if ( null !== $check ) {6718		return $check;6719	}6720 6721	delete_post_meta( $post_id, '_wp_trash_meta_status' );6722	delete_post_meta( $post_id, '_wp_trash_meta_time' );6723 6724	$meta         = wp_get_attachment_metadata( $post_id );6725	$backup_sizes = get_post_meta( $post->ID, '_wp_attachment_backup_sizes', true );6726	$file         = get_attached_file( $post_id );6727 6728	if ( is_multisite() && is_string( $file ) && ! empty( $file ) ) {6729		clean_dirsize_cache( $file );6730	}6731 6732	/**6733	 * Fires before an attachment is deleted, at the start of wp_delete_attachment().6734	 *6735	 * @since 2.0.06736	 * @since 5.5.0 Added the `$post` parameter.6737	 *6738	 * @param int     $post_id Attachment ID.6739	 * @param WP_Post $post    Post object.6740	 */6741	do_action( 'delete_attachment', $post_id, $post );6742 6743	wp_delete_object_term_relationships( $post_id, array( 'category', 'post_tag' ) );6744	wp_delete_object_term_relationships( $post_id, get_object_taxonomies( $post->post_type ) );6745 6746	// Delete all for any posts.6747	delete_metadata( 'post', null, '_thumbnail_id', $post_id, true );6748 6749	wp_defer_comment_counting( true );6750 6751	$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 ) );6752	foreach ( $comment_ids as $comment_id ) {6753		wp_delete_comment( $comment_id, true );6754	}6755 6756	wp_defer_comment_counting( false );6757 6758	$post_meta_ids = $wpdb->get_col( $wpdb->prepare( "SELECT meta_id FROM $wpdb->postmeta WHERE post_id = %d ", $post_id ) );6759	foreach ( $post_meta_ids as $mid ) {6760		delete_metadata_by_mid( 'post', $mid );6761	}6762 6763	/** This action is documented in wp-includes/post.php */6764	do_action( 'delete_post', $post_id, $post );6765	$result = $wpdb->delete( $wpdb->posts, array( 'ID' => $post_id ) );6766	if ( ! $result ) {6767		return false;

Changelog

Introduced in 2.0.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 6.9.7 tag, from src/wp-includes/post.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.