wp_trash_post - Documentation

WordPress Version: 6.3

/**
 * Moves a post or page to the Trash
 *
 * If Trash is disabled, the post or page is permanently deleted.
 *
 * @since 2.9.0
 *
 * @see wp_delete_post()
 *
 * @param int $post_id Optional. Post ID. Default is the ID of the global `$post`
 *                     if `EMPTY_TRASH_DAYS` equals true.
 * @return WP_Post|false|null Post data on success, false or null on failure.
 */
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;
}

WordPress Version: 6.1

/**
 * Moves a post or page to the Trash
 *
 * If Trash is disabled, the post or page is permanently deleted.
 *
 * @since 2.9.0
 *
 * @see wp_delete_post()
 *
 * @param int $post_id Optional. Post ID. Default is the ID of the global `$post`
 *                     if `EMPTY_TRASH_DAYS` equals true.
 * @return WP_Post|false|null Post data on success, false or null on failure.
 */
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;
    }
    /**
     * Filters whether a post trashing should take place.
     *
     * @since 4.9.0
     *
     * @param bool|null $trash Whether to go forward with trashing.
     * @param WP_Post   $post  Post object.
     */
    $check = apply_filters('pre_trash_post', null, $post);
    if (null !== $check) {
        return $check;
    }
    /**
     * Fires before a post is sent to the Trash.
     *
     * @since 3.3.0
     *
     * @param int $post_id Post ID.
     */
    do_action('wp_trash_post', $post_id);
    add_post_meta($post_id, '_wp_trash_meta_status', $post->post_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
     *
     * @param int $post_id Post ID.
     */
    do_action('trashed_post', $post_id);
    return $post;
}

WordPress Version: 5.9

/**
 * Move a post or page to the Trash
 *
 * If Trash is disabled, the post or page is permanently deleted.
 *
 * @since 2.9.0
 *
 * @see wp_delete_post()
 *
 * @param int $post_id Optional. Post ID. Default is the ID of the global `$post`
 *                     if `EMPTY_TRASH_DAYS` equals true.
 * @return WP_Post|false|null Post data on success, false or null on failure.
 */
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;
    }
    /**
     * Filters whether a post trashing should take place.
     *
     * @since 4.9.0
     *
     * @param bool|null $trash Whether to go forward with trashing.
     * @param WP_Post   $post  Post object.
     */
    $check = apply_filters('pre_trash_post', null, $post);
    if (null !== $check) {
        return $check;
    }
    /**
     * Fires before a post is sent to the Trash.
     *
     * @since 3.3.0
     *
     * @param int $post_id Post ID.
     */
    do_action('wp_trash_post', $post_id);
    add_post_meta($post_id, '_wp_trash_meta_status', $post->post_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
     *
     * @param int $post_id Post ID.
     */
    do_action('trashed_post', $post_id);
    return $post;
}

WordPress Version: 5.4

/**
 * Move a post or page to the Trash
 *
 * If Trash is disabled, the post or page is permanently deleted.
 *
 * @since 2.9.0
 *
 * @see wp_delete_post()
 *
 * @param int $post_id Optional. Post ID. Default is ID of the global $post
 *                     if EMPTY_TRASH_DAYS equals true.
 * @return WP_Post|false|null Post data on success, false or null on failure.
 */
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;
    }
    /**
     * Filters whether a post trashing should take place.
     *
     * @since 4.9.0
     *
     * @param bool|null $trash Whether to go forward with trashing.
     * @param WP_Post   $post  Post object.
     */
    $check = apply_filters('pre_trash_post', null, $post);
    if (null !== $check) {
        return $check;
    }
    /**
     * Fires before a post is sent to the Trash.
     *
     * @since 3.3.0
     *
     * @param int $post_id Post ID.
     */
    do_action('wp_trash_post', $post_id);
    add_post_meta($post_id, '_wp_trash_meta_status', $post->post_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
     *
     * @param int $post_id Post ID.
     */
    do_action('trashed_post', $post_id);
    return $post;
}

WordPress Version: 5.3

