wp_trash_post() │ WP 2.9.0

Moves the specified post to the trash. If the trash is disabled, the post will be permanently deleted.

When moving a post to the trash, its status is set to trash. The previous status is saved in the meta-field _wp_trash_meta_status and the time of moving to the trash is recorded in the meta-field _wp_trash_meta_time. Also, all comments of the post receive the status post-trashed (in the comment_approve field), and the previous statuses of the post's comments are recorded in the post meta-field _wp_trash_meta_comments_status. All this is needed for restoring the post from the trash.

If, when calling this function, the constant EMPTY_TRASH_DAYS=false, control is fully passed to the function wp_delete_post().

It is always better to use this function instead of wp_delete_post(). However, wp_delete_post() passes control to wp_trash_post() if the trash is enabled and the post type is either post or page. For custom types, wp_delete_post() always deletes the post.

Trash Settings in WordPress

By default, the trash is enabled in WordPress and posts are stored in it for 30 days, after which they are permanently deleted. It can be disabled by setting (defining) the constant EMPTY_TRASH_DAYS=false. The constant should be defined in the configuration file wp-config.php:

define( 'EMPTY_TRASH_DAYS', false ); // trash is disabled
define( 'EMPTY_TRASH_DAYS', true );  // trash is enabled. By default in WP
define( 'EMPTY_TRASH_DAYS', 30 );    // trash is enabled and posts will be stored in it for 30 days, after which they will be deleted.

To disable the trash for specific post types, see the article: How to Disable Trash in WordPress

Use wp_untrash_post() when you need to programmatically restore a post from the trash.

Use wp_trash_comment() when you need to move a comment to the trash.

Hooks from the function

Returns

WP_Post|false|null. An array of post data or false.

Usage

wp_trash_post( $post_id );
$post_id(integer) (required)
ID of the post. By default, the value of the global variable $post is passed.

Examples

0

#1 Move the post to the trash

If the trash is enabled, we will move the post with ID=15 to the trash. The post will remain in the trash for 30 days, during this time we can restore it. After 30 days, the post will be deleted completely by WordPress.

$post_id = 15;
wp_trash_post( $post_id );

If trash feature is not enabled, then wp_delete_post() function will be called.

Notes

Changelog

Since 2.9.0 Introduced.

wp_trash_post() code WP 6.9.1

wp-includes/post.php 
function wp_trash_post( $post_id = 0 ) {
	if ( ! EMPTY_TRASH_DAYS ) {
		return wp_delete_post( $post_id, true );
	}

	$post = get_post( $post_id );

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

	if ( 'trash' === $post->post_status ) {
		return false;
	}

	$previous_status = $post->post_status;

	/**
	 * Filters whether a post trashing should take place.
	 *
	 * @since 4.9.0
	 * @since 6.3.0 Added the `$previous_status` parameter.
	 *
	 * @param bool|null $trash           Whether to go forward with trashing.
	 * @param WP_Post   $post            Post object.
	 * @param string    $previous_status The status of the post about to be trashed.
	 */
	$check = apply_filters( 'pre_trash_post', null, $post, $previous_status );

	if ( null !== $check ) {
		return $check;
	}

	/**
	 * Fires before a post is sent to the Trash.
	 *
	 * @since 3.3.0
	 * @since 6.3.0 Added the `$previous_status` parameter.
	 *
	 * @param int    $post_id         Post ID.
	 * @param string $previous_status The status of the post about to be trashed.
	 */
	do_action( 'wp_trash_post', $post_id, $previous_status );

	add_post_meta( $post_id, '_wp_trash_meta_status', $previous_status );
	add_post_meta( $post_id, '_wp_trash_meta_time', time() );

	$post_updated = wp_update_post(
		array(
			'ID'          => $post_id,
			'post_status' => 'trash',
		)
	);

	if ( ! $post_updated ) {
		return false;
	}

	wp_trash_post_comments( $post_id );

	/**
	 * Fires after a post is sent to the Trash.
	 *
	 * @since 2.9.0
	 * @since 6.3.0 Added the `$previous_status` parameter.
	 *
	 * @param int    $post_id         Post ID.
	 * @param string $previous_status The status of the post at the point where it was trashed.
	 */
	do_action( 'trashed_post', $post_id, $previous_status );

	return $post;
}

Insert, delete, update