root/trunk/wp-includes/deprecated.php

<?php
/**
 * Deprecated functions from past WordPress versions. You shouldn't use these
 * globals and functions and look for the alternatives instead. The functions
 * and globals will be removed in a later version.
 *
 * @package WordPress
 * @subpackage Deprecated
 */

/*
 * Deprecated global variables.
 */

/**
 * The name of the Posts table
 * @global string $tableposts
 * @deprecated Use $wpdb->posts
 */
$tableposts = $wpdb->posts;

/**
 * The name of the Users table
 * @global string $tableusers
 * @deprecated Use $wpdb->users
 */
$tableusers = $wpdb->users;

/**
 * The name of the Categories table
 * @global string $tablecategories
 * @deprecated Use $wpdb->categories
 */
$tablecategories = $wpdb->categories;

/**
 * The name of the post to category table
 * @global string $tablepost2cat
 * @deprecated Use $wpdb->post2cat;
 */
$tablepost2cat = $wpdb->post2cat;

/**
 * The name of the comments table
 * @global string $tablecomments
 * @deprecated Use $wpdb->comments;
 */
$tablecomments = $wpdb->comments;

/**
 * The name of the links table
 * @global string $tablelinks
 * @deprecated Use $wpdb->links;
 */
$tablelinks = $wpdb->links;

/**
 * @global string $tablelinkcategories
 * @deprecated Not used anymore;
 */
$tablelinkcategories = 'linkcategories_is_gone';

/**
 * The name of the options table
 * @global string $tableoptions
 * @deprecated Use $wpdb->options;
 */
$tableoptions = $wpdb->options;

/**
 * The name of the postmeta table
 * @global string $tablepostmeta
 * @deprecated Use $wpdb->postmeta;
 */
$tablepostmeta = $wpdb->postmeta;

/*
 * Deprecated functions come here to die.
 */

/**
 * Entire Post data.
 *
 * @since 0.71
 * @deprecated Use get_post()
 * @see get_post()
 *
 * @param int $postid
 * @return array
 */
function get_postdata($postid) {
    _deprecated_function(__FUNCTION__, '0.0', 'get_post()');

    $post = &get_post($postid);

    $postdata = array (
        'ID' => $post->ID,
        'Author_ID' => $post->post_author,
        'Date' => $post->post_date,
        'Content' => $post->post_content,
        'Excerpt' => $post->post_excerpt,
        'Title' => $post->post_title,
        'Category' => $post->post_category,
        'post_status' => $post->post_status,
        'comment_status' => $post->comment_status,
        'ping_status' => $post->ping_status,
        'post_password' => $post->post_password,
        'to_ping' => $post->to_ping,
        'pinged' => $post->pinged,
        'post_type' => $post->post_type,
        'post_name' => $post->post_name
    );

    return $postdata;
}

/**
 * Sets up the WordPress Loop.
 *
 * @since 1.0.1
 * @deprecated Since 1.5 - {@link http://codex.wordpress.org/The_Loop Use new WordPress Loop}
 */
function start_wp() {
    global $wp_query, $post;

    _deprecated_function(__FUNCTION__, '1.5', __('new WordPress Loop') );

    // Since the old style loop is being used, advance the query iterator here.
    $wp_query->next_post();

    setup_postdata($post);
}

/**
 * Return or Print Category ID.
 *
 * @since 0.71
 * @deprecated use get_the_category()
 * @see get_the_category()
 *
 * @param bool $echo
 * @return null|int
 */
function the_category_ID($echo = true) {
    _deprecated_function(__FUNCTION__, '0.0', 'get_the_category()');

    // Grab the first cat in the list.
    $categories = get_the_category();
    $cat = $categories[0]->term_id;

    if ( $echo )
        echo $cat;

    return $cat;
}

/**
 * Print category with optional text before and after.
 *
 * @since 0.71
 * @deprecated use get_the_category_by_ID()
 * @see get_the_category_by_ID()
 *
 * @param string $before
 * @param string $after
 */
