Changeset 29093
- Timestamp:
- 07/11/2014 10:27:02 AM (10 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/src/wp-includes/post.php
r29092 r29093 308 308 * @since 2.0.0 309 309 * 310 * @see get_posts() Has additional arguments that can be replaced.310 * @see get_posts() 311 311 * 312 312 * @param mixed $args Optional. User defined arguments for replacing the defaults. Default empty. … … 407 407 * 408 408 * @since 1.5.1 409 *410 * @see http://codex.wordpress.org/Function_Reference/get_post411 409 * 412 410 * @param int|WP_Post $post Optional. Post ID or post object. Defaults to global $post. … … 1830 1828 * @todo Tie to WP_Query default args hash notation. 1831 1829 * 1832 * @see WP_Query::query() See for more default arguments and information. 1833 * @see http://codex.wordpress.org/Template_Tags/get_posts 1830 * @see WP_Query::query() 1834 1831 * 1835 1832 * @param array $args Optional. Overrides defaults. … … 1878 1875 * 1879 1876 * @since 1.5.0 1880 * @link http://codex.wordpress.org/Function_Reference/add_post_meta1881 * 1882 * @param int $post_id Post ID.1883 * @param string $meta_key Metadata name.1884 * @param mixed $meta_value Metadata value. Must be serializable if non-scalar.1885 * @param bool $unique Optional, default is false. Whether the same key should not be added.1877 * 1878 * @param int $post_id Post ID. 1879 * @param string $meta_key Metadata name. 1880 * @param mixed $meta_value Metadata value. Must be serializable if non-scalar. 1881 * @param bool $unique Optional. Whether the same key should not be added. 1882 * Default false. 1886 1883 * @return int|bool Meta ID on success, false on failure. 1887 1884 */ 1888 function add_post_meta($post_id, $meta_key, $meta_value, $unique = false) { 1885 function add_post_meta( $post_id, $meta_key, $meta_value, $unique = false ) { 1886 // Make sure meta is added to the post, not a revision. 1887 if ( $the_post = wp_is_post_revision($post_id) ) 1888 $post_id = $the_post; 1889 1890 return add_metadata('post', $post_id, $meta_key, $meta_value, $unique); 1891 } 1892 1893 /** 1894 * Remove metadata matching criteria from a post. 1895 * 1896 * You can match based on the key, or key and value. Removing based on key and 1897 * value, will keep from removing duplicate metadata with the same key. It also 1898 * allows removing all metadata matching key, if needed. 1899 * 1900 * @since 1.5.0 1901 * 1902 * @param int $post_id Post ID. 1903 * @param string $meta_key Metadata name. 1904 * @param mixed $meta_value Optional. Metadata value. Must be serializable if 1905 * non-scalar. Default empty. 1906 * @return bool True on success, false on failure. 1907 */ 1908 function delete_post_meta( $post_id, $meta_key, $meta_value = '' ) { 1909 // Make sure meta is added to the post, not a revision. 1910 if ( $the_post = wp_is_post_revision($post_id) ) 1911 $post_id = $the_post; 1912 1913 return delete_metadata('post', $post_id, $meta_key, $meta_value); 1914 } 1915 1916 /** 1917 * Retrieve post meta field for a post. 1918 * 1919 * @since 1.5.0 1920 * 1921 * @param int $post_id Post ID. 1922 * @param string $key Optional. The meta key to retrieve. By default, returns 1923 * data for all keys. Default empty. 1924 * @param bool $single Optional. Whether to return a single value. Default false. 1925 * @return mixed Will be an array if $single is false. Will be value of meta data 1926 * field if $single is true. 1927 */ 1928 function get_post_meta( $post_id, $key = '', $single = false ) { 1929 return get_metadata('post', $post_id, $key, $single); 1930 } 1931 1932 /** 1933 * Update post meta field based on post ID. 1934 * 1935 * Use the $prev_value parameter to differentiate between meta fields with the 1936 * same key and post ID. 1937 * 1938 * If the meta field for the post does not exist, it will be added. 1939 * 1940 * @since 1.5.0 1941 * 1942 * @param int $post_id Post ID. 1943 * @param string $meta_key Metadata key. 1944 * @param mixed $meta_value Metadata value. Must be serializable if non-scalar. 1945 * @param mixed $prev_value Optional. Previous value to check before removing. 1946 * Default empty. 1947 * @return int|bool Meta ID if the key didn't exist, true on successful update, 1948 * false on failure. 1949 */ 1950 function update_post_meta( $post_id, $meta_key, $meta_value, $prev_value = '' ) { 1889 1951 // make sure meta is added to the post, not a revision 1890 1952 if ( $the_post = wp_is_post_revision($post_id) ) 1891 1953 $post_id = $the_post; 1892 1954 1893 return add_metadata('post', $post_id, $meta_key, $meta_value, $unique);1894 }1895 1896 /**1897 * Remove metadata matching criteria from a post.1898 *1899 * You can match based on the key, or key and value. Removing based on key and1900 * value, will keep from removing duplicate metadata with the same key. It also1901 * allows removing all metadata matching key, if needed.1902 *1903 * @since 1.5.01904 * @link http://codex.wordpress.org/Function_Reference/delete_post_meta1905 *1906 * @param int $post_id post ID1907 * @param string $meta_key Metadata name.1908 * @param mixed $meta_value Optional. Metadata value. Must be serializable if non-scalar.1909 * @return bool True on success, false on failure.1910 */1911 function delete_post_meta($post_id, $meta_key, $meta_value = '') {1912 // make sure meta is added to the post, not a revision1913 if ( $the_post = wp_is_post_revision($post_id) )1914 $post_id = $the_post;1915 1916 return delete_metadata('post', $post_id, $meta_key, $meta_value);1917 }1918 1919 /**1920 * Retrieve post meta field for a post.1921 *1922 * @since 1.5.01923 * @link http://codex.wordpress.org/Function_Reference/get_post_meta1924 *1925 * @param int $post_id Post ID.1926 * @param string $key Optional. The meta key to retrieve. By default, returns1927 * data for all keys.1928 * @param bool $single Optional. Whether to return a single value. Default false.1929 * @return mixed Will be an array if $single is false. Will be value of meta data1930 * field if $single is true.1931 */1932 function get_post_meta($post_id, $key = '', $single = false) {1933 return get_metadata('post', $post_id, $key, $single);1934 }1935 1936 /**1937 * Update post meta field based on post ID.1938 *1939 * Use the $prev_value parameter to differentiate between meta fields with the1940 * same key and post ID.1941 *1942 * If the meta field for the post does not exist, it will be added.1943 *1944 * @since 1.5.01945 * @link http://codex.wordpress.org/Function_Reference/update_post_meta1946 *1947 * @param int $post_id Post ID.1948 * @param string $meta_key Metadata key.1949 * @param mixed $meta_value Metadata value. Must be serializable if non-scalar.1950 * @param mixed $prev_value Optional. Previous value to check before removing.1951 * @return int|bool Meta ID if the key didn't exist, true on successful update, false on failure.1952 */1953 function update_post_meta($post_id, $meta_key, $meta_value, $prev_value = '') {1954 // make sure meta is added to the post, not a revision1955 if ( $the_post = wp_is_post_revision($post_id) )1956 $post_id = $the_post;1957 1958 1955 return update_metadata('post', $post_id, $meta_key, $meta_value, $prev_value); 1959 1956 } … … 1965 1962 * 1966 1963 * @param string $post_meta_key Key to search for when deleting. 1967 * @return bool Whether the post meta key was deleted from the database 1968 */ 1969 function delete_post_meta_by_key( $post_meta_key) {1964 * @return bool Whether the post meta key was deleted from the database. 1965 */ 1966 function delete_post_meta_by_key( $post_meta_key ) { 1970 1967 return delete_metadata( 'post', null, $post_meta_key, '', true ); 1971 1968 } … … 1978 1975 * 1979 1976 * @since 1.2.0 1980 * @link http://codex.wordpress.org/Function_Reference/get_post_custom1981 1977 * 1982 1978 * @param int $post_id Optional. Post ID. Default is ID of the global $post. … … 1997 1993 * 1998 1994 * @since 1.2.0 1999 * @link http://codex.wordpress.org/Function_Reference/get_post_custom_keys2000 1995 * 2001 1996 * @param int $post_id Optional. Post ID. Default is ID of the global $post. 2002 * @return array|null Either array of the keys, or null if keys could not be retrieved. 1997 * @return array|null Either array of the keys, or null if keys could not be 1998 * retrieved. 2003 1999 */ 2004 2000 function get_post_custom_keys( $post_id = 0 ) { … … 2019 2015 * 2020 2016 * @since 1.2.0 2021 * @link http://codex.wordpress.org/Function_Reference/get_post_custom_values 2022 * 2023 * @param string $key Meta field key. 2024 * @param int $post_id Optional. Post ID. Default is ID of the global $post. 2017 * 2018 * @param string $key Optional. Meta field key. Default empty. 2019 * @param int $post_id Optional. Post ID. Default is ID of the global $post. 2025 2020 * @return array Meta field values. 2026 2021 */ … … 2065 2060 * Sanitize every post field. 2066 2061 * 2067 * If the context is 'raw', then the post object or array will get minimal santization of the int fields. 2062 * If the context is 'raw', then the post object or array will get minimal 2063 * sanitization of the integer fields. 2068 2064 * 2069 2065 * @since 2.3.0 2070 * @uses sanitize_post_field() Used to sanitize the fields. 2071 * 2072 * @param object|WP_Post|array $post The Post Object or Array 2073 * @param string $context Optional, default is 'display'. How to sanitize post fields. 2074 * @return object|WP_Post|array The now sanitized Post Object or Array (will be the same type as $post) 2075 */ 2076 function sanitize_post($post, $context = 'display') { 2066 * 2067 * @see sanitize_post_field() 2068 * 2069 * @param object|WP_Post|array $post The Post Object or Array 2070 * @param string $context Optional. How to sanitize post fields. 2071 * Accepts 'raw', 'edit', 'db', or 'display'. 2072 * Default 'display'. 2073 * @return object|WP_Post|array The now sanitized Post Object or Array (will be the 2074 * same type as $post). 2075 */ 2076 function sanitize_post( $post, $context = 'display' ) { 2077 2077 if ( is_object($post) ) { 2078 // Check if post already filtered for this context 2078 // Check if post already filtered for this context. 2079 2079 if ( isset($post->filter) && $context == $post->filter ) 2080 2080 return $post; … … 2085 2085 $post->filter = $context; 2086 2086 } else { 2087 // Check if post already filtered for this context 2087 // Check if post already filtered for this context. 2088 2088 if ( isset($post['filter']) && $context == $post['filter'] ) 2089 2089 return $post; … … 2100 2100 * Sanitize post field based on context. 2101 2101 * 2102 * Possible context values are: 'raw', 'edit', 'db', 'display', 'attribute' and 'js'. The2103 * ' display' context is used by default. 'attribute' and 'js' contexts are treated like 'display'2104 * when calling filters.2102 * Possible context values are: 'raw', 'edit', 'db', 'display', 'attribute' and 2103 * 'js'. The 'display' context is used by default. 'attribute' and 'js' contexts 2104 * are treated like 'display' when calling filters. 2105 2105 * 2106 2106 * @since 2.3.0 2107 2107 * 2108 * @param string $field The Post Object field name.2109 * @param mixed $valueThe Post Object value.2110 * @param int $post_id Post ID.2111 * @param string $context How to sanitize post fields. Looks for 'raw', 'edit', 'db', 'display',2112 * 'attribute' and 'js'.2108 * @param string $field The Post Object field name. 2109 * @param mixed $value The Post Object value. 2110 * @param int $post_id Post ID. 2111 * @param string $context How to sanitize post fields. Looks for 'raw', 'edit', 2112 * 'db', 'display', 'attribute' and 'js'. 2113 2113 * @return mixed Sanitized value. 2114 2114 */ … … 2118 2118 $value = (int) $value; 2119 2119 2120 // Fields which contain arrays of int s.2120 // Fields which contain arrays of integers. 2121 2121 $array_int_fields = array( 'ancestors' ); 2122 2122 if ( in_array($field, $array_int_fields) ) { … … 2142 2142 * Filter the value of a specific post field to edit. 2143 2143 * 2144 * The dynamic portion of the hook name, $field, refers to the post field name. 2144 * The dynamic portion of the hook name, $field, refers to the post 2145 * field name. 2145 2146 * 2146 2147 * @since 2.3.0 … … 2181 2182 * Filter the value of a specific post field before saving. 2182 2183 * 2183 * The dynamic portion of the hook name, $field, refers to the post field name. 2184 * The dynamic portion of the hook name, $field, refers to the post 2185 * field name. 2184 2186 * 2185 2187 * @since 2.3.0 … … 2206 2208 * Filter the value of a specific post field before saving. 2207 2209 * 2208 * The dynamic portion of the hook name, $field, refers to the post field name. 2210 * The dynamic portion of the hook name, $field, refers to the post 2211 * field name. 2209 2212 * 2210 2213 * @since 2.3.0 … … 2222 2225 * Filter the value of a specific post field for display. 2223 2226 * 2224 * The dynamic portion of the hook name, $field, refers to the post field name. 2227 * The dynamic portion of the hook name, $field, refers to the post 2228 * field name. 2225 2229 * 2226 2230 * @since 2.3.0 … … 2255 2259 * @param int $post_id Post ID. 2256 2260 */ 2257 function stick_post( $post_id) {2261 function stick_post( $post_id ) { 2258 2262 $stickies = get_option('sticky_posts'); 2259 2263 … … 2268 2272 2269 2273 /** 2270 * Un stick a post.2274 * Un-stick a post. 2271 2275 * 2272 2276 * Sticky posts should be displayed at the top of the front page. … … 2276 2280 * @param int $post_id Post ID. 2277 2281 */ 2278 function unstick_post( $post_id) {2282 function unstick_post( $post_id ) { 2279 2283 $stickies = get_option('sticky_posts'); 2280 2284 … … 2295 2299 2296 2300 /** 2297 * Return the cache key for wp_count_posts() based on the passed arguments 2301 * Return the cache key for wp_count_posts() based on the passed arguments. 2298 2302 * 2299 2303 * @since 3.9.0 2300 2304 * 2301 * @param string $type Optional. Post type to retrieve count 2302 * @param string $perm Optional. 'readable' or empty. 2305 * @param string $type Optional. Post type to retrieve count Default 'post'. 2306 * @param string $perm Optional. 'readable' or empty. Default empty. 2303 2307 * @return string The cache key. 2304 2308 */ … … 2325 2329 * private posts, it will display that for the user that is signed in. 2326 2330 * 2327 * @link http://codex.wordpress.org/Template_Tags/wp_count_posts2328 *2329 2331 * @since 2.5.0 2330 2332 * 2331 * @param string $type Optional. Post type to retrieve count 2332 * @param string $perm Optional. 'readable' or empty. 2333 * @return object Number of posts for each status 2333 * @param string $type Optional. Post type to retrieve count. Default 'post'. 2334 * @param string $perm Optional. 'readable' or empty. Default empty. 2335 * @return object Number of posts for each status. 2334 2336 */ 2335 2337 function wp_count_posts( $type = 'post', $perm = '' ) { … … 2388 2390 * @since 2.5.0 2389 2391 * 2390 * @param string|array $mime_type Optional. Array or comma-separated list of MIME patterns. 2392 * @param string|array $mime_type Optional. Array or comma-separated list of 2393 * MIME patterns. Default empty. 2391 2394 * @return object An object containing the attachment counts by mime type. 2392 2395 */ … … 2408 2411 * @since 3.7.0 2409 2412 * 2410 * @param object $counts An object containing the attachment counts by mime type. 2411 * @param string $mime_type The mime type pattern used to filter the attachments counted. 2413 * @param object $counts An object containing the attachment counts by 2414 * mime type. 2415 * @param string $mime_type The mime type pattern used to filter the attachments 2416 * counted. 2412 2417 */ 2413 2418 return apply_filters( 'wp_count_attachments', (object) $counts, $mime_type ); … … 2415 2420 2416 2421 /** 2417 * Get default post mime types 2422 * Get default post mime types. 2418 2423 * 2419 2424 * @since 2.9.0 2420 2425 * 2421 * @return array 2426 * @return array List of post mime types. 2422 2427 */ 2423 2428 function get_post_mime_types() { … … 2447 2452 * @since 2.5.0 2448 2453 * 2449 * @param string|array $wildcard_mime_types e.g. audio/mpeg or image (same as image/*) or2450 * flash (same as *flash*).2451 * @param string|array $real_mime_types post_mime_type values2452 * @return array array(wildcard=>array(real types)) 2454 * @param string|array $wildcard_mime_types Mime types, e.g. audio/mpeg or image (same as image/*) 2455 * or flash (same as *flash*). 2456 * @param string|array $real_mime_types Real post mime type values. 2457 * @return array array(wildcard=>array(real types)). 2453 2458 */ 2454 2459 function wp_match_mime_types( $wildcard_mime_types, $real_mime_types ) { … … 2491 2496 * @since 2.5.0 2492 2497 * 2493 * @param string|array $post_mime_types List of mime types or comma separated string of mime types. 2494 * @param string $table_alias Optional. Specify a table alias, if needed. 2498 * @param string|array $post_mime_types List of mime types or comma separated string 2499 * of mime types. 2500 * @param string $table_alias Optional. Specify a table alias, if needed. 2501 * Default empty. 2495 2502 * @return string The SQL AND clause for mime searching. 2496 2503 */ 2497 function wp_post_mime_type_where( $post_mime_types, $table_alias = '') {2504 function wp_post_mime_type_where( $post_mime_types, $table_alias = '' ) { 2498 2505 $where = ''; 2499 2506 $wildcards = array('', '%', '%/%'); … … 2533 2540 2534 2541 /** 2535 * Trashes or deletes a post or page. 2536 * 2537 * When the post and page is permanently deleted, everything that is tied to it is deleted also. 2538 * This includes comments, post meta fields, and terms associated with the post. 2539 * 2540 * The post or page is moved to trash instead of permanently deleted unless trash is 2541 * disabled, item is already in the trash, or $force_delete is true. 2542 * Trash or delete a post or page. 2543 * 2544 * When the post and page is permanently deleted, everything that is tied to 2545 * it is deleted also. This includes comments, post meta fields, and terms 2546 * associated with the post. 2547 * 2548 * The post or page is moved to trash instead of permanently deleted unless 2549 * trash is disabled, item is already in the trash, or $force_delete is true. 2542 2550 * 2543 2551 * @since 1.0.0 2544 2552 * 2545 * @uses wp_delete_attachment() if post type is 'attachment'. 2546 * @uses wp_trash_post() if item should be trashed. 2547 * 2548 * @param int $postid Post ID. 2549 * @param bool $force_delete Whether to bypass trash and force deletion. Defaults to false. 2550 * @return mixed False on failure 2553 * @global wpdb $wpdb WordPress database access abstraction object. 2554 * @see wp_delete_attachment() 2555 * @see wp_trash_post() 2556 * 2557 * @param int $postid Optional. Post ID. Default 0. 2558 * @param bool $force_delete Optional. Whether to bypass trash and force deletion. 2559 * Default false. 2560 * @return array|bool|WP_Post False on failure. 2551 2561 */ 2552 2562 function wp_delete_post( $postid = 0, $force_delete = false ) { … … 2652 2662 2653 2663 /** 2654 * Reset s the page_on_front, show_on_front, and page_for_post settings when a2655 * linked page is deleted or trashed.2664 * Reset the page_on_front, show_on_front, and page_for_post settings when 2665 * a linked page is deleted or trashed. 2656 2666 * 2657 2667 * Also ensures the post is no longer sticky. 2658 2668 * 2669 * @since 3.7.0 2659 2670 * @access private 2660 * @since 3.7.02661 * @param $post_id2671 * 2672 * @param int $post_id Post ID. 2662 2673 */ 2663 2674 function _reset_front_page_settings_for_post( $post_id ) { … … 2680 2691 2681 2692 /** 2682 * Move sa post or page to the Trash2693 * Move a post or page to the Trash 2683 2694 * 2684 2695 * If trash is disabled, the post or page is permanently deleted. … … 2686 2697 * @since 2.9.0 2687 2698 * 2688 * @ uses wp_delete_post() if trash is disabled2689 * 2690 * @param int $post_id Optional. Post ID. Default is ID of the global `$post`2699 * @see wp_delete_post() 2700 * 2701 * @param int $post_id Optional. Post ID. Default is ID of the global $post 2691 2702 * if EMPTY_TRASH_DAYS equals true. 2692 2703 * @return bool|array Post data array, otherwise false. 2693 2704 */ 2694 function wp_trash_post( $post_id = 0) {2705 function wp_trash_post( $post_id = 0 ) { 2695 2706 if ( !EMPTY_TRASH_DAYS ) 2696 2707 return wp_delete_post($post_id, true); … … 2732 2743 2733 2744 /** 2734 * Restore s a post or page from the Trash2745 * Restore a post or page from the Trash. 2735 2746 * 2736 2747 * @since 2.9.0 2737 2748 * 2738 2749 * @param int $post_id Optional. Post ID. Default is ID of the global $post. 2739 * @return mixed False on failure2750 * @return WP_Post|bool WP_Post object. False on failure. 2740 2751 */ 2741 2752 function wp_untrash_post( $post_id = 0 ) { … … 2779 2790 2780 2791 /** 2781 * Moves comments for a post to the trash 2792 * Moves comments for a post to the trash. 2782 2793 * 2783 2794 * @since 2.9.0 2784 2795 * 2785 * @param int|WP_Post $post Optional. Post ID or post object. 2786 * @return mixed False on failure 2787 */ 2788 function wp_trash_post_comments($post = null) { 2796 * @global wpdb $wpdb WordPress database access abstraction object. 2797 * 2798 * @param int|WP_Post $post Optional. Post ID or post object. Defaults to global $post. 2799 * @return mixed False on failure. 2800 */ 2801 function wp_trash_post_comments( $post = null ) { 2789 2802 global $wpdb; 2790 2803 … … 2833 2846 2834 2847 /** 2835 * Restore comments for a post from the trash 2848 * Restore comments for a post from the trash. 2836 2849 * 2837 2850 * @since 2.9.0 2838 2851 * 2839 * @param int|WP_Post $post Optional. Post ID or post object. 2840 * @return mixed False on failure 2841 */ 2842 function wp_untrash_post_comments( $post = null) {2852 * @param int|WP_Post $post Optional. Post ID or post object. Defaults to global $post. 2853 * @return mixed False on failure. 2854 */ 2855 function wp_untrash_post_comments( $post = null ) { 2843 2856 global $wpdb; 2844 2857 … … 2898 2911 * @since 2.1.0 2899 2912 * 2900 * @uses wp_get_object_terms() Retrieves the categories. Args details can be found here. 2901 * 2902 * @param int $post_id Optional. The Post ID. Does not default to the ID of the global $post. 2903 * @param array $args Optional. Overwrite the defaults. 2904 * @return array 2913 * @see wp_get_object_terms() 2914 * 2915 * @param int $post_id Optional. The Post ID. Does not default to the ID of the 2916 * global $post. Default 0. 2917 * @param array $args Optional. Category arguments. Default empty. 2918 * @return array List of categories. 2905 2919 */ 2906 2920 function wp_get_post_categories( $post_id = 0, $args = array() ) { … … 2923 2937 * @since 2.3.0 2924 2938 * 2925 * @uses wp_get_object_terms() Gets the tags for returning. Args can be found here 2926 * 2927 * @param int $post_id Optional. The Post ID. Does not default to the ID of the global $post. 2939 * @uses wp_get_object_terms() 2940 * 2941 * @param int $post_id Optional. The Post ID. Does not default to the ID of the 2942 * global $post. Defualt 0. 2928 2943 * @param array $args Optional. Overwrite the defaults 2929 2944 * @return array List of post tags. … … 2942 2957 * @since 2.8.0 2943 2958 * 2944 * @uses wp_get_object_terms() Gets the tags for returning. Args can be found here 2945 * 2946 * @param int $post_id Optional. The Post ID. Does not default to the ID of the global $post. 2947 * @param string $taxonomy The taxonomy for which to retrieve terms. Defaults to post_tag. 2948 * @param array $args Optional. {@link wp_get_object_terms()} arguments. 2959 * @uses wp_get_object_terms() 2960 * 2961 * @param int $post_id Optional. The Post ID. Does not default to the ID of the 2962 * global $post. Default 0. 2963 * @param string $taxonomy Optional. The taxonomy for which to retrieve terms. Default 'post_tag'. 2964 * @param array $args Optional. {@link wp_get_object_terms()} arguments. Default empty array. 2949 2965 * @return array List of post tags. 2950 2966 */ … … 2961 2977 2962 2978 /** 2963 * Retrieve number of recent posts.2979 * Retrieve a number of recent posts. 2964 2980 * 2965 2981 * @since 1.0.0 2966 * @uses wp_parse_args()2967 * @ usesget_posts()2968 * 2969 * @param string $deprecated Deprecated.2970 * @param array $args Optional. Overrides defaults.2971 * @param string $output Optional.2972 * @return unknown.2982 * 2983 * @see get_posts() 2984 * 2985 * @param string $deprecated Not used. 2986 * @param array $args Optional. Arguments to retrieve posts. Default empty array. 2987 * @param string $output Optional. Type of output. Accepts ARRAY_A or ''. Default ARRAY_A. 2988 * @return array|bool Associative array if $output equals ARRAY_A, array or false if no results. 2973 2989 */ 2974 2990 function wp_get_recent_posts( $args = array(), $output = ARRAY_A ) { … … 3014 3030 * setting the value for 'comment_status' key. 3015 3031 * 3016 * @global wpdb $wpdb WordPress database abstraction object.3017 *3018 3032 * @since 1.0.0 3033 * 3034 * @see sanitize_post() 3035 * @global wpdb $wpdb WordPress database abstraction object. 3019 3036 * 3020 3037 * @param array $postarr { 3021 3038 * An array of elements that make up a post to update or insert. 3022 3039 * 3023 * @type int $ID The post ID. If equal to something other than 0, the post with that ID will3024 * be updated. Default 0.3040 * @type int $ID The post ID. If equal to something other than 0, 3041 * the post with that ID will be updated. Default 0. 3025 3042 * @type string $post_status The post status. Default 'draft'. 3026 3043 * @type string $post_type The post type. Default 'post'. 3027 * @type int $post_author The ID of the user who added the post. Default the current user ID. 3028 * @type bool $ping_status Whether the post can accept pings. Default value of 'default_ping_status' option. 3044 * @type int $post_author The ID of the user who added the post. Default is 3045 * the current user ID. 3046 * @type bool $ping_status Whether the post can accept pings. Default is the 3047 * value of 'default_ping_status' option. 3029 3048 * @type int $post_parent Set this for the post it belongs to, if any. Default 0. 3030 3049 * @type int $menu_order The order it is displayed. Default 0. 3031 * @type string $to_ping Space or carriage return-separated list of URLs to ping. Default empty string. 3032 * @type string $pinged Space or carriage return-separated list of URLs that have been pinged. 3050 * @type string $to_ping Space or carriage return-separated list of URLs to ping. 3033 3051 * Default empty string. 3052 * @type string $pinged Space or carriage return-separated list of URLs that have 3053 * been pinged. Default empty string. 3034 3054 * @type string $post_password The password to access the post. Default empty string. 3035 3055 * @type string $guid' Global Unique ID for referencing the post. … … 3037 3057 * @type string $post_excerpt The post excerpt. Default empty string. 3038 3058 * } 3039 * @param bool $wp_error Optional. Allow return of WP_Error on failure.3059 * @param bool $wp_error Optional. Whether to allow return of WP_Error on failure. Default false. 3040 3060 * @return int|WP_Error The post ID on success. The value 0 or WP_Error on failure. 3041 3061 */ … … 3065 3085 $update = true; 3066 3086 3067 // Get the post ID and GUID 3087 // Get the post ID and GUID. 3068 3088 $post_ID = $postarr['ID']; 3069 3089 $post_before = get_post( $post_ID ); … … 3126 3146 3127 3147 if ( ! empty( $postarr['post_category'] ) ) { 3128 $post_category = array_filter( $postarr['post_category'] ); // Filter out empty terms 3148 // Filter out empty terms. 3149 $post_category = array_filter( $postarr['post_category'] ); 3129 3150 } 3130 3151 … … 3139 3160 } 3140 3161 3141 // Don't allow contributors to set the post slug for pending review posts 3162 // Don't allow contributors to set the post slug for pending review posts. 3142 3163 if ( 'pending' == $post_status && !current_user_can( 'publish_posts' ) ) { 3143 3164 $post_name = ''; 3144 3165 } 3145 3166 3146 // Create a valid post name. Drafts and pending posts are allowed to have an empty 3147 // post name. 3167 /* 3168 * Create a valid post name. Drafts and pending posts are allowed to have 3169 * an empty post name. 3170 */ 3148 3171 if ( empty($post_name) ) { 3149 3172 if ( !in_array( $post_status, array( 'draft', 'pending', 'auto-draft' ) ) ) { … … 3162 3185 } 3163 3186 3164 // If the post date is empty (due to having been new or a draft) and status is not 'draft' or 'pending', set date to now 3187 /* 3188 * If the post date is empty (due to having been new or a draft) and status 3189 * is not 'draft' or 'pending', set date to now. 3190 */ 3165 3191 if ( empty( $postarr['post_date'] ) || '0000-00-00 00:00:00' == $postarr['post_date'] ) { 3166 3192 $post_date = current_time( 'mysql' ); … … 3169 3195 } 3170 3196 3171 // validate the date3197 // Validate the date. 3172 3198 $mm = substr( $post_date, 5, 2 ); 3173 3199 $jj = substr( $post_date, 8, 2 ); … … 3224 3250 } 3225 3251 3226 // these variables are needed by compact() later3252 // These variables are needed by compact() later. 3227 3253 $post_content_filtered = $postarr['post_content_filtered']; 3228 3254 $post_author = empty( $postarr['post_author'] ) ? $user_id : $postarr['post_author']; … … 3232 3258 $import_id = isset( $postarr['import_id'] ) ? $postarr['import_id'] : 0; 3233 3259 3234 // The 'wp_insert_post_parent' filter expects all variables to be present. 3235 // Previously, these variables would have already been extracted 3260 /* 3261 * The 'wp_insert_post_parent' filter expects all variables to be present. 3262 * Previously, these variables would have already been extracted 3263 */ 3236 3264 if ( isset( $postarr['menu_order'] ) ) { 3237 3265 $menu_order = (int) $postarr['menu_order']; … … 3265 3293 $post_name = wp_unique_post_slug( $post_name, $post_ID, $post_status, $post_type, $post_parent ); 3266 3294 3267 // don't unslash3295 // Don't unslash. 3268 3296 $post_mime_type = isset( $postarr['post_mime_type'] ) ? $postarr['post_mime_type'] : ''; 3269 3297 3270 // expected_slashed (everything!)3298 // Expected_slashed (everything!). 3271 3299 $data = compact( 'post_author', 'post_date', 'post_date_gmt', 'post_content', 'post_content_filtered', 'post_title', 'post_excerpt', 'post_status', 'post_type', 'comment_status', 'ping_status', 'post_password', 'post_name', 'to_ping', 'pinged', 'post_modified', 'post_modified_gmt', 'post_parent', 'menu_order', 'post_mime_type', 'guid' ); 3272 3300 … … 3313 3341 } 3314 3342 } else { 3315 // If there is a suggested ID, use it if not already present 3343 // If there is a suggested ID, use it if not already present. 3316 3344 if ( ! empty( $import_id ) ) { 3317 3345 $import_id = (int) $import_id; … … 3329 3357 $post_ID = (int) $wpdb->insert_id; 3330 3358 3331 // use the newly generated $post_ID3359 // Use the newly generated $post_ID. 3332 3360 $where = array( 'ID' => $post_ID ); 3333 3361 } … … 3346 3374 } 3347 3375 3348 // new-style support for all custom taxonomies3376 // New-style support for all custom taxonomies. 3349 3377 if ( ! empty( $postarr['tax_input'] ) ) { 3350 3378 foreach ( $postarr['tax_input'] as $taxonomy => $tags ) { 3351 3379 $taxonomy_obj = get_taxonomy($taxonomy); 3352 if ( is_array( $tags ) ) { // array = hierarchical, string = non-hierarchical. 3380 // array = hierarchical, string = non-hierarchical. 3381 if ( is_array( $tags ) ) { 3353 3382 $tags = array_filter($tags); 3354 3383 } … … 3361 3390 $current_guid = get_post_field( 'guid', $post_ID ); 3362 3391 3363 // Set GUID 3392 // Set GUID. 3364 3393 if ( ! $update && '' == $current_guid ) { 3365 3394 $wpdb->update( $wpdb->posts, array( 'guid' => get_permalink( $post_ID ) ), $where ); … … 3491 3520 * @since 1.0.0 3492 3521 * 3493 * @param array|object $postarr Post data. Arrays are expected to be escaped, objects are not. 3494 * @param bool $wp_error Optional. Allow return of WP_Error on failure. 3522 * @param array|object $postarr Optional. Post data. Arrays are expected to be escaped, 3523 * objects are not. Default array. 3524 * @param bool $wp_error Optional. Allow return of WP_Error on failure. Default false. 3495 3525 * @return int|WP_Error The value 0 or WP_Error on failure. The post ID on success. 3496 3526 */ … … 3502 3532 } 3503 3533 3504 // First, get all of the original fields 3534 // First, get all of the original fields. 3505 3535 $post = get_post($postarr['ID'], ARRAY_A); 3506 3536 … … 3521 3551 $post_cats = $post['post_category']; 3522 3552 3523 // Drafts shouldn't be assigned a date unless explicitly done so by the user 3553 // Drafts shouldn't be assigned a date unless explicitly done so by the user. 3524 3554 if ( isset( $post['post_status'] ) && in_array($post['post_status'], array('draft', 'pending', 'auto-draft')) && empty($postarr['edit_date']) && 3525 3555 ('0000-00-00 00:00:00' == $post['post_date_gmt']) ) … … 3546 3576 * 3547 3577 * @since 2.1.0 3548 * @uses $wpdb 3578 * 3579 * @global wpdb $wpdb WordPress database abstraction object. 3549 3580 * 3550 3581 * @param int|WP_Post $post Post ID or post object. … … 3569 3600 /** This action is documented in wp-includes/post.php */ 3570 3601 do_action( 'edit_post', $post->ID, $post ); 3602 3571 3603 /** This action is documented in wp-includes/post.php */ 3572 3604 do_action( "save_post_{$post->post_type}", $post->ID, $post, true ); 3605 3573 3606 /** This action is documented in wp-includes/post.php */ 3574 3607 do_action( 'save_post', $post->ID, $post, true ); 3608 3575 3609 /** This action is documented in wp-includes/post.php */ 3576 3610 do_action( 'wp_insert_post', $post->ID, $post, true ); … … 3586 3620 * 3587 3621 * @param int|WP_Post $post_id Post ID or post object. 3588 * @return null Nothing is returned. Which can mean that no action is required or post was published. 3589 */ 3590 function check_and_publish_future_post($post_id) { 3622 * @return null Nothing is returned. Which can mean that no action is required 3623 * or post was published. 3624 */ 3625 function check_and_publish_future_post( $post_id ) { 3591 3626 3592 3627 $post = get_post($post_id); … … 3614 3649 * @since 2.8.0 3615 3650 * 3616 * @global wpdb $wpdb 3651 * @global wpdb $wpdb WordPress database abstraction object. 3617 3652 * @global WP_Rewrite $wp_rewrite 3618 * @param string $slug the desired slug (post_name) 3619 * @param integer $post_ID 3620 * @param string $post_status no uniqueness checks are made if the post is still draft or pending 3621 * @param string $post_type 3622 * @param integer $post_parent 3623 * @return string unique slug for the post, based on $post_name (with a -1, -2, etc. suffix) 3653 * 3654 * @param string $slug The desired slug (post_name). 3655 * @param int $post_ID Post ID. 3656 * @param string $post_status No uniqueness checks are made if the post is still draft or pending. 3657 * @param string $post_type Post type. 3658 * @param int $post_parent Post parent ID. 3659 * @return string Unique slug for the post, based on $post_name (with a -1, -2, etc. suffix) 3624 3660 */ 3625 3661 function wp_unique_post_slug( $slug, $post_ID, $post_status, $post_type, $post_parent ) { … … 3729 3765 3730 3766 /** 3731 * Truncate sa post slug.3767 * Truncate a post slug. 3732 3768 * 3733 3769 * @since 3.6.0 3734 3770 * @access private 3735 * @uses utf8_uri_encode() Makes sure UTF-8 characters are properly cut and encoded. 3736 * 3737 * @param string $slug The slug to truncate. 3738 * @param int $length Max length of the slug. 3771 * 3772 * @see utf8_uri_encode() 3773 * 3774 * @param string $slug The slug to truncate. 3775 * @param int $length Optional. Max length of the slug. Default 200 (characters). 3739 3776 * @return string The truncated slug. 3740 3777 */ … … 3752 3789 3753 3790 /** 3754 * Add stags to a post.3755 * 3756 * @ uses wp_set_post_tags() Same first two parameters, but the last parameter is always set to true.3791 * Add tags to a post. 3792 * 3793 * @see wp_set_post_tags() 3757 3794 * 3758 3795 * @since 2.3.0 3759 3796 * 3760 * @param int $post_id Optional. The Post ID. Does not default to the ID of the global $post. 3761 * @param string $tags The tags to set for the post, separated by commas. 3762 * @return bool|null Will return false if $post_id is not an integer or is 0. Will return null otherwise 3797 * @param int $post_id Optional. The Post ID. Does not default to the ID of the global $post. 3798 * Default 0. 3799 * @param string $tags Optional. The tags to set for the post, separated by commas. Default empty. 3800 * @return bool|null Will return false if $post_id is not an integer or is 0. Will return null otherwise. 3763 3801 */ 3764 3802 function wp_add_post_tags( $post_id = 0, $tags = '' ) { … … 3770 3808 * 3771 3809 * @since 2.3.0 3772 * @uses wp_set_object_terms() Sets the tags for the post. 3773 * 3774 * @param int $post_id Optional. The Post ID. Does not default to the ID of the global $post. 3775 * @param string $tags The tags to set for the post, separated by commas. 3776 * @param bool $append If true, don't delete existing tags, just add on. If false, replace the tags with the new tags. 3810 * 3811 * @see wp_set_object_terms() 3812 * 3813 * @param int $post_id Optional. The Post ID. Does not default to the ID of the global $post. 3814 * @param string $tags Optional. The tags to set for the post, separated by commas. 3815 * Default empty. 3816 * @param bool $append Optional. If true, don't delete existing tags, just add on. If false, 3817 * replace the tags with the new tags. Default false. 3777 3818 * @return mixed Array of affected term IDs. WP_Error or false on failure. 3778 3819 */ … … 3785 3826 * 3786 3827 * @since 2.8.0 3787 * @uses wp_set_object_terms() Sets the tags for the post. 3828 * 3829 * @see wp_set_object_terms() 3788 3830 * 3789 3831 * @param int $post_id Optional. The Post ID. Does not default to the ID of the global $post. 3790 * @param string $tags The tags to set for the post, separated by commas. 3791 * @param string $taxonomy Taxonomy name. Defaults to 'post_tag'. 3792 * @param bool $append If true, don't delete existing tags, just add on. If false, replace the tags with the new tags. 3832 * @param string $tags Optional. The tags to set for the post, separated by commas. Default empty. 3833 * @param string $taxonomy Optional. Taxonomy name. Default 'post_tag'. 3834 * @param bool $append Optional. If true, don't delete existing tags, just add on. If false, 3835 * replace the tags with the new tags. Default false. 3793 3836 * @return mixed Array of affected term IDs. WP_Error or false on failure. 3794 3837 */ … … 3809 3852 } 3810 3853 3811 // Hierarchical taxonomies must always pass IDs rather than names so that children with the same 3812 // names but different parents aren't confused. 3854 /* 3855 * Hierarchical taxonomies must always pass IDs rather than names so that 3856 * children with the same names but different parents aren't confused. 3857 */ 3813 3858 if ( is_taxonomy_hierarchical( $taxonomy ) ) { 3814 3859 $tags = array_unique( array_map( 'intval', $tags ) ); … … 3826 3871 * @since 2.1.0 3827 3872 * 3828 * @param int $post_ID Optional. The Post ID. Does not default to the ID of the global $post. 3873 * @param int $post_ID Optional. The Post ID. Does not default to the ID 3874 * of the global $post. Default 0. 3829 3875 * @param array|int $post_categories Optional. List of categories or ID of category. 3830 * @param bool $append If true, don't delete existing categories, just add on. If false, replace the categories with the new categories. 3876 * Default empty array. 3877 * @param bool $append If true, don't delete existing categories, just add on. 3878 * If false, replace the categories with the new categories. 3831 3879 * @return bool|mixed 3832 3880 */ … … 3867 3915 * @since 2.3.0 3868 3916 * 3869 * @link http://codex.wordpress.org/Post_Status_Transitions3870 *3871 3917 * @param string $new_status Transition to this post status. 3872 3918 * @param string $old_status Previous post status. 3873 3919 * @param object $post Post data. 3874 3920 */ 3875 function wp_transition_post_status( $new_status, $old_status, $post) {3921 function wp_transition_post_status( $new_status, $old_status, $post ) { 3876 3922 /** 3877 3923 * Fires when a post is transitioned from one status to another. … … 3916 3962 3917 3963 /** 3918 * Add a URL to those already p ung.3964 * Add a URL to those already pinged. 3919 3965 * 3920 3966 * @since 1.5.0 3921 * @uses $wpdb 3922 * 3923 * @param int $post_id Post ID. 3924 * @param string $uri Ping URI. 3967 * 3968 * @global wpdb $wpdb WordPress database abstraction object. 3969 * 3970 * @param int $post_id Post ID. 3971 * @param string $uri Ping URI. 3925 3972 * @return int How many rows were updated. 3926 3973 */ 3927 function add_ping( $post_id, $uri) {3974 function add_ping( $post_id, $uri ) { 3928 3975 global $wpdb; 3929 3976 $pung = $wpdb->get_var( $wpdb->prepare( "SELECT pinged FROM $wpdb->posts WHERE ID = %d", $post_id )); … … 3953 4000 * 3954 4001 * @param int $post_id Post ID. 3955 * @return array List of enclosures 3956 */ 3957 function get_enclosed( $post_id) {4002 * @return array List of enclosures. 4003 */ 4004 function get_enclosed( $post_id ) { 3958 4005 $custom_fields = get_post_custom( $post_id ); 3959 4006 $pung = array(); … … 3986 4033 * 3987 4034 * @since 1.5.0 3988 * @uses $wpdb 4035 * 4036 * @global wpdb $wpdb WordPress database abstraction object. 3989 4037 * 3990 4038 * @param int $post_id Post ID. 3991 4039 * @return array 3992 4040 */ 3993 function get_pung( $post_id) {4041 function get_pung( $post_id ) { 3994 4042 global $wpdb; 3995 4043 $pung = $wpdb->get_var( $wpdb->prepare( "SELECT pinged FROM $wpdb->posts WHERE ID = %d", $post_id )); … … 4012 4060 * 4013 4061 * @since 1.5.0 4014 * @uses $wpdb 4062 * 4063 * @global wpdb $wpdb WordPress database abstraction object. 4015 4064 * 4016 4065 * @param int $post_id Post ID 4017 4066 * @return array 4018 4067 */ 4019 function get_to_ping( $post_id) {4068 function get_to_ping( $post_id ) { 4020 4069 global $wpdb; 4021 4070 $to_ping = $wpdb->get_var( $wpdb->prepare( "SELECT to_ping FROM $wpdb->posts WHERE ID = %d", $post_id )); … … 4039 4088 * @since 1.0.0 4040 4089 * 4041 * @param string $tb_list Comma separated list of URLs 4042 * @param int $post_id Post ID4090 * @param string $tb_list Comma separated list of URLs. 4091 * @param int $post_id Post ID. 4043 4092 */ 4044 4093 function trackback_url_list( $tb_list, $post_id ) { … … 4070 4119 * 4071 4120 * @since 2.0.0 4072 * @uses $wpdb 4121 * 4122 * @global wpdb $wpdb WordPress database abstraction object. 4073 4123 * 4074 4124 * @return array List of page IDs. … … 4092 4142 * 4093 4143 * @since 1.5.1 4094 * @deprecated 3.5.0 4095 * 4096 * @param mixed $page Page object or page ID. Passed by reference. 4097 * @param string $output What to output. OBJECT, ARRAY_A, or ARRAY_N. 4098 * @param string $filter How the return value should be filtered. 4099 * @return WP_Post|null WP_Post on success or null on failure 4144 * @deprecated 3.5.0 Use get_post() 4145 * 4146 * @param mixed $page Page object or page ID. Passed by reference. 4147 * @param string $output Optional. What to output. Accepts OBJECT, ARRAY_A, or ARRAY_N. 4148 * Default OBJECT. 4149 * @param string $filter Optional. How the return value should be filtered. Accepts 'raw', 4150 * 'edit', 'db', 'display'. Default 'raw'. 4151 * @return WP_Post|null WP_Post on success or null on failure. 4100 4152 */ 4101 4153 function get_page( $page, $output = OBJECT, $filter = 'raw') { … … 4107 4159 * 4108 4160 * @since 2.1.0 4109 * @uses $wpdb 4110 * 4111 * @param string $page_path Page path 4112 * @param string $output Optional. Output type. OBJECT, ARRAY_N, or ARRAY_A. Default OBJECT. 4113 * @param string|array $post_type Optional. Post type or array of post types. Default page. 4114 * @return WP_Post|null WP_Post on success or null on failure 4161 * 4162 * @global wpdb $wpdb WordPress database abstraction object. 4163 * 4164 * @param string $page_path Page path. 4165 * @param string $output Optional. Output type. Accepts OBJECT, ARRAY_N, or ARRAY_A. 4166 * Default OBJECT. 4167 * @param string|array $post_type Optional. Post type or array of post types. Default 'page'. 4168 * @return WP_Post|null WP_Post on success or null on failure. 4115 4169 */ 4116 4170 function get_page_by_path( $page_path, $output = OBJECT, $post_type = 'page' ) { … … 4176 4230 * 4177 4231 * @since 2.1.0 4178 * @uses $wpdb 4179 * 4180 * @param string $page_title Page title 4181 * @param string $output Optional. Output type. OBJECT, ARRAY_N, or ARRAY_A. Default OBJECT. 4182 * @param string|array $post_type Optional. Post type or array of post types. Default page. 4232 * 4233 * @global wpdb $wpdb WordPress database abstraction object. 4234 * 4235 * @param string $page_title Page title 4236 * @param string $output Optional. Output type. OBJECT, ARRAY_N, or ARRAY_A. 4237 * Default OBJECT. 4238 * @param string|array $post_type Optional. Post type or array of post types. Default 'page'. 4183 4239 * @return WP_Post|null WP_Post on success or null on failure 4184 4240 */ … … 4221 4277 * @since 1.5.1 4222 4278 * 4223 * @param int $page_id Page ID.4224 * @param array $pages List of pages' objects.4225 * @return array 4279 * @param int $page_id Page ID. 4280 * @param array $pages List of pages' objects. 4281 * @return array List of page children. 4226 4282 */ 4227 4283 function get_page_children($page_id, $pages) { … … 4245 4301 * @since 2.0.0 4246 4302 * 4247 * @param array $pages Posts array.4248 * @param int $page_id Parent page ID.4303 * @param array $pages Posts array, passed by reference. 4304 * @param int $page_id Optional. Parent page ID. Default 0. 4249 4305 * @return array A list arranged by hierarchy. Children immediately follow their parents. 4250 4306 */ … … 4268 4324 4269 4325 /** 4270 * function to traverse and return all the nested children post names of a root page. 4326 * Traverse and return all the nested children post names of a root page. 4327 * 4271 4328 * $children contains parent-children relations 4272 4329 * 4273 4330 * @since 2.9.0 4331 * 4332 * @see _page_traverse_name() 4333 * 4334 * @param int $page_id Page ID. 4335 * @param array &$children Parent-children relations, passed by reference. 4336 * @param array &$result Result, passed by reference. 4274 4337 */ 4275 4338 function _page_traverse_name( $page_id, &$children, &$result ){ … … 4283 4346 4284 4347 /** 4285 * Build sURI for a page.4348 * Build URI for a page. 4286 4349 * 4287 4350 * Sub pages will be in the "directory" under the parent page post name. … … 4289 4352 * @since 1.5.0 4290 4353 * 4291 * @param mixed$page Page object or page ID.4354 * @param WP_Post|object|int $page Page object or page ID. 4292 4355 * @return string|false Page URI, false on error. 4293 4356 */ … … 4310 4373 * Retrieve a list of pages. 4311 4374 * 4312 * @global wpdb $wpdb WordPress database abstraction object 4375 * @global wpdb $wpdb WordPress database abstraction object. 4313 4376 * 4314 4377 * @since 1.5.0 … … 5152 5215 * Retrieve the post SQL based on capability, author, and type. 5153 5216 * 5154 * @see get_private_posts_cap_sql() for full description.5217 * @see get_private_posts_cap_sql() 5155 5218 * 5156 5219 * @since 3.0.0
Note: See TracChangeset
for help on using the changeset viewer.