get_boundary_post - Documentation

WordPress Version: 6.2

/**
 * Retrieves the boundary post.
 *
 * Boundary being either the first or last post by publish date within the constraints specified
 * by `$in_same_term` or `$excluded_terms`.
 *
 * @since 2.8.0
 *
 * @param bool         $in_same_term   Optional. Whether returned post should be in the same taxonomy term.
 *                                     Default false.
 * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs.
 *                                     Default empty.
 * @param bool         $start          Optional. Whether to retrieve first or last post.
 *                                     Default true.
 * @param string       $taxonomy       Optional. Taxonomy, if `$in_same_term` is true. Default 'category'.
 * @return array|null Array containing the boundary post object if successful, null otherwise.
 */
function get_boundary_post($in_same_term = false, $excluded_terms = '', $start = true, $taxonomy = 'category')
{
    $post = get_post();
    if (!$post || !is_single() || is_attachment() || !taxonomy_exists($taxonomy)) {
        return null;
    }
    $query_args = array('posts_per_page' => 1, 'order' => $start ? 'ASC' : 'DESC', 'update_post_term_cache' => false, 'update_post_meta_cache' => false);
    $term_array = array();
    if (!is_array($excluded_terms)) {
        if (!empty($excluded_terms)) {
            $excluded_terms = explode(',', $excluded_terms);
        } else {
            $excluded_terms = array();
        }
    }
    if ($in_same_term || !empty($excluded_terms)) {
        if ($in_same_term) {
            $term_array = wp_get_object_terms($post->ID, $taxonomy, array('fields' => 'ids'));
        }
        if (!empty($excluded_terms)) {
            $excluded_terms = array_map('intval', $excluded_terms);
            $excluded_terms = array_diff($excluded_terms, $term_array);
            $inverse_terms = array();
            foreach ($excluded_terms as $excluded_term) {
                $inverse_terms[] = $excluded_term * -1;
            }
            $excluded_terms = $inverse_terms;
        }
        $query_args['tax_query'] = array(array('taxonomy' => $taxonomy, 'terms' => array_merge($term_array, $excluded_terms)));
    }
    return get_posts($query_args);
}

WordPress Version: 5.7

/**
 * Retrieves the boundary post.
 *
 * Boundary being either the first or last post by publish date within the constraints specified
 * by $in_same_term or $excluded_terms.
 *
 * @since 2.8.0
 *
 * @param bool         $in_same_term   Optional. Whether returned post should be in a same taxonomy term.
 *                                     Default false.
 * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs.
 *                                     Default empty.
 * @param bool         $start          Optional. Whether to retrieve first or last post. Default true
 * @param string       $taxonomy       Optional. Taxonomy, if $in_same_term is true. Default 'category'.
 * @return null|array Array containing the boundary post object if successful, null otherwise.
 */
function get_boundary_post($in_same_term = false, $excluded_terms = '', $start = true, $taxonomy = 'category')
{
    $post = get_post();
    if (!$post || !is_single() || is_attachment() || !taxonomy_exists($taxonomy)) {
        return null;
    }
    $query_args = array('posts_per_page' => 1, 'order' => $start ? 'ASC' : 'DESC', 'update_post_term_cache' => false, 'update_post_meta_cache' => false);
    $term_array = array();
    if (!is_array($excluded_terms)) {
        if (!empty($excluded_terms)) {
            $excluded_terms = explode(',', $excluded_terms);
        } else {
            $excluded_terms = array();
        }
    }
    if ($in_same_term || !empty($excluded_terms)) {
        if ($in_same_term) {
            $term_array = wp_get_object_terms($post->ID, $taxonomy, array('fields' => 'ids'));
        }
        if (!empty($excluded_terms)) {
            $excluded_terms = array_map('intval', $excluded_terms);
            $excluded_terms = array_diff($excluded_terms, $term_array);
            $inverse_terms = array();
            foreach ($excluded_terms as $excluded_term) {
                $inverse_terms[] = $excluded_term * -1;
            }
            $excluded_terms = $inverse_terms;
        }
        $query_args['tax_query'] = array(array('taxonomy' => $taxonomy, 'terms' => array_merge($term_array, $excluded_terms)));
    }
    return get_posts($query_args);
}

WordPress Version: 4.6

/**
 * Retrieves the boundary post.
 *
 * Boundary being either the first or last post by publish date within the constraints specified
 * by $in_same_term or $excluded_terms.
 *
 * @since 2.8.0
 *
 * @param bool         $in_same_term   Optional. Whether returned post should be in a same taxonomy term.
 *                                     Default false.
 * @param array|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs.
 *                                     Default empty.
 * @param bool         $start          Optional. Whether to retrieve first or last post. Default true
 * @param string       $taxonomy       Optional. Taxonomy, if $in_same_term is true. Default 'category'.
 * @return null|array Array containing the boundary post object if successful, null otherwise.
 */