function the_category_head($before='', $after='') {
    global $currentcat, $previouscat;

    _deprecated_function(__FUNCTION__, '0.0', 'get_the_category_by_ID()');

    // Grab the first cat in the list.
    $categories = get_the_category();
    $currentcat = $categories[0]->category_id;
    if ( $currentcat != $previouscat ) {
        echo $before;
        echo get_the_category_by_ID($currentcat);
        echo $after;
        $previouscat = $currentcat;
    }
}

/**
 * Prints link to the previous post.
 *
 * @since 1.5
 * @deprecated Use previous_post_link()
 * @see previous_post_link()
 *
 * @param string $format
 * @param string $previous
 * @param string $title
 * @param string $in_same_cat
 * @param int $limitprev
 * @param string $excluded_categories
 */
function previous_post($format='%', $previous='previous post: ', $title='yes', $in_same_cat='no', $limitprev=1, $excluded_categories='') {

    _deprecated_function(__FUNCTION__, '0.0', 'previous_post_link()');

    if ( empty($in_same_cat) || 'no' == $in_same_cat )
        $in_same_cat = false;
    else
        $in_same_cat = true;

    $post = get_previous_post($in_same_cat, $excluded_categories);

    if ( !$post )
        return;

    $string = '<a href="'.get_permalink($post->ID).'">'.$previous;
    if ( 'yes' == $title )
        $string .= apply_filters('the_title', $post->post_title, $post);
    $string .= '</a>';
    $format = str_replace('%', $string, $format);
    echo $format;
}

/**
 * Prints link to the next post.
 *
 * @since 0.71
 * @deprecated Use next_post_link()
 * @see next_post_link()
 *
 * @param string $format
 * @param string $previous
 * @param string $title
 * @param string $in_same_cat
 * @param int $limitprev
 * @param string $excluded_categories
 */
function next_post($format='%', $next='next post: ', $title='yes', $in_same_cat='no', $limitnext=1, $excluded_categories='') {
    _deprecated_function(__FUNCTION__, '0.0', 'next_post_link()');

    if ( empty($in_same_cat) || 'no' == $in_same_cat )
        $in_same_cat = false;
    else
        $in_same_cat = true;

    $post = get_next_post($in_same_cat, $excluded_categories);

    if ( !$post    )
        return;

    $string = '<a href="'.get_permalink($post->ID).'">'.$next;
    if ( 'yes' == $title )
        $string .= apply_filters('the_title', $post->post_title, $nextpost);
    $string .= '</a>';
    $format = str_replace('%', $string, $format);
    echo $format;
}

/**
 * Whether user can create a post.
 *
 * @since 1.5
 * @deprecated Use current_user_can()
 * @see current_user_can()
 *
 * @param int $user_id
 * @param int $blog_id Not Used
 * @param int $category_id Not Used
 * @return bool
 */
function user_can_create_post($user_id, $blog_id = 1, $category_id = 'None') {
    _deprecated_function(__FUNCTION__, '0.0', 'current_user_can()');

    $author_data = get_userdata($user_id);
    return ($author_data->user_level > 1);
}

/**
 * Whether user can create a post.
 *
 * @since 1.5
 * @deprecated Use current_user_can()
 * @see current_user_can()
 *
 * @param int $user_id
 * @param int $blog_id Not Used
 * @param int $category_id Not Used
 * @return bool
 */
function user_can_create_draft($user_id, $blog_id = 1, $category_id = 'None') {
    _deprecated_function(__FUNCTION__, '0.0', 'current_user_can()');

    $author_data = get_userdata($user_id);
    return ($author_data->user_level >= 1);
}

/**
 * Whether user can edit a post.
 *
 * @since 1.5
 * @deprecated Use current_user_can()
 * @see current_user_can()
 *
 * @param int $user_id
 * @param int $post_id
 * @param int $blog_id Not Used
 * @return bool
 */
function user_can_edit_post($user_id, $post_id, $blog_id = 1) {
    _deprecated_function(__FUNCTION__, '0', 'current_user_can()');

    $author_data = get_userdata($user_id);
    $post = get_post($post_id);
    $post_author_data = get_userdata($post->post_author);

    if ( (($user_id == $post_author_data->ID) && !($post->post_status == 'publish' &&  $author_data->user_level < 2))
             || ($author_data->user_level > $post_author_data->user_level)
             || ($author_data->user_level >= 10) ) {
        return true;
    } else {
        return false;
    }
}

