WordPress.org

Make WordPress Core

Ticket #3982: post-phpdoc.diff

File post-phpdoc.diff, 16.5 KB (added by m0n5t3r, 11 years ago)

post.php phpdoc take 1

  • wp-includes/post.php

    === modified file 'wp-includes/post.php'
     
    11<?php
    2 
    3 //
    4 // Post functions
    5 //
    6 
     2/**
     3 * Post functions
     4 *
     5 * @author Wordpress team (FIXME)
     6 * @version "$Id$"
     7 * @copyright (FIXME)
     8 * @package wordpress
     9 * @subpackage post
     10 */
     11
     12/**
     13 * get metadata for an attached file
     14 *
     15 * @filter get_attached_file
     16 * @param int $attachment_id attachment ID
     17 * @param bool $unfiltered whether to applu filters or not
     18 * @return array
     19 */
    720function get_attached_file( $attachment_id, $unfiltered = false ) {
    821        $file = get_post_meta( $attachment_id, '_wp_attached_file', true );
    922        if ( $unfiltered )
     
    1124        return apply_filters( 'get_attached_file', $file, $attachment_id );
    1225}
    1326
     27/**
     28 * update attached file metadata
     29 *
     30 * @filter update_attached_file
     31 * @param int $attachment_id
     32 * @param string $file
     33 * @return bool
     34 */
    1435function update_attached_file( $attachment_id, $file ) {
    1536        if ( !get_post( $attachment_id ) )
    1637                return false;
     
    2546                return add_post_meta( $attachment_id, '_wp_attached_file', $file );
    2647}
    2748
     49/**
     50 * get post children
     51 *
     52 * @param mixed $args
     53 * @param string $output
     54 * @return mixed
     55 */
    2856function &get_children($args = '', $output = OBJECT) {
    2957        global $post_cache, $wpdb, $blog_id;
    3058
     
    7199        }
    72100}
    73101
    74 // get extended entry info (<!--more-->)
     102/**
     103 * get extended entry info (<!--more-->)
     104 *
     105 * @param string $post
     106 * @return array
     107 */
    75108function get_extended($post) {
    76109        //Match the new style more links
    77110        if ( preg_match('/<!--more(.*?)-->/', $post, $matches) ) {
     
    88121        return array('main' => $main, 'extended' => $extended);
    89122}
    90123
    91 // Retrieves post data given a post ID or post object.
    92 // Handles post caching.
     124/**
     125 * Retrieves post data given a post ID or post object.
     126 * Handles post caching.
     127 *
     128 * @param mixed &$post post ID or post object
     129 * @param string $output
     130 * @return mixed
     131 */
    93132function &get_post(&$post, $output = OBJECT) {
    94133        global $post_cache, $wpdb, $blog_id;
    95134
     
    133172        }
    134173}
    135174
    136 // Takes a post ID, returns its mime type.
     175/**
     176 * Takes a post ID, returns its mime type.
     177 *
     178 * @param int $ID
     179 * @return mixed string or false
     180 */
    137181function get_post_mime_type($ID = '') {
    138182        $post = & get_post($ID);
    139183
     
    143187        return false;
    144188}
    145189
     190/**
     191 * Takes a post ID and returns its status
     192 *
     193 * @param int $ID
     194 * @return mixed post status or false
     195 */
    146196function get_post_status($ID = '') {
    147197        $post = get_post($ID);
    148198
     
    156206        return false;
    157207}
    158208
     209/**
     210 * Returns post type
     211 *
     212 * @param mixed $post post object or post ID
     213 * @return mixed post type or false
     214 */
    159215function get_post_type($post = false) {
    160216        global $wpdb, $posts;
    161217
     
    170226        return false;
    171227}
    172228
     229/**
     230 * returns a number of posts
     231 *
     232 * @param array $args
     233 * @return array
     234 */
    173235function get_posts($args) {
    174236        global $wpdb;
    175237
     
    254316        return $posts;
    255317}
    256318
    257 //
    258 // Post meta functions
    259 //
    260 
     319/**
     320 * adds metadata for post
     321 *
     322 * @param int $post_id post ID
     323 * @param string $key
     324 * @param mixed $value
     325 * @param bool $unique whether to check for a value with the same key
     326 * @return bool
     327 */
    261328function add_post_meta($post_id, $key, $value, $unique = false) {
    262329        global $wpdb, $post_meta_cache, $blog_id;
    263330
     
    279346        return true;
    280347}
    281348
     349/**
     350 * delete post metadata
     351 *
     352 * @param int $post_id post ID
     353 * @param string $key
     354 * @param mixed $value
     355 * @return bool
     356 */
    282357function delete_post_meta($post_id, $key, $value = '') {
    283358        global $wpdb, $post_meta_cache, $blog_id;
    284359
     
    309384        return true;
    310385}
    311386
     387/**
     388 * get a post meta field
     389 *
     390 * @param int $post_id post ID
     391 * @param string $key
     392 * @param bool $single whether to return a single value
     393 * @return mixed
     394 */
    312395function get_post_meta($post_id, $key, $single = false) {
    313396        global $wpdb, $post_meta_cache, $blog_id;
    314397
     
    335418        }
    336419}
    337420
     421/**
     422 * update a post meta field
     423 *
     424 * @param int $post_id post ID
     425 * @param string $key
     426 * @param mixed $value
     427 * @param mixed $prev_value previous value (for differentiating between meta fields with the same key and post ID)
     428 * @return bool
     429 */
    338430function update_post_meta($post_id, $key, $value, $prev_value = '') {
    339431        global $wpdb, $post_meta_cache, $blog_id;
    340432
     
    371463}
    372464
    373465
     466/**
     467 * retrieve post custom fields
     468 *
     469 * @param int $post_id post ID
     470 * @return array
     471 */
    374472function get_post_custom($post_id = 0) {
    375473        global $id, $post_meta_cache, $wpdb, $blog_id;
    376474
     
    385483        return $post_meta_cache[$blog_id][$post_id];
    386484}
    387485
     486/**
     487 * retrieve post custom field names
     488 *
     489 * @param int $post_id post ID
     490 * @return array
     491 */
    388492function get_post_custom_keys( $post_id = 0 ) {
    389493        $custom = get_post_custom( $post_id );
    390494
     
    396500}
    397501
    398502
     503/**
     504 * retrieve values for a custom post field
     505 *
     506 * @param string $key field name
     507 * @param int $post_id post ID
     508 * @return mixed
     509 */
    399510function get_post_custom_values( $key = '', $post_id = 0 ) {
    400511        $custom = get_post_custom($post_id);
    401512
    402513        return $custom[$key];
    403514}
    404515
     516/**
     517 * delete post
     518 *
     519 * @action delete_post
     520 * @action edit_category
     521 * @param int $postid post ID
     522 * @return mixed
     523 */
    405524function wp_delete_post($postid = 0) {
    406525        global $wpdb, $wp_rewrite;
    407526        $postid = (int) $postid;
     
    446565        return $post;
    447566}
    448567
     568/**
     569 * retrieve the list of categories for a post
     570 *
     571 * @param int $post_id post ID
     572 * @return array
     573 */
    449574function wp_get_post_categories($post_id = 0) {
    450575        $cats = &get_the_category($post_id);
    451576        $cat_ids = array();
     
    454579        return array_unique($cat_ids);
    455580}
    456581
     582/**
     583 * get the $num most recent posts
     584 *
     585 * @param int $num number of posts to get
     586 * @return array
     587 */
    457588function wp_get_recent_posts($num = 10) {
    458589        global $wpdb;
    459590
     
    468599        return $result?$result:array();
    469600}
    470601
     602/**
     603 * get one post
     604 *
     605 * @param int $postid post ID
     606 * @param string $mode what to return
     607 * @return mixed
     608 */
    471609function wp_get_single_post($postid = 0, $mode = OBJECT) {
    472610        global $wpdb;
    473611
     
    484622        return $post;
    485623}
    486624
     625/**
     626 * insert a post
     627 *
     628 * @filter content_save_pre
     629 * @filter content_filtered_save_pre
     630 * @filter excerpt_save_pre
     631 * @filter title_save_pre
     632 * @filter category_save_pre
     633 * @filter status_save_pre
     634 * @filter name_save_pre
     635 * @filter comment_status_pre
     636 * @filter ping_status_pre
     637 * @action private_to_published
     638 * @action edit_post
     639 * @action publish_post
     640 * @action xmlrpc_publish_post
     641 * @action app_publish_post
     642 * @action publish_page
     643 * @action save_post
     644 * @action wp_insert_post
     645 * @param array $postarr post contents
     646 * @return int post ID or 0 on error
     647 */
    487648function wp_insert_post($postarr = array()) {
    488649        global $wpdb, $wp_rewrite, $allowedtags, $user_ID;
    489650
     
    712873        return $post_ID;
    713874}
    714875
     876/**
     877 * update a post
     878 *
     879 * @param array $postarr post data
     880 * @return int
     881 */
    715882function wp_update_post($postarr = array()) {
    716883        global $wpdb;
    717884
     
    752919        return wp_insert_post($postarr);
    753920}
    754921
     922/**
     923 * mark a post as "published"
     924 *
     925 * @param int $post_id post ID
     926 * @return mixed int or void
     927 */
    755928function wp_publish_post($post_id) {
    756929        $post = get_post($post_id);
    757930
    758         if ( empty($post) )
     931        if ( empty($post) ) //FIXME: inconsistent error handling, should return 0
    759932                return;
    760933
    761934        if ( 'publish' == $post->post_status )
     
    764937        return wp_update_post(array('post_status' => 'publish', 'ID' => $post_id, 'no_filter' => true));
    765938}
    766939
     940/**
     941 * set categories for a post
     942 *
     943 * @action edit_category
     944 * @param int $post_ID post ID
     945 * @param array $post_categories
     946 */
    767947function wp_set_post_categories($post_ID = 0, $post_categories = array()) {
    768948        global $wpdb;
    769949        // If $post_categories isn't already an array, make it one:
     
    8201000        }
    8211001}       // wp_set_post_categories()
    8221002
    823 //
    824 // Trackback and ping functions
    825 //
     1003/**
     1004 * Trackback and ping functions
     1005 */
    8261006
    827 function add_ping($post_id, $uri) { // Add a URL to those already pung
     1007/**
     1008 * add URL to the pinged URLs list
     1009 *
     1010 * @filter add_ping
     1011 * @param int $post_id post ID
     1012 * @param string $uri
     1013 * @return mixed
     1014 */
     1015function add_ping($post_id, $uri) {
    8281016        global $wpdb;
    8291017        $pung = $wpdb->get_var("SELECT pinged FROM $wpdb->posts WHERE ID = $post_id");
    8301018        $pung = trim($pung);
     
    8351023        return $wpdb->query("UPDATE $wpdb->posts SET pinged = '$new' WHERE ID = $post_id");
    8361024}
    8371025
    838 function get_enclosed($post_id) { // Get enclosures already enclosed for a post
     1026/**
     1027 * Get enclosures already enclosed for a post
     1028 *
     1029 * @filter get_enclosed
     1030 * @param int $post_id post ID
     1031 * @return array
     1032 */
     1033function get_enclosed($post_id) {
    8391034        global $wpdb;
    8401035        $custom_fields = get_post_custom( $post_id );
    8411036        $pung = array();
     
    8541049        return $pung;
    8551050}
    8561051
    857 function get_pung($post_id) { // Get URLs already pung for a post
     1052/**
     1053 * Get URLs already pinged for a post
     1054 *
     1055 * @filter get_pung
     1056 * @param int $post_id post ID
     1057 * @return array
     1058 */
     1059function get_pung($post_id) {
    8581060        global $wpdb;
    8591061        $pung = $wpdb->get_var("SELECT pinged FROM $wpdb->posts WHERE ID = $post_id");
    8601062        $pung = trim($pung);
     
    8631065        return $pung;
    8641066}
    8651067
    866 function get_to_ping($post_id) { // Get any URLs in the todo list
     1068/**
     1069 * Get any URLs in the todo list
     1070 *
     1071 * @filter get_to_ping
     1072 * @param int $post_id post ID
     1073 * @return array
     1074 */
     1075function get_to_ping($post_id) {
    8671076        global $wpdb;
    8681077        $to_ping = $wpdb->get_var("SELECT to_ping FROM $wpdb->posts WHERE ID = $post_id");
    8691078        $to_ping = trim($to_ping);
     
    8721081        return $to_ping;
    8731082}
    8741083
    875 // do trackbacks for a list of urls
    876 // accepts a comma-separated list of trackback urls and a post id
     1084/**
     1085 * do trackbacks for a list of urls
     1086 *
     1087 * @param string $tb_list comma separated list of URLs
     1088 * @param int $post_id post ID
     1089 */
    8771090function trackback_url_list($tb_list, $post_id) {
    8781091        if (!empty($tb_list)) {
    8791092                // get post data
     
    8971110                }
    8981111}
    8991112
    900 //
    901 // Page functions
    902 //
     1113/**
     1114 * Page functions
     1115 */
    9031116
     1117/**
     1118 * get a list of page IDs
     1119 * handles caching
     1120 *
     1121 * @return array
     1122 */
    9041123function get_all_page_ids() {
    9051124        global $wpdb;
    9061125
     
    9131132}
    9141133
    9151134
    916 // Retrieves page data given a page ID or page object.
    917 // Handles page caching.
     1135/**
     1136 * retrieves page data given a page ID or page object
     1137 *
     1138 * @param mixed &$page page object or page ID
     1139 * @param string $output what to output
     1140 * @return mixed
     1141 */
    9181142function &get_page(&$page, $output = OBJECT) {
    9191143        global $wpdb, $blog_id;
    9201144
     
    9671191        }
    9681192}
    9691193
     1194/**
     1195 * retrieves a page given its path
     1196 *
     1197 * @param string $page_path page path
     1198 * @param string $output output type
     1199 * @return mixed
     1200 */
    9701201function get_page_by_path($page_path, $output = OBJECT) {
    9711202        global $wpdb;
    9721203        $page_path = rawurlencode(urldecode($page_path));
     
    9981229        return NULL;
    9991230}
    10001231
     1232/**
     1233 * retrieve a page given its title
     1234 *
     1235 * @param string $page_title page title
     1236 * @param string $output output type
     1237 * @return mixed
     1238 */
    10011239function get_page_by_title($page_title, $output = OBJECT) {
    10021240        global $wpdb;
    10031241        $page_title = $wpdb->escape($page_title);
     
    10081246        return NULL;
    10091247}
    10101248
     1249/**
     1250 * retrieve child pages
     1251 *
     1252 * @param int $page_id page ID
     1253 * @param array $pages list of pages
     1254 * @return array
     1255 */
    10111256function &get_page_children($page_id, $pages) {
    10121257        global $page_cache, $blog_id;
    10131258
     
    10251270        return $page_list;
    10261271}
    10271272
    1028 //fetches the pages returned as a FLAT list, but arranged in order of their hierarchy, i.e., child parents
    1029 //immediately follow their parents
     1273/**
     1274 * fetches the pages returned as a FLAT list, but arranged in order of their hierarchy, i.e., child parents
     1275 * immediately follow their parents
     1276 *
     1277 * @param array $posts posts array
     1278 * @param int $parent parent page ID
     1279 * @return array
     1280 */
    10301281function get_page_hierarchy($posts, $parent = 0) {
    10311282        $result = array ( );
    10321283        if ($posts) { foreach ($posts as $post) {
     
    10391290        return $result;
    10401291}
    10411292
     1293/**
     1294 * builds a page URI
     1295 *
     1296 * @param int $page_id page ID
     1297 * @return string
     1298 */
    10421299function get_page_uri($page_id) {
    10431300        $page = get_page($page_id);
    10441301        $uri = urldecode($page->post_name);
     
    10551312        return $uri;
    10561313}
    10571314
     1315/**
     1316 * retrieve a list of pages
     1317 *
     1318 * @filter get_pages
     1319 * @param mixed $args array or query string
     1320 * @return array
     1321 */
    10581322function &get_pages($args = '') {
    10591323        global $wpdb;
    10601324
     
    11581422        return $pages;
    11591423}
    11601424
     1425/**
     1426 * build page URI index
     1427 *
     1428 */
    11611429function generate_page_uri_index() {
    11621430        global $wpdb;
    11631431
     
    11961464        }
    11971465}
    11981466
    1199 //
    1200 // Attachment functions
    1201 //
     1467/**
     1468 * Attachment functions
     1469 */
    12021470
     1471/**
     1472 * check if the attachment URI is a local one and it is really an attachment
     1473 *
     1474 * @param string $url URL to check
     1475 * @return bool
     1476 */
    12031477function is_local_attachment($url) {
    12041478        if (strpos($url, get_bloginfo('url')) === false)
    12051479                return false;
     
    12131487        return false;
    12141488}
    12151489
     1490/**
     1491 * insert an attachment
     1492 *
     1493 * @filter content_save_pre
     1494 * @filter content_filtered_save_pre
     1495 * @filter excerpt_save_pre
     1496 * @filter title_save_pre
     1497 * @filter category_save_pre
     1498 * @filter name_save_pre
     1499 * @filter comment_status_pre
     1500 * @filter ping_status_pre
     1501 * @filter post_mime_type_pre
     1502 * @action edit_attachment
     1503 * @action add_attachment
     1504 * @param object $object attachment object
     1505 * @param string $file filename
     1506 * @param int $post_parent parent post ID
     1507 * @return int
     1508 */
    12161509function wp_insert_attachment($object, $file = false, $post_parent = 0) {
    12171510        global $wpdb, $user_ID;
    12181511
     
    13681661        return $post_ID;
    13691662}
    13701663
     1664/**
     1665 * delete an attachment
     1666 *
     1667 * @filter wp_delete_file
     1668 * @action delete_attachment
     1669 * @param int $postid attachment Id
     1670 * @return mixed
     1671 */
    13711672function wp_delete_attachment($postid) {
    13721673        global $wpdb;
    13731674        $postid = (int) $postid;
     
    14081709        return $post;
    14091710}
    14101711
     1712/**
     1713 * retrieve metadata for an attachment
     1714 *
     1715 * @filter wp_get_attachment_metadata
     1716 * @param int $post_id attachment ID
     1717 * @param bool $unfiltered if true, filters are not ran
     1718 * @return array
     1719 */
    14111720function wp_get_attachment_metadata( $post_id, $unfiltered = false ) {
    14121721        $post_id = (int) $post_id;
    14131722        if ( !$post =& get_post( $post_id ) )
     
    14191728        return apply_filters( 'wp_get_attachment_metadata', $data, $post->ID );
    14201729}
    14211730
     1731/**
     1732 * update metadata for an attachment
     1733 *
     1734 * @filter wp_update_attachment_metadata
     1735 * @param int $post_id attachment ID
     1736 * @param array $data attachment data
     1737 * @return int
     1738 */
    14221739function wp_update_attachment_metadata( $post_id, $data ) {
    14231740        $post_id = (int) $post_id;
    14241741        if ( !$post =& get_post( $post_id ) )
     
    14341751                return add_post_meta( $post->ID, '_wp_attachment_metadata', $data );
    14351752}
    14361753
     1754/**
     1755 * retrieve the URL for an attachment
     1756 *
     1757 * @filter wp_get_attachment_url
     1758 * @param int $post_id attachment ID
     1759 * @return string
     1760 */
    14371761function wp_get_attachment_url( $post_id = 0 ) {
    14381762        $post_id = (int) $post_id;
    14391763        if ( !$post =& get_post( $post_id ) )
     
    14471771        return apply_filters( 'wp_get_attachment_url', $url, $post->ID );
    14481772}
    14491773
     1774/**
     1775 * retrieve thumbnail for an attachment
     1776 *
     1777 * @filter wp_get_attachment_thumb_file
     1778 * @param int $post_id attachment ID
     1779 * @return mixed
     1780 */
    14501781function wp_get_attachment_thumb_file( $post_id = 0 ) {
    14511782        $post_id = (int) $post_id;
    14521783        if ( !$post =& get_post( $post_id ) )
     
    14611792        return false;
    14621793}
    14631794
     1795/**
     1796 * retrieve URL for an attachment thumbnail
     1797 *
     1798 * @filter wp_get_attachment_thumb_url
     1799 * @param int $post_id attachment ID
     1800 * @return string
     1801 */
    14641802function wp_get_attachment_thumb_url( $post_id = 0 ) {
    14651803        $post_id = (int) $post_id;
    14661804        if ( !$post =& get_post( $post_id ) )
     
    14761814        return apply_filters( 'wp_get_attachment_thumb_url', $url, $post->ID );
    14771815}
    14781816
     1817/**
     1818 * check if the attachment is an image
     1819 *
     1820 * @param int $post_id attachment ID
     1821 * @return bool
     1822 */
    14791823function wp_attachment_is_image( $post_id = 0 ) {
    14801824        $post_id = (int) $post_id;
    14811825        if ( !$post =& get_post( $post_id ) )
     
    14931837        return false;
    14941838}
    14951839
     1840/**
     1841 * retrieve the icon for a MIME type
     1842 *
     1843 * @filter icon_dir
     1844 * @filter icon_dir_uri
     1845 * @filter wp_mime_type_icon
     1846 * @param string $mime MIME type
     1847 * @return string
     1848 */
    14961849function wp_mime_type_icon( $mime = 0 ) {
    14971850        $post_id = 0;
    14981851        if ( is_numeric($mime) ) {
     
    15321885        return apply_filters( 'wp_mime_type_icon', $src, $mime, $post_id ); // Last arg is 0 if function pass mime type.
    15331886}
    15341887
     1888/**
     1889 * store slug history as custom fields; only looks at published posts
     1890 *
     1891 * @param int $post_id post ID
     1892 * @return int
     1893 */
    15351894function wp_check_for_changed_slugs($post_id) {
    15361895        if ( !strlen($_POST['wp-old-slug']) )
    15371896                return $post_id;