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 6842 (+28 into the body)

   Filters whether an attachment deletion should take place.

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

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

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

   Fires immediately before a post is deleted from the database.

4. 4
   do_action( deleted_post )actionline 6896 (+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 ↗

6814function wp_delete_attachment( $post_id, $force_delete = false ) {6815	global $wpdb;6816 6817	$post = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->posts WHERE ID = %d", $post_id ) );6818 6819	if ( ! $post ) {6820		return $post;6821	}6822 6823	$post = get_post( $post );6824 6825	if ( 'attachment' !== $post->post_type ) {6826		return false;6827	}6828 6829	if ( ! $force_delete && EMPTY_TRASH_DAYS && MEDIA_TRASH && 'trash' !== $post->post_status ) {6830		return wp_trash_post( $post_id );6831	}6832 6833	/**6834	 * Filters whether an attachment deletion should take place.6835	 *6836	 * @since 5.5.06837	 *6838	 * @param WP_Post|false|null $delete       Whether to go forward with deletion.6839	 * @param WP_Post            $post         Post object.6840	 * @param bool               $force_delete Whether to bypass the Trash.6841	 */6842	$check = apply_filters( 'pre_delete_attachment', null, $post, $force_delete );6843	if ( null !== $check ) {6844		return $check;6845	}6846 6847	delete_post_meta( $post_id, '_wp_trash_meta_status' );6848	delete_post_meta( $post_id, '_wp_trash_meta_time' );6849 6850	$meta         = wp_get_attachment_metadata( $post_id );6851	$backup_sizes = get_post_meta( $post->ID, '_wp_attachment_backup_sizes', true );6852	$file         = get_attached_file( $post_id );6853 6854	if ( is_multisite() && is_string( $file ) && ! empty( $file ) ) {6855		clean_dirsize_cache( $file );6856	}6857 6858	/**6859	 * Fires before an attachment is deleted, at the start of wp_delete_attachment().6860	 *6861	 * @since 2.0.06862	 * @since 5.5.0 Added the `$post` parameter.6863	 *6864	 * @param int     $post_id Attachment ID.6865	 * @param WP_Post $post    Post object.6866	 */6867	do_action( 'delete_attachment', $post_id, $post );6868 6869	wp_delete_object_term_relationships( $post_id, array( 'category', 'post_tag' ) );6870	wp_delete_object_term_relationships( $post_id, get_object_taxonomies( $post->post_type ) );6871 6872	// Delete all for any posts.6873	delete_metadata( 'post', null, '_thumbnail_id', $post_id, true );6874 6875	wp_defer_comment_counting( true );6876 6877	$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 ) );6878	foreach ( $comment_ids as $comment_id ) {6879		wp_delete_comment( $comment_id, true );6880	}6881 6882	wp_defer_comment_counting( false );6883 6884	$post_meta_ids = $wpdb->get_col( $wpdb->prepare( "SELECT meta_id FROM $wpdb->postmeta WHERE post_id = %d ", $post_id ) );6885	foreach ( $post_meta_ids as $mid ) {6886		delete_metadata_by_mid( 'post', $mid );6887	}6888 6889	/** This action is documented in wp-includes/post.php */6890	do_action( 'delete_post', $post_id, $post );6891	$result = $wpdb->delete( $wpdb->posts, array( 'ID' => $post_id ) );6892	if ( ! $result ) {6893		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 7.1.0 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.