/**
 * Whether user can delete a post.
 *
 * @since 1.5
 * @deprecated Use current_user_can()
 * @see current_user_can()
 *
 * @param int $user_id
 * @param int $post_id
 * @param int $blog_id Not Used
 * @return bool
 */
function user_can_delete_post($user_id, $post_id, $blog_id = 1) {
    _deprecated_function(__FUNCTION__, '0.0', 'current_user_can()');

    // right now if one can edit, one can delete
    return user_can_edit_post($user_id, $post_id, $blog_id);
}

/**
 * Whether user can set new posts' dates.
 *
 * @since 1.5
 * @deprecated Use current_user_can()
 * @see current_user_can()
 *
 * @param int $user_id
 * @param int $blog_id Not Used
 * @param int $category_id Not Used
 * @return bool
 */
function user_can_set_post_date($user_id, $blog_id = 1, $category_id = 'None') {
    _deprecated_function(__FUNCTION__, '0.0', 'current_user_can()');

    $author_data = get_userdata($user_id);
    return (($author_data->user_level > 4) && user_can_create_post($user_id, $blog_id, $category_id));
}

/**
 * Whether user can delete a post.
 *
 * @since 1.5
 * @deprecated Use current_user_can()
 * @see current_user_can()
 *
 * @param int $user_id
 * @param int $post_id
 * @param int $blog_id Not Used
 * @return bool returns true if $user_id can edit $post_id's date
 */
function user_can_edit_post_date($user_id, $post_id, $blog_id = 1) {
    _deprecated_function(__FUNCTION__, '0.0', 'current_user_can()');

    $author_data = get_userdata($user_id);
    return (($author_data->user_level > 4) && user_can_edit_post($user_id, $post_id, $blog_id));
}

/**
 * Whether user can delete a post.
 *
 * @since 1.5
 * @deprecated Use current_user_can()
 * @see current_user_can()
 *
 * @param int $user_id
 * @param int $post_id
 * @param int $blog_id Not Used
 * @return bool returns true if $user_id can edit $post_id's comments
 */
function user_can_edit_post_comments($user_id, $post_id, $blog_id = 1) {
    _deprecated_function(__FUNCTION__, '0.0', 'current_user_can()');

    // right now if one can edit a post, one can edit comments made on it
    return user_can_edit_post($user_id, $post_id, $blog_id);
}

/**
 * Whether user can delete a post.
 *
 * @since 1.5
 * @deprecated Use current_user_can()
 * @see current_user_can()
 *
 * @param int $user_id
 * @param int $post_id
 * @param int $blog_id Not Used
 * @return bool returns true if $user_id can delete $post_id's comments
 */
function user_can_delete_post_comments($user_id, $post_id, $blog_id = 1) {
    _deprecated_function(__FUNCTION__, '0.0', 'current_user_can()');

    // right now if one can edit comments, one can delete comments
    return user_can_edit_post_comments($user_id, $post_id, $blog_id);
}

/**
 * Can user can edit other user.
 *
 * @since 1.5
 * @deprecated Use current_user_can()
 * @see current_user_can()
 *
 * @param int $user_id
 * @param int $other_user
 * @return bool
 */
function user_can_edit_user($user_id, $other_user) {
    _deprecated_function(__FUNCTION__, '0.0', 'current_user_can()');

    $user  = get_userdata($user_id);
    $other = get_userdata($other_user);
    if ( $user->user_level > $other->user_level || $user->user_level > 8 || $user->ID == $other->ID )
        return true;
    else
        return false;
}