/**
 * Move a post or page to the Trash
 *
 * If trash is disabled, the post or page is permanently deleted.
 *
 * @since 2.9.0
 *
 * @see wp_delete_post()
 *
 * @param int $post_id Optional. Post ID. Default is ID of the global $post
 *                     if EMPTY_TRASH_DAYS equals true.
 * @return WP_Post|false|null Post data on success, false or null on failure.
 */
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;
    }
    /**
     * Filters whether a post trashing should take place.
     *
     * @since 4.9.0
     *
     * @param bool|null $trash Whether to go forward with trashing.
     * @param WP_Post   $post  Post object.
     */
    $check = apply_filters('pre_trash_post', null, $post);
    if (null !== $check) {
        return $check;
    }
    /**
     * Fires before a post is sent to the trash.
     *
     * @since 3.3.0
     *
     * @param int $post_id Post ID.
     */
    do_action('wp_trash_post', $post_id);
    add_post_meta($post_id, '_wp_trash_meta_status', $post->post_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
     *
     * @param int $post_id Post ID.
     */
    do_action('trashed_post', $post_id);
    return $post;
}

WordPress Version: 4.9

/**
 * Move a post or page to the Trash
 *
 * If trash is disabled, the post or page is permanently deleted.
 *
 * @since 2.9.0
 *
 * @see wp_delete_post()
 *
 * @param int $post_id Optional. Post ID. Default is ID of the global $post
 *                     if EMPTY_TRASH_DAYS equals true.
 * @return WP_Post|false|null Post data on success, false or null on failure.
 */
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;
    }
    /**
     * Filters whether a post trashing should take place.
     *
     * @since 4.9.0
     *
     * @param bool    $trash Whether to go forward with trashing.
     * @param WP_Post $post  Post object.
     */
    $check = apply_filters('pre_trash_post', null, $post);
    if (null !== $check) {
        return $check;
    }
    /**
     * Fires before a post is sent to the trash.
     *
     * @since 3.3.0
     *
     * @param int $post_id Post ID.
     */
    do_action('wp_trash_post', $post_id);
    add_post_meta($post_id, '_wp_trash_meta_status', $post->post_status);
    add_post_meta($post_id, '_wp_trash_meta_time', time());
    wp_update_post(array('ID' => $post_id, 'post_status' => 'trash'));
    wp_trash_post_comments($post_id);
    /**
     * Fires after a post is sent to the trash.
     *
     * @since 2.9.0
     *
     * @param int $post_id Post ID.
     */
    do_action('trashed_post', $post_id);
    return $post;
}

WordPress Version: 4.4

/**
 * Move a post or page to the Trash
 *
 * If trash is disabled, the post or page is permanently deleted.
 *
 * @since 2.9.0
 *
 * @see wp_delete_post()
 *
 * @param int $post_id Optional. Post ID. Default is ID of the global $post
 *                     if EMPTY_TRASH_DAYS equals true.
 * @return false|array|WP_Post|null Post data array, otherwise false.
 */
function wp_trash_post($post_id = 0)
{
    if (!EMPTY_TRASH_DAYS) {
        return wp_delete_post($post_id, true);
    }
    if (!$post = get_post($post_id, ARRAY_A)) {
        return $post;
    }
    if ($post['post_status'] == 'trash') {
        return false;
    }
    /**
     * Fires before a post is sent to the trash.
     *
     * @since 3.3.0
     *
     * @param int $post_id Post ID.
     */
    do_action('wp_trash_post', $post_id);
    add_post_meta($post_id, '_wp_trash_meta_status', $post['post_status']);
    add_post_meta($post_id, '_wp_trash_meta_time', time());
    $post['post_status'] = 'trash';
    wp_insert_post(wp_slash($post));
    wp_trash_post_comments($post_id);
    /**
     * Fires after a post is sent to the trash.
     *
     * @since 2.9.0
     *
     * @param int $post_id Post ID.
     */
    do_action('trashed_post', $post_id);
    return $post;
}

WordPress Version: 4.3

/**
 * Move a post or page to the Trash
 *
 * If trash is disabled, the post or page is permanently deleted.
 *
 * @since 2.9.0
 *
 * @see wp_delete_post()
 *
 * @param int $post_id Optional. Post ID. Default is ID of the global $post
 *                     if EMPTY_TRASH_DAYS equals true.
 * @return false|array|WP_Post|null Post data array, otherwise false.
 */