function get_boundary_post($in_same_term = false, $excluded_terms = '', $start = true, $taxonomy = 'category')
{
    $post = get_post();
    if (!$post || !is_single() || is_attachment() || !taxonomy_exists($taxonomy)) {
        return null;
    }
    $query_args = array('posts_per_page' => 1, 'order' => $start ? 'ASC' : 'DESC', 'update_post_term_cache' => false, 'update_post_meta_cache' => false);
    $term_array = array();
    if (!is_array($excluded_terms)) {
        if (!empty($excluded_terms)) {
            $excluded_terms = explode(',', $excluded_terms);
        } else {
            $excluded_terms = array();
        }
    }
    if ($in_same_term || !empty($excluded_terms)) {
        if ($in_same_term) {
            $term_array = wp_get_object_terms($post->ID, $taxonomy, array('fields' => 'ids'));
        }
        if (!empty($excluded_terms)) {
            $excluded_terms = array_map('intval', $excluded_terms);
            $excluded_terms = array_diff($excluded_terms, $term_array);
            $inverse_terms = array();
            foreach ($excluded_terms as $excluded_term) {
                $inverse_terms[] = $excluded_term * -1;
            }
            $excluded_terms = $inverse_terms;
        }
        $query_args['tax_query'] = array(array('taxonomy' => $taxonomy, 'terms' => array_merge($term_array, $excluded_terms)));
    }
    return get_posts($query_args);
}

WordPress Version: 4.3

/**
 * Retrieve boundary post.
 *
 * Boundary being either the first or last post by publish date within the constraints specified
 * by $in_same_term or $excluded_terms.
 *
 * @since 2.8.0
 *
 * @param bool         $in_same_term   Optional. Whether returned post should be in a same taxonomy term.
 * @param array|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs.
 * @param bool         $start          Optional. Whether to retrieve first or last post.
 * @param string       $taxonomy       Optional. Taxonomy, if $in_same_term is true. Default 'category'.
 * @return null|array Array containing the boundary post object if successful, null otherwise.
 */
function get_boundary_post($in_same_term = false, $excluded_terms = '', $start = true, $taxonomy = 'category')
{
    $post = get_post();
    if (!$post || !is_single() || is_attachment() || !taxonomy_exists($taxonomy)) {
        return null;
    }
    $query_args = array('posts_per_page' => 1, 'order' => $start ? 'ASC' : 'DESC', 'update_post_term_cache' => false, 'update_post_meta_cache' => false);
    $term_array = array();
    if (!is_array($excluded_terms)) {
        if (!empty($excluded_terms)) {
            $excluded_terms = explode(',', $excluded_terms);
        } else {
            $excluded_terms = array();
        }
    }
    if ($in_same_term || !empty($excluded_terms)) {
        if ($in_same_term) {
            $term_array = wp_get_object_terms($post->ID, $taxonomy, array('fields' => 'ids'));
        }
        if (!empty($excluded_terms)) {
            $excluded_terms = array_map('intval', $excluded_terms);
            $excluded_terms = array_diff($excluded_terms, $term_array);
            $inverse_terms = array();
            foreach ($excluded_terms as $excluded_term) {
                $inverse_terms[] = $excluded_term * -1;
            }
            $excluded_terms = $inverse_terms;
        }
        $query_args['tax_query'] = array(array('taxonomy' => $taxonomy, 'terms' => array_merge($term_array, $excluded_terms)));
    }
    return get_posts($query_args);
}

WordPress Version: 3.9

/**
 * Retrieve boundary post.
 *
 * Boundary being either the first or last post by publish date within the constraints specified
 * by $in_same_term or $excluded_terms.
 *
 * @since 2.8.0
 *
 * @param bool         $in_same_term   Optional. Whether returned post should be in a same taxonomy term.
 * @param array|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs.
 * @param bool         $start          Optional. Whether to retrieve first or last post.
 * @param string       $taxonomy       Optional. Taxonomy, if $in_same_term is true. Default 'category'.
 * @return mixed Array containing the boundary post object if successful, null otherwise.
 */