/**
 * Gets the links associated with category $cat_name.
 *
 * @since 0.71
 * @deprecated Use get_links()
 * @see get_links()
 *
 * @param string $cat_name Optional. The category name to use. If no match is found uses all.
 * @param string $before Optional. The html to output before the link.
 * @param string $after Optional. The html to output after the link.
 * @param string $between Optional. The html to output between the link/image and it's description. Not used if no image or $show_images is true.
 * @param bool $show_images Optional. Whether to show images (if defined).
 * @param string $orderby Optional. The order to output the links. E.g. 'id', 'name', 'url', 'description' or 'rating'. Or maybe owner.
 *        If you start the name with an underscore the order will be reversed. You can also specify 'rand' as the order which will return links in a
 *        random order.
 * @param bool $show_description Optional. Whether to show the description if show_images=false/not defined.
 * @param bool $show_rating Optional. Show rating stars/chars.
 * @param int $limit        Optional. Limit to X entries. If not specified, all entries are shown.
 * @param int $show_updated Optional. Whether to show last updated timestamp
 */
function get_linksbyname($cat_name = "noname", $before = '', $after = '<br />', $between = " ", $show_images = true, $orderby = 'id',
                         $show_description = true, $show_rating = false,
                         $limit = -1, $show_updated = 0) {
    _deprecated_function(__FUNCTION__, '0.0', 'get_links()');

    $cat_id = -1;
    $cat = get_term_by('name', $cat_name, 'link_category');
    if ( $cat )
        $cat_id = $cat->term_id;

    get_links($cat_id, $before, $after, $between, $show_images, $orderby, $show_description, $show_rating, $limit, $show_updated);
}

/**
 * Gets the links associated with the named category.
 *
 * @since 1.0.1
 * @deprecated Use wp_get_links()
 * @see wp_get_links()
 *
 * @param string $category The category to use.
 * @param string $args
 * @return bool|null
 */
function wp_get_linksbyname($category, $args = '') {
    _deprecated_function(__FUNCTION__, '0.0', 'wp_get_links()');

    $cat = get_term_by('name', $category, 'link_category');
    if ( !$cat )
        return false;
    $cat_id = $cat->term_id;

    $args = add_query_arg('category', $cat_id, $args);
    wp_get_links($args);
}

/**
 * Gets an array of link objects associated with category $cat_name.
 *
 * <code>
 *    $links = get_linkobjectsbyname('fred');
 *    foreach ($links as $link) {
 *         echo '<li>'.$link->link_name.'</li>';
 *    }
 * </code>
 *
 * @since 1.0.1
 * @deprecated Use get_linkobjects()
 * @see get_linkobjects()
 *
 * @param string $cat_name The category name to use. If no match is found uses all.
 * @param string $orderby The order to output the links. E.g. 'id', 'name', 'url', 'description', or 'rating'.
 *        Or maybe owner. If you start the name with an underscore the order will be reversed. You can also
 *        specify 'rand' as the order which will return links in a random order.
 * @param int $limit Limit to X entries. If not specified, all entries are shown.
 * @return unknown
 */
function get_linkobjectsbyname($cat_name = "noname" , $orderby = 'name', $limit = -1) {
    _deprecated_function(__FUNCTION__, '0.0', 'get_linkobjects()');

    $cat_id = -1;
    $cat = get_term_by('name', $cat_name, 'link_category');
    if ( $cat )
        $cat_id = $cat->term_id;

    return get_linkobjects($cat_id, $orderby, $limit);
}

/**
 * Gets an array of link objects associated with category n.
 *
 * Usage:
 * <code>
 *    $links = get_linkobjects(1);
 *    if ($links) {
 *        foreach ($links as $link) {
 *            echo '<li>'.$link->link_name.'<br />'.$link->link_description.'</li>';
 *        }
 *    }
 * </code>
 *
 * Fields are:
 * <ol>
 *    <li>link_id</li>
 *    <li>link_url</li>
 *    <li>link_name</li>
 *    <li>link_image</li>
 *    <li>link_target</li>
 *    <li>link_category</li>
 *    <li>link_description</li>
 *    <li>link_visible</li>
 *    <li>link_owner</li>
 *    <li>link_rating</li>
 *    <li>link_updated</li>
 *    <li>link_rel</li>
 *    <li>link_notes</li>
 * </ol>
 *
 * @since 1.0.1
 * @deprecated Use get_bookmarks()
 * @see get_bookmarks()
 *
 * @param int $category The category to use. If no category supplied uses all
 * @param string $orderby the order to output the links. E.g. 'id', 'name', 'url',
 *        'description', or 'rating'. Or maybe owner. If you start the name with an
 *        underscore the order will be reversed. You can also specify 'rand' as the
 *        order which will return links in a random order.
 * @param int $limit Limit to X entries. If not specified, all entries are shown.
 * @return unknown
 */