function wp_trash_post($post_id = 0)
{
    if (!EMPTY_TRASH_DAYS) {
        return wp_delete_post($post_id, true);
    }
    if (!$post = get_post($post_id, ARRAY_A)) {
        return $post;
    }
    if ($post['post_status'] == 'trash') {
        return false;
    }
    /**
     * Fires before a post is sent to the trash.
     *
     * @since 3.3.0
     *
     * @param int $post_id Post ID.
     */
    do_action('wp_trash_post', $post_id);
    add_post_meta($post_id, '_wp_trash_meta_status', $post['post_status']);
    add_post_meta($post_id, '_wp_trash_meta_time', time());
    $post['post_status'] = 'trash';
    wp_insert_post($post);
    wp_trash_post_comments($post_id);
    /**
     * Fires after a post is sent to the trash.
     *
     * @since 2.9.0
     *
     * @param int $post_id Post ID.
     */
    do_action('trashed_post', $post_id);
    return $post;
}

WordPress Version: 4.0

/**
 * Move a post or page to the Trash
 *
 * If trash is disabled, the post or page is permanently deleted.
 *
 * @since 2.9.0
 *
 * @see wp_delete_post()
 *
 * @param int $post_id Optional. Post ID. Default is ID of the global $post
 *                     if EMPTY_TRASH_DAYS equals true.
 * @return bool|array Post data array, otherwise false.
 */
function wp_trash_post($post_id = 0)
{
    if (!EMPTY_TRASH_DAYS) {
        return wp_delete_post($post_id, true);
    }
    if (!$post = get_post($post_id, ARRAY_A)) {
        return $post;
    }
    if ($post['post_status'] == 'trash') {
        return false;
    }
    /**
     * Fires before a post is sent to the trash.
     *
     * @since 3.3.0
     *
     * @param int $post_id Post ID.
     */
    do_action('wp_trash_post', $post_id);
    add_post_meta($post_id, '_wp_trash_meta_status', $post['post_status']);
    add_post_meta($post_id, '_wp_trash_meta_time', time());
    $post['post_status'] = 'trash';
    wp_insert_post($post);
    wp_trash_post_comments($post_id);
    /**
     * Fires after a post is sent to the trash.
     *
     * @since 2.9.0
     *
     * @param int $post_id Post ID.
     */
    do_action('trashed_post', $post_id);
    return $post;
}

WordPress Version: 3.9

/**
 * Moves a post or page to the Trash
 *
 * If trash is disabled, the post or page is permanently deleted.
 *
 * @since 2.9.0
 *
 * @uses wp_delete_post() if trash is disabled
 *
 * @param int $post_id Post ID.
 * @return mixed False on failure
 */
function wp_trash_post($post_id = 0)
{
    if (!EMPTY_TRASH_DAYS) {
        return wp_delete_post($post_id, true);
    }
    if (!$post = get_post($post_id, ARRAY_A)) {
        return $post;
    }
    if ($post['post_status'] == 'trash') {
        return false;
    }
    /**
     * Fires before a post is sent to the trash.
     *
     * @since 3.3.0
     *
     * @param int $post_id Post ID.
     */
    do_action('wp_trash_post', $post_id);
    add_post_meta($post_id, '_wp_trash_meta_status', $post['post_status']);
    add_post_meta($post_id, '_wp_trash_meta_time', time());
    $post['post_status'] = 'trash';
    wp_insert_post($post);
    wp_trash_post_comments($post_id);
    /**
     * Fires after a post is sent to the trash.
     *
     * @since 2.9.0
     *
     * @param int $post_id Post ID.
     */
    do_action('trashed_post', $post_id);
    return $post;
}

WordPress Version: 3.7

/**
 * Moves a post or page to the Trash
 *
 * If trash is disabled, the post or page is permanently deleted.
 *
 * @since 2.9.0
 * @uses do_action() on 'trash_post' before trashing
 * @uses do_action() on 'trashed_post' after trashing
 * @uses wp_delete_post() if trash is disabled
 *
 * @param int $post_id Post ID.
 * @return mixed False on failure
 */
function wp_trash_post($post_id = 0)
{
    if (!EMPTY_TRASH_DAYS) {
        return wp_delete_post($post_id, true);
    }
    if (!$post = get_post($post_id, ARRAY_A)) {
        return $post;
    }
    if ($post['post_status'] == 'trash') {
        return false;
    }
    do_action('wp_trash_post', $post_id);
    add_post_meta($post_id, '_wp_trash_meta_status', $post['post_status']);
    add_post_meta($post_id, '_wp_trash_meta_time', time());
    $post['post_status'] = 'trash';
    wp_insert_post($post);
    wp_trash_post_comments($post_id);
    do_action('trashed_post', $post_id);
    return $post;
}