WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
07/02/2008 11:07:56 PM (17 years ago)
Author:
mdawaffe
Message:

crazyhorse: merge with log:trunk@8151:8240

File:
1 edited

Legend:

Unmodified
Added
Removed

  • branches/crazyhorse/wp-includes/post.php

    r8103 r8242  
    1313
    1414/**
    15  * get_attached_file() - Get metadata for an attached file
    16  *
    17  * {@internal Missing Long Description}}
     15 * Retrieve attached file path based on attachment ID.
     16 *
     17 * You can optionally send it through the 'get_attached_file' filter, but by
     18 * default it will just return the file path unfiltered.
     19 *
     20 * The function works by getting the single post meta name, named
     21 * '_wp_attached_file' and returning it. This is a convenience function to
     22 * prevent looking up the meta name and provide a mechanism for sending the
     23 * attached filename through a filter.
    1824 *
    1925 * @package WordPress
    2026 * @subpackage Post
    2127 * @since 2.0
     28 * @uses apply_filters() Calls 'get_attached_file' on file path and attachment ID
    2229 *
    2330 * @param int $attachment_id Attachment ID
    2431 * @param bool $unfiltered Whether to apply filters or not
    25  * @return array {@internal Missing Description}}
     32 * @return string The file path to the attached file.
    2633 */
    2734function get_attached_file( $attachment_id, $unfiltered = false ) {
    … …  
    3340
    3441/**
    35  * update_attached_file() - Update attached file metadata
    36  *
    37  * {@internal Missing Long Description}}
     42 * Update attachment file path based on attachment ID.
     43 *
     44 * Used to update the file path of the attachment, which uses post meta name
     45 * '_wp_attached_file' to store the path of the attachment.
    3846 *
    3947 * @package WordPress
    4048 * @subpackage Post
    4149 * @since 2.1
     50 * @uses apply_filters() Calls 'update_attached_file' on file path and attachment ID
    4251 *
    4352 * @param int $attachment_id Attachment ID
    44  * @param string $file {@internal Missing Description}}
    45  * @return bool|mixed {@internal Missing Description}}
     53 * @param string $file File path for the attachment
     54 * @return bool False on failure, true on success.
    4655 */
    4756function update_attached_file( $attachment_id, $file ) {
    … …  
    5564
    5665/**
    57  * get_children() - Get post children
    58  *
    59  * {@internal Missing Long Description}}
     66 * Retrieve all children of the post parent ID.
     67 *
     68 * Normally, without any enhancements, the children would apply to pages. In the
     69 * context of the inner workings of WordPress, pages, posts, and attachments
     70 * share the same table, so therefore the functionality could apply to any one
     71 * of them. It is then noted that while this function does not work on posts, it
     72 * does not mean that it won't work on posts. It is recommended that you know
     73 * what context you wish to retrieve the children of.
     74 *
     75 * Attachments may also be made the child of a post, so if that is an accurate
     76 * statement (which needs to be verified), it would then be possible to get
     77 * all of the attachments for a post. Attachments have since changed since
     78 * version 2.5, so this is most likely unaccurate, but serves generally as an
     79 * example of what is possible.
     80 *
     81 * The arguments listed as defaults are for this function and also of the
     82 * get_posts() function. The arguments are combined with the get_children
     83 * defaults and are then passed to the get_posts() function, which accepts
     84 * additional arguments. You can replace the defaults in this function, listed
     85 * below and the additional arguments listed in the get_posts() function.
     86 *
     87 * The 'post_parent' is the most important argument and important attention
     88 * needs to be paid to the $args parameter. If you pass either an object or an
     89 * integer (number), then just the 'post_parent' is grabbed and everything else
     90 * is lost. If you don't specify any arguments, then it is assumed that you are
     91 * in The Loop and the post parent will be grabbed for from the current post.
     92 *
     93 * The 'post_parent' argument is the ID to get the children. The 'numberposts'
     94 * is the amount of posts to retrieve that has a default of '-1', which is
     95 * used to get all of the posts. Giving a number higher than 0 will only
     96 * retrieve that amount of posts.
     97 *
     98 * The 'post_type' and 'post_status' arguments can be used to choose what
     99 * criteria of posts to retrieve. The 'post_type' can be anything, but WordPress
     100 * post types are 'post', 'pages', and 'attachments'. The 'post_status'
     101 * argument will accept any post status within the write administration panels.
     102 *
     103 * @see get_posts() Has additional arguments that can be replaced.
     104 * @internal Claims made in the long description might be inaccurate.
    60105 *
    61106 * @package WordPress
    … …  
    63108 * @since 2.0
    64109 *
    65  * @param mixed $args {@internal Missing Description}}
    66  * @param string $output {@internal Missing Description}}
    67  * @return mixed {@internal Missing Description}}
     110 * @param mixed $args Optional. User defined arguments for replacing the defaults.
     111 * @param string $output Optional. Constant for return type, either OBJECT (default), ARRAY_A, ARRAY_N.
     112 * @return array|bool False on failure and the type will be determined by $output parameter.
    68113 */
    69114function &get_children($args = '', $output = OBJECT) {
    … …  
    112157
    113158/**
    114  * get_extended() - get extended entry info (<!--more-->)
    115  *
    116  * {@internal Missing Long Description}}
    117  *
    118  * @package WordPress
    119  * @subpackage Post
    120  * @since 1.0.1
     159 * get_extended() - Get extended entry info (<!--more-->)
     160 *
     161 * {@internal Missing Long Description}}
     162 *
     163 * @package WordPress
     164 * @subpackage Post
     165 * @since 1.0.0
    121166 *
    122167 * @param string $post {@internal Missing Description}}
    … …  
    148193 * @since 1.5.1
    149194 * @uses $wpdb
     195 * @link http://codex.wordpress.org/Function_Reference/get_post
    150196 *
    151197 * @param int|object &$post post ID or post object
    … …  
    171217        if ( ! $_post = wp_cache_get($post, 'posts') ) {
    172218            $_post = & $wpdb->get_row($wpdb->prepare("SELECT * FROM $wpdb->posts WHERE ID = %d LIMIT 1", $post));
     219            if ( ! $_post )
     220                return $null;
    173221            _get_post_ancestors($_post);
    174222            wp_cache_add($_post->ID, $_post, 'posts');
    … …  
    192240
    193241/**
    194  * get_post_ancestors() - Retrieve ancestors for a post
     242 * Retrieve ancestors of a post.
    195243 *
    196244 * @package WordPress
    … …  
    198246 * @since 2.5
    199247 *
    200  * @param int|object $post post ID or post object
    201  * @return array of ancestor IDs
     248 * @param int|object $post Post ID or post object
     249 * @return array Ancestor IDs or empty array if none are found.
    202250 */
    203251function get_post_ancestors($post) {
    … …  
    211259
    212260/**
    213  * get_post_field() - Retrieve a field based on a post ID.
     261 * Retrieve data from a post field based on Post ID.
     262 *
     263 * Examples of the post field will be, 'post_type', 'post_status', 'content',
     264 * etc and based off of the post object property or key names.
     265 *
     266 * The context values are based off of the taxonomy filter functions and
     267 * supported values are found within those functions.
    214268 *
    215269 * @package WordPress
    216270 * @subpackage Post
    217271 * @since 2.3
    218  *
    219  * @param string $field {@internal Missing Description}}
     272 * @uses sanitize_post_field() See for possible $context values.
     273 *
     274 * @param string $field Post field name
    220275 * @param id $post Post ID
    221  * @param string $context Optional. How to filter the field
     276 * @param string $context Optional. How to filter the field. Default is display.
    222277 * @return WP_Error|string Value in post field or WP_Error on failure
    223278 */
    … …  
    239294
    240295/**
    241  * get_post_mime_type() - Takes a post ID, returns its mime type.
     296 * Retrieve the mime type of an attachment based on the ID.
     297 *
     298 * This function can be used with any post type, but it makes more sense with
     299 * attachments.
    242300 *
    243301 * @package WordPress
    … …  
    245303 * @since 2.0
    246304 *
    247  * @param int $ID Post ID
     305 * @param int $ID Optional. Post ID.
    248306 * @return bool|string False on failure or returns the mime type
    249307 */
    … …  
    258316
    259317/**
    260  * get_post_status() - Takes a post ID and returns its status
    261  *
    262  * {@internal Missing Long Description}}
     318 * Retrieve the post status based on the Post ID.
     319 *
     320 * If the post ID is of an attachment, then the parent post status will be given
     321 * instead.
    263322 *
    264323 * @package WordPress
    … …  
    266325 * @since 2.0
    267326 *
    268  * @param int $ID {@internal Missing Description}}
    269  * @return string|bool post status or false
     327 * @param int $ID Post ID
     328 * @return string|bool Post status or false on failure.
    270329 */
    271330function get_post_status($ID = '') {
    … …  
    283342
    284343/**
    285  * get_post_statuses( ) - Retuns the possible user post status values
     344 * Retrieve all of the WordPress supported post statuses.
    286345 *
    287346 * Posts have a limited set of valid status values, this provides the
    … …  
    292351 * @since 2.5
    293352 *
    294  * @return array
     353 * @return array List of post statuses.
    295354 */
    296355function get_post_statuses( ) {
    … …  
    306365
    307366/**
    308  * get_page_statuses( ) - Retuns the possible user page status values
     367 * Retrieve all of the WordPress support page statuses.
    309368 *
    310369 * Pages have a limited set of valid status values, this provides the
    … …  
    315374 * @since 2.5
    316375 *
    317  * @return array
     376 * @return array List of page statuses.
    318377 */
    319378function get_page_statuses( ) {
    … …  
    395454 * @since 1.2
    396455 * @uses $wpdb
     456 * @link http://codex.wordpress.org/Template_Tags/get_posts
    397457 *
    398458 * @param array $args {@internal Missing Description}}
    … …  
    441501 * @since 1.5
    442502 * @uses $wpdb
     503 * @link http://codex.wordpress.org/Function_Reference/add_post_meta
    443504 *
    444505 * @param int $post_id post ID
    … …  
    475536 * @since 1.5
    476537 * @uses $wpdb
     538 * @link http://codex.wordpress.org/Function_Reference/delete_post_meta
    477539 *
    478540 * @param int $post_id post ID
    … …  
    517579 * @since 1.5
    518580 * @uses $wpdb
     581 * @link http://codex.wordpress.org/Function_Reference/get_post_meta
    519582 *
    520583 * @param int $post_id post ID
    … …  
    560623 * @since 1.5
    561624 * @uses $wpdb
     625 * @link http://codex.wordpress.org/Function_Reference/update_post_meta
    562626 *
    563627 * @param int $post_id post ID
    … …  
    621685 * @subpackage Post
    622686 * @since 1.2
     687 * @link http://codex.wordpress.org/Function_Reference/get_post_custom
    623688 *
    624689 * @uses $id
    … …  
    648713 * @subpackage Post
    649714 * @since 1.2
     715 * @link http://codex.wordpress.org/Function_Reference/get_post_custom_keys
    650716 *
    651717 * @param int $post_id post ID
    … …  
    662728}
    663729
    664 
     730/**
     731 * get_post_custom_values() - Retrieve values for a custom post field
     732 *
     733 * @package WordPress
     734 * @subpackage Post
     735 * @since 1.2
     736 * @link http://codex.wordpress.org/Function_Reference/get_post_custom_values
     737 *
     738 * @param string $key field name
     739 * @param int $post_id post ID
     740 * @return mixed {@internal Missing Description}}
     741 */
    665742function get_post_custom_values( $key = '', $post_id = 0 ) {
    666743    $custom = get_post_custom($post_id);
    … …  
    669746}
    670747
     748/**
     749 * sanitize_post() - Sanitize every post field
     750 *
     751 * {@internal Missing Long Description}}
     752 *
     753 * @package WordPress
     754 * @subpackage Post
     755 * @since 2.3
     756 *
     757 * @param object|array $post The Post Object or Array
     758 * @param string $context How to sanitize post fields
     759 * @return object|array The now sanitized Post Object or Array (will be the same type as $post)
     760 */
    671761function sanitize_post($post, $context = 'display') {
    672762    if ( 'raw' == $context )
    … …  
    755845
    756846/**
    757  * Count number of posts of a post type and is permissible.
    758  *
    759  * This function provides an efficient method of finding the amount
    760  * of post's type a blog has. Another method is to count the amount
    761  * of items in get_posts(), but that method has a lot of overhead
    762  * with doing so. Therefore, when developing for 2.5+, use this
    763  * function instead.
    764  *
    765  * The $perm parameter checks for 'readable' value and if the user
    766  * can read private posts, it will display that for the user that
    767  * is signed in.
     847 * Count number of posts of a post type and is user has permissions to view.
     848 *
     849 * This function provides an efficient method of finding the amount of post's
     850 * type a blog has. Another method is to count the amount of items in
     851 * get_posts(), but that method has a lot of overhead with doing so. Therefore,
     852 * when developing for 2.5+, use this function instead.
     853 *
     854 * The $perm parameter checks for 'readable' value and if the user can read
     855 * private posts, it will display that for the user that is signed in.
    768856 *
    769857 * @package WordPress
    … …  
    9281016 * @package WordPress
    9291017 * @subpackage Post
    930  * @since 1.0.1
     1018 * @since 1.0.0
    9311019 *
    9321020 * @param int $postid post ID
    … …  
    10561144 * @package WordPress
    10571145 * @subpackage Post
    1058  * @since 1.0.1
     1146 * @since 1.0.0
    10591147 *
    10601148 * @param int $num number of posts to get
    … …  
    10831171 * @package WordPress
    10841172 * @subpackage Post
    1085  * @since 1.0.1
     1173 * @since 1.0.0
    10861174 * @uses $wpdb
    10871175 *
    … …  
    11151203 * @package WordPress
    11161204 * @subpackage Post
    1117  * @since 1.0.1
     1205 * @since 1.0.0
    11181206 *
    11191207 * @uses $wpdb
    … …  
    13351423 * @package WordPress
    13361424 * @subpackage Post
    1337  * @since 1.0.1
     1425 * @since 1.0.0
    13381426 * @uses $wpdb
    13391427 *
    … …  
    14481536}
    14491537
     1538/**
     1539 * wp_add_post_tags() - Adds the tags to a post
     1540 *
     1541 * @uses wp_set_post_tags() Same first two paraeters, but the last parameter is always set to true.
     1542 *
     1543 * @package WordPress
     1544 * @subpackage Post
     1545 * @since 2.3
     1546 *
     1547 * @param int $post_id Optional. Post ID
     1548 * @param string $tags The tags to set for the post
     1549 * @return bool|null Will return false if $post_id is not an integer or is 0. Will return null otherwise
     1550 */
    14501551function wp_add_post_tags($post_id = 0, $tags = '') {
    14511552    return wp_set_post_tags($post_id, $tags, true);
    14521553}
    14531554
     1555/**
     1556 * wp_set_post_tags() - Set the tags for a post
     1557 *
     1558 * {@internal Missing Long Description}}
     1559 *
     1560 * @package WordPress
     1561 * @subpackage Post
     1562 * @since 2.3
     1563 * @uses $wpdb
     1564 *
     1565 * @param int $post_id post ID
     1566 * @param string $tags The tags to set for the post
     1567 * @param bool $append If true, don't delete existing tags, just add on. If false, replace the tags with the new tags.
     1568 * @return bool|null Will return false if $post_id is not an integer or is 0. Will return null otherwise
     1569 */
    14541570function wp_set_post_tags( $post_id = 0, $tags = '', $append = false ) {
    1455     /* $append - true = don't delete existing tags, just add on, false = replace the tags with the new tags */
    14561571
    14571572    $post_id = (int) $post_id;
    … …  
    15461661}
    15471662
    1548 function get_enclosed($post_id) { // Get enclosures already enclosed for a post
     1663/**
     1664 * get_enclosed() - Get enclosures already enclosed for a post
     1665 *
     1666 * {@internal Missing Long Description}}
     1667 *
     1668 * @package WordPress
     1669 * @subpackage Post
     1670 * @since 1.5
     1671 * @uses $wpdb
     1672 *
     1673 * @param int $post_id post ID
     1674 * @return array {@internal Missing Description}}
     1675 */
     1676function get_enclosed($post_id) {
    15491677    $custom_fields = get_post_custom( $post_id );
    15501678    $pung = array();
    … …  
    16151743 * @package WordPress
    16161744 * @subpackage Post
    1617  * @since 1.0.1
     1745 * @since 1.0.0
    16181746 *
    16191747 * @param string $tb_list comma separated list of URLs
Note: See TracChangeset for help on using the changeset viewer.