function get_linkobjects($category = 0, $orderby = 'name', $limit = 0) {
    _deprecated_function(__FUNCTION__, '0.0', 'get_bookmarks()');

    $links = get_bookmarks("category=$category&orderby=$orderby&limit=$limit");

    $links_array = array();
    foreach ($links as $link)
        $links_array[] = $link;

    return $links_array;
}

/**
 * Gets the links associated with category 'cat_name' and display rating stars/chars.
 *
 * @since 0.71
 * @deprecated Use get_bookmarks()
 * @see get_bookmarks()
 *
 * @param string $cat_name The category name to use. If no match is found uses all
 * @param string $before The html to output before the link
 * @param string $after The html to output after the link
 * @param string $between The html to output between the link/image and it's description. Not used if no image or show_images is true
 * @param bool $show_images Whether to show images (if defined).
 * @param string $orderby the order to output the links. E.g. 'id', 'name', 'url',
 *        'description', or 'rating'. Or maybe owner. If you start the name with an
 *        underscore the order will be reversed. You can also specify 'rand' as the
 *        order which will return links in a random order.
 * @param bool $show_description Whether to show the description if show_images=false/not defined
 * @param int $limit Limit to X entries. If not specified, all entries are shown.
 * @param int $show_updated Whether to show last updated timestamp
 */
function get_linksbyname_withrating($cat_name = "noname", $before = '', $after = '<br />', $between = " ",
                                    $show_images = true, $orderby = 'id', $show_description = true, $limit = -1, $show_updated = 0) {
    _deprecated_function(__FUNCTION__, '0.0', 'get_bookmarks()');

    get_linksbyname($cat_name, $before, $after, $between, $show_images, $orderby, $show_description, true, $limit, $show_updated);
}

/**
 * Gets the links associated with category n and display rating stars/chars.
 *
 * @since 0.71
 * @deprecated Use get_bookmarks()
 * @see get_bookmarks()
 *
 * @param int $category The category to use. If no category supplied uses all
 * @param string $before The html to output before the link
 * @param string $after The html to output after the link
 * @param string $between The html to output between the link/image and it's description. Not used if no image or show_images == true
 * @param bool $show_images Whether to show images (if defined).
 * @param string $orderby The order to output the links. E.g. 'id', 'name', 'url',
 *        'description', or 'rating'. Or maybe owner. If you start the name with an
 *        underscore the order will be reversed. You can also specify 'rand' as the
 *        order which will return links in a random order.
 * @param bool $show_description Whether to show the description if show_images=false/not defined.
 * @param string $limit Limit to X entries. If not specified, all entries are shown.
 * @param int $show_updated Whether to show last updated timestamp
 */
function get_links_withrating($category = -1, $before = '', $after = '<br />', $between = " ", $show_images = true,
                              $orderby = 'id', $show_description = true, $limit = -1, $show_updated = 0) {
    _deprecated_function(__FUNCTION__, '0.0', 'get_bookmarks()');

    get_links($category, $before, $after, $between, $show_images, $orderby, $show_description, true, $limit, $show_updated);
}

/**
 * Gets the auto_toggle setting.
 *
 * @since 0.71
 * @deprecated No alternative function available
 *
 * @param int $id The category to get. If no category supplied uses 0
 * @return int Only returns 0.
 */
function get_autotoggle($id = 0) {
    _deprecated_function(__FUNCTION__, '0.0' );
    return 0;
}

/**
 * @since 0.71
 * @deprecated Use wp_list_categories()
 * @see wp_list_categories()
 *
 * @param int $optionall
 * @param string $all
 * @param string $sort_column
 * @param string $sort_order
 * @param string $file
 * @param bool $list
 * @param int $optiondates
 * @param int $optioncount
 * @param int $hide_empty