function get_boundary_post($in_same_term = false, $excluded_terms = '', $start = true, $taxonomy = 'category')
{
    $post = get_post();
    if (!$post || !is_single() || is_attachment() || !taxonomy_exists($taxonomy)) {
        return null;
    }
    $query_args = array('posts_per_page' => 1, 'order' => $start ? 'ASC' : 'DESC', 'update_post_term_cache' => false, 'update_post_meta_cache' => false);
    $term_array = array();
    if (!is_array($excluded_terms)) {
        if (!empty($excluded_terms)) {
            $excluded_terms = explode(',', $excluded_terms);
        } else {
            $excluded_terms = array();
        }
    }
    if ($in_same_term || !empty($excluded_terms)) {
        if ($in_same_term) {
            $term_array = wp_get_object_terms($post->ID, $taxonomy, array('fields' => 'ids'));
        }
        if (!empty($excluded_terms)) {
            $excluded_terms = array_map('intval', $excluded_terms);
            $excluded_terms = array_diff($excluded_terms, $term_array);
            $inverse_terms = array();
            foreach ($excluded_terms as $excluded_term) {
                $inverse_terms[] = $excluded_term * -1;
            }
            $excluded_terms = $inverse_terms;
        }
        $query_args['tax_query'] = array(array('taxonomy' => $taxonomy, 'terms' => array_merge($term_array, $excluded_terms)));
    }
    return get_posts($query_args);
}

WordPress Version: 3.8

/**
 * Retrieve boundary post.
 *
 * Boundary being either the first or last post by publish date within the constraints specified
 * by $in_same_term or $excluded_terms.
 *
 * @since 2.8.0
 *
 * @param bool         $in_same_term   Optional. Whether returned post should be in a same taxonomy term.
 * @param array|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs.
 * @param bool         $start          Optional. Whether to retrieve first or last post.
 * @param string       $taxonomy       Optional. Taxonomy, if $in_same_term is true. Default 'category'.
 * @return object
 */
function get_boundary_post($in_same_term = false, $excluded_terms = '', $start = true, $taxonomy = 'category')
{
    $post = get_post();
    if (!$post || !is_single() || is_attachment() || !taxonomy_exists($taxonomy)) {
        return null;
    }
    $query_args = array('posts_per_page' => 1, 'order' => $start ? 'ASC' : 'DESC', 'update_post_term_cache' => false, 'update_post_meta_cache' => false);
    $term_array = array();
    if (!is_array($excluded_terms)) {
        if (!empty($excluded_terms)) {
            $excluded_terms = explode(',', $excluded_terms);
        } else {
            $excluded_terms = array();
        }
    }
    if ($in_same_term || !empty($excluded_terms)) {
        if ($in_same_term) {
            $term_array = wp_get_object_terms($post->ID, $taxonomy, array('fields' => 'ids'));
        }
        if (!empty($excluded_terms)) {
            $excluded_terms = array_map('intval', $excluded_terms);
            $excluded_terms = array_diff($excluded_terms, $term_array);
            $inverse_terms = array();
            foreach ($excluded_terms as $excluded_term) {
                $inverse_terms[] = $excluded_term * -1;
            }
            $excluded_terms = $inverse_terms;
        }
        $query_args['tax_query'] = array(array('taxonomy' => $taxonomy, 'terms' => array_merge($term_array, $excluded_terms)));
    }
    return get_posts($query_args);
}

WordPress Version: 3.7

/**
 * Retrieve boundary post.
 *
 * Boundary being either the first or last post by publish date within the constraints specified
 * by $in_same_cat or $excluded_categories.
 *
 * @since 2.8.0
 *
 * @param bool $in_same_cat Optional. Whether returned post should be in a same category.
 * @param array|string $excluded_categories Optional. Array or comma-separated list of excluded category IDs.
 * @param bool $start Optional. Whether to retrieve first or last post.
 * @return object
 */
function get_boundary_post($in_same_cat = false, $excluded_categories = '', $start = true)
{
    $post = get_post();
    if (!$post || !is_single() || is_attachment()) {
        return null;
    }
    $cat_array = array();
    if (!is_array($excluded_categories)) {
        $excluded_categories = explode(',', $excluded_categories);
    }
    if ($in_same_cat || !empty($excluded_categories)) {
        if ($in_same_cat) {
            $cat_array = wp_get_object_terms($post->ID, 'category', array('fields' => 'ids'));
        }
        if (!empty($excluded_categories)) {
            $excluded_categories = array_map('intval', $excluded_categories);
            $excluded_categories = array_diff($excluded_categories, $cat_array);
            $inverse_cats = array();
            foreach ($excluded_categories as $excluded_category) {
                $inverse_cats[] = $excluded_category * -1;
            }
            $excluded_categories = $inverse_cats;
        }
    }
    $categories = implode(',', array_merge($cat_array, $excluded_categories));
    $order = $start ? 'ASC' : 'DESC';
    return get_posts(array('numberposts' => 1, 'category' => $categories, 'order' => $order, 'update_post_term_cache' => false, 'update_post_meta_cache' => false));
}