From 6e3a5acd3bc693dc540e686c435b4963d2dc3dbe Mon Sep 17 00:00:00 2001 From: ryan Date: Thu, 4 Sep 2008 19:19:32 +0000 Subject: [PATCH] phpdoc for query.php. Props jacobsantos. fixes #7663 git-svn-id: http://svn.automattic.com/wordpress/trunk@8807 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/query.php | 905 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 881 insertions(+), 24 deletions(-) diff --git a/wp-includes/query.php b/wp-includes/query.php index 7fa51bb740..631830832d 100644 --- a/wp-includes/query.php +++ b/wp-includes/query.php @@ -1,27 +1,77 @@ get($var); } +/** + * Set query variable. + * + * @see WP_Query::set() + * @since 2.2.0 + * @uses $wp_query + * + * @param string $var Query variable key. + * @param mixed $value + * @return null + */ function set_query_var($var, $value) { global $wp_query; return $wp_query->set($var, $value); } +/** + * Setup The Loop with query parameters. + * + * This will override the current WordPress Loop and shouldn't be used more than + * once. This must not be used within the WordPress Loop. + * + * @since 1.5.0 + * @uses $wp_query + * + * @param string $query + * @return array List of posts + */ function &query_posts($query) { unset($GLOBALS['wp_query']); $GLOBALS['wp_query'] =& new WP_Query(); return $GLOBALS['wp_query']->query($query); } +/** + * Destroy the previous query and setup a new query. + * + * This should be used after {@link query_posts()} and before another {@link + * query_posts()}. This will remove obscure bugs that occur when the previous + * wp_query object is not destroyed properly before another is setup. + * + * @since 2.3.0 + * @uses $wp_query + */ function wp_reset_query() { unset($GLOBALS['wp_query']); $GLOBALS['wp_query'] =& $GLOBALS['wp_the_query']; @@ -36,24 +86,70 @@ function wp_reset_query() { * Query type checks. */ +/** + * Whether the current request is in WordPress admin Panel + * + * Does not inform on whether the user is an admin! Use capability checks to + * tell if the user should be accessing a section or not. + * + * @since 1.5.1 + * + * @return bool True if inside WordPress administration pages. + */ function is_admin () { if ( defined('WP_ADMIN') ) return WP_ADMIN; return false; } +/** + * Is query requesting an archive page. + * + * @since 1.5.0 + * @uses $wp_query + * + * @return bool True if page is archive. + */ function is_archive () { global $wp_query; return $wp_query->is_archive; } +/** + * Is query requesting an attachment page. + * + * @since 2.0.0 + * @uses $wp_query + * + * @return bool True if page is attachment. + */ function is_attachment () { global $wp_query; return $wp_query->is_attachment; } +/** + * Is query requesting an author page. + * + * If the $author parameter is specified then the check will be expanded to + * include whether the queried author matches the one given in the parameter. + * You can match against integers and against strings. + * + * If matching against an integer, the ID should be used of the author for the + * test. If the $author is an ID and matches the author page user ID, then + * 'true' will be returned. + * + * If matching against strings, then the test will be matched against both the + * nickname and user nicename and will return true on success. + * + * @since 1.5.0 + * @uses $wp_query + * + * @param string|int $author Optional. Is current page this author. + * @return bool True if page is author or $author (if set). + */ function is_author ($author = '') { global $wp_query; @@ -77,6 +173,18 @@ function is_author ($author = '') { return false; } +/** + * Whether current page query contains a category name or given category name. + * + * The category list can contain category IDs, names, or category slugs. If any + * of them are part of the query, then it will return true. + * + * @since 1.5.0 + * @uses $wp_query + * + * @param string|array $category Optional. + * @return bool + */ function is_category ($category = '') { global $wp_query; @@ -100,6 +208,15 @@ function is_category ($category = '') { return false; } +/** + * Whether the current page query has the given tag slug or contains tag. + * + * @since 2.3.0 + * @uses $wp_query + * + * @param string|array $slug Optional. Single tag or list of tags to check for. + * @return bool + */ function is_tag( $slug = '' ) { global $wp_query; @@ -119,6 +236,15 @@ function is_tag( $slug = '' ) { return false; } +/** + * Whether the current page query has the given taxonomy slug or contains taxonomy. + * + * @since 2.5.0 + * @uses $wp_query + * + * @param string|array $slug Optional. Slug or slugs to check in current query. + * @return bool + */ function is_tax( $slug = '' ) { global $wp_query; @@ -138,24 +264,56 @@ function is_tax( $slug = '' ) { return false; } +/** + * Whether the current URL is within the comments popup window. + * + * @since 1.5.0 + * @uses $wp_query + * + * @return bool + */ function is_comments_popup () { global $wp_query; return $wp_query->is_comments_popup; } +/** + * Whether current URL is based on a date. + * + * @since 1.5.0 + * @uses $wp_query + * + * @return bool + */ function is_date () { global $wp_query; return $wp_query->is_date; } +/** + * Whether current blog URL contains a day. + * + * @since 1.5.0 + * @uses $wp_query + * + * @return bool + */ function is_day () { global $wp_query; return $wp_query->is_day; } +/** + * Whether current page query is feed URL. + * + * @since 1.5.0 + * @uses $wp_query + * + * @return bool + */ function is_feed () { global $wp_query; @@ -163,13 +321,13 @@ function is_feed () { } /** - * is_front_page() - Is it the front of the site, whether blog view or a WP Page? + * Whether current page query is the front of the site. * - * @since 2.5 - * @uses is_home - * @uses get_option + * @since 2.5.0 + * @uses is_home() + * @uses get_option() * - * @return bool True if front of site + * @return bool True, if front of site. */ function is_front_page () { // most likely case @@ -182,12 +340,12 @@ function is_front_page () { } /** - * is_home() - Is it the blog view homepage? + * Whether current page view is the blog homepage. * - * @since 2.1 - * @global object $wp_query + * @since 1.5.0 + * @uses $wp_query * - * @return bool True if blog view homepage + * @return bool True if blog view homepage. */ function is_home () { global $wp_query; @@ -195,12 +353,37 @@ function is_home () { return $wp_query->is_home; } +/** + * Whether current page query contains a month. + * + * @since 1.5.0 + * @uses $wp_query + * + * @return bool + */ function is_month () { global $wp_query; return $wp_query->is_month; } +/** + * Whether query is page or contains given page(s). + * + * Calls the function without any parameters will only test whether the current + * query is of the page type. Either a list or a single item can be tested + * against for whether the query is a page and also is the value or one of the + * values in the page parameter. + * + * The parameter can contain the page ID, page title, or page name. The + * parameter can also be an array of those three values. + * + * @since 1.5.0 + * @uses $wp_query + * + * @param mixed $page Either page or list of pages to test against. + * @return bool + */ function is_page ($page = '') { global $wp_query; @@ -224,12 +407,31 @@ function is_page ($page = '') { return false; } +/** + * Whether query contains multiple pages for the results. + * + * @since 1.5.0 + * @uses $wp_query + * + * @return bool + */ function is_paged () { global $wp_query; return $wp_query->is_paged; } +/** + * Whether the current page was created by a plugin. + * + * The plugin can set this by using the global $plugin_page and setting it to + * true. + * + * @since 1.5.0 + * @global bool $plugin_page Used by plugins to tell the query that current is a plugin page. + * + * @return bool + */ function is_plugin_page() { global $plugin_page; @@ -239,24 +441,63 @@ function is_plugin_page() { return false; } +/** + * Whether the current query is preview of post or page. + * + * @since 2.0.0 + * @uses $wp_query + * + * @return bool + */ function is_preview() { global $wp_query; return $wp_query->is_preview; } +/** + * Whether the current query post is robots. + * + * @since 2.1.0 + * @uses $wp_query + * + * @return bool + */ function is_robots() { global $wp_query; return $wp_query->is_robots; } +/** + * Whether current query is the result of a user search. + * + * @since 1.5.0 + * @uses $wp_query + * + * @return bool + */ function is_search () { global $wp_query; return $wp_query->is_search; } +/** + * Whether the current page query is single page. + * + * The parameter can contain the post ID, post title, or post name. The + * parameter can also be an array of those three values. + * + * This applies to other post types, attachments, pages, posts. Just means that + * the current query has only a single object. + * + * @since 1.5.0 + * @uses $wp_query + * + * @param mixed $post Either post or list of posts to test against. + * @return bool + */ function is_single ($post = '') { global $wp_query; @@ -280,30 +521,70 @@ function is_single ($post = '') { return false; } +/** + * Whether is single post, is a page, or is an attachment. + * + * @since 1.5.0 + * @uses $wp_query + * + * @return bool + */ function is_singular() { global $wp_query; return $wp_query->is_singular; } +/** + * Whether the query contains a time. + * + * @since 1.5.0 + * @uses $wp_query + * + * @return bool + */ function is_time () { global $wp_query; return $wp_query->is_time; } +/** + * Whether the query is a trackback. + * + * @since 1.5.0 + * @uses $wp_query + * + * @return bool + */ function is_trackback () { global $wp_query; return $wp_query->is_trackback; } +/** + * Whether the query contains a year. + * + * @since 1.5.0 + * @uses $wp_query + * + * @return bool + */ function is_year () { global $wp_query; return $wp_query->is_year; } +/** + * Whether current page query is a 404 and no results for WordPress query. + * + * @since 1.5.0 + * @uses $wp_query + * + * @return bool True, if nothing is found matching WordPress Query. + */ function is_404 () { global $wp_query; @@ -314,24 +595,57 @@ function is_404 () { * The Loop. Post loop control. */ +/** + * Whether current WordPress query has results to loop over. + * + * @see WP_Query::have_posts() + * @since 1.5.0 + * @uses $wp_query + * + * @return bool + */ function have_posts() { global $wp_query; return $wp_query->have_posts(); } +/** + * Whether the caller is in the Loop. + * + * @since 2.0.0 + * @uses $wp_query + * + * @return bool True if caller is within loop, false if loop hasn't started or ended. + */ function in_the_loop() { global $wp_query; return $wp_query->in_the_loop; } +/** + * Rewind the loop posts. + * + * @see WP_Query::rewind_posts() + * @since 1.5.0 + * @uses $wp_query + * + * @return null + */ function rewind_posts() { global $wp_query; return $wp_query->rewind_posts(); } +/** + * Iterate the post index in the loop. + * + * @see WP_Query::the_post() + * @since 1.5.0 + * @uses $wp_query + */ function the_post() { global $wp_query; @@ -342,11 +656,29 @@ function the_post() { * Comments loop. */ +/** + * Whether there are comments to loop over. + * + * @see WP_Query::have_comments() + * @since 2.2.0 + * @uses $wp_query + * + * @return bool + */ function have_comments() { global $wp_query; return $wp_query->have_comments(); } +/** + * Iterate comment index in the comment loop. + * + * @see WP_Query::the_comment() + * @since 2.2.0 + * @uses $wp_query + * + * @return object + */ function the_comment() { global $wp_query; return $wp_query->the_comment(); @@ -356,53 +688,396 @@ function the_comment() { * WP_Query */ +/** + * The WordPress Query class. + * + * @link http://codex.wordpress.org/Function_Reference/WP_Query Codex page. + * + * @since 1.5.0 + */ class WP_Query { + + /** + * Query string + * + * @since 1.5.0 + * @access public + * @var string + */ var $query; + + /** + * Query search variables set by the user. + * + * @since 1.5.0 + * @access public + * @var array + */ var $query_vars = array(); + + /** + * Holds the data for a single object that is queried. + * + * Holds the contents of a post, page, category, attachment. + * + * @since 1.5.0 + * @access public + * @var object|array + */ var $queried_object; + + /** + * The ID of the queried object. + * + * @since 1.5.0 + * @access public + * @var int + */ var $queried_object_id; + + /** + * Get post database query. + * + * @since 2.0.1 + * @access public + * @var string + */ var $request; + /** + * List of posts. + * + * @since 1.5.0 + * @access public + * @var array + */ var $posts; + + /** + * The amount of posts for the current query. + * + * @since 1.5.0 + * @access public + * @var int + */ var $post_count = 0; + + /** + * Index of the current item in the loop. + * + * @since 1.5.0 + * @access public + * @var int + */ var $current_post = -1; + + /** + * Whether the loop has started and the caller is in the loop. + * + * @since 2.0.0 + * @access public + * @var bool + */ var $in_the_loop = false; + + /** + * The current post ID. + * + * @since 1.5.0 + * @access public + * @var int + */ var $post; + /** + * The list of comments for current post. + * + * @since 2.2.0 + * @access public + * @var array + */ var $comments; + + /** + * The amount of comments for the posts. + * + * @since 2.2.0 + * @access public + * @var int + */ var $comment_count = 0; + + /** + * The index of the comment in the comment loop. + * + * @since 2.2.0 + * @access public + * @var int + */ var $current_comment = -1; + + /** + * Current comment ID. + * + * @since 2.2.0 + * @access public + * @var int + */ var $comment; + /** + * Amount of posts if limit clause was not used. + * + * @since 2.1.0 + * @access public + * @var int + */ var $found_posts = 0; + + /** + * The amount of pages. + * + * @since 2.1.0 + * @access public + * @var int + */ var $max_num_pages = 0; + /** + * Set if query is single post. + * + * @since 1.5.0 + * @access public + * @var bool + */ var $is_single = false; + + /** + * Set if query is preview of blog. + * + * @since 2.0.0 + * @access public + * @var bool + */ var $is_preview = false; + + /** + * Set if query returns a page. + * + * @since 1.5.0 + * @access public + * @var bool + */ var $is_page = false; + + /** + * Set if query is an archive list. + * + * @since 1.5.0 + * @access public + * @var bool + */ var $is_archive = false; + + /** + * Set if query is part of a date. + * + * @since 1.5.0 + * @access public + * @var bool + */ var $is_date = false; + + /** + * Set if query contains a year. + * + * @since 1.5.0 + * @access public + * @var bool + */ var $is_year = false; + + /** + * Set if query contains a month. + * + * @since 1.5.0 + * @access public + * @var bool + */ var $is_month = false; + + /** + * Set if query contains a day. + * + * @since 1.5.0 + * @access public + * @var bool + */ var $is_day = false; + + /** + * Set if query contains time. + * + * @since 1.5.0 + * @access public + * @var bool + */ var $is_time = false; + + /** + * Set if query contains an author. + * + * @since 1.5.0 + * @access public + * @var bool + */ var $is_author = false; + + /** + * Set if query contains category. + * + * @since 1.5.0 + * @access public + * @var bool + */ var $is_category = false; + + /** + * Set if query contains tag. + * + * @since 2.3.0 + * @access public + * @var bool + */ var $is_tag = false; + + /** + * Set if query contains taxonomy. + * + * @since 2.5.0 + * @access public + * @var bool + */ var $is_tax = false; + + /** + * Set if query was part of a search result. + * + * @since 1.5.0 + * @access public + * @var bool + */ var $is_search = false; + + /** + * Set if query is feed display. + * + * @since 1.5.0 + * @access public + * @var bool + */ var $is_feed = false; + + /** + * Set if query is comment feed display. + * + * @since 2.2.0 + * @access public + * @var bool + */ var $is_comment_feed = false; + + /** + * Set if query is trackback. + * + * @since 1.5.0 + * @access public + * @var bool + */ var $is_trackback = false; + + /** + * Set if query is blog homepage. + * + * @since 1.5.0 + * @access public + * @var bool + */ var $is_home = false; + + /** + * Set if query couldn't found anything. + * + * @since 1.5.0 + * @access public + * @var bool + */ var $is_404 = false; + + /** + * Set if query is within comments popup window. + * + * @since 1.5.0 + * @access public + * @var bool + */ var $is_comments_popup = false; + + /** + * Set if query is part of administration page. + * + * @since 1.5.0 + * @access public + * @var bool + */ var $is_admin = false; + + /** + * Set if query is an attachment. + * + * @since 2.0.0 + * @access public + * @var bool + */ var $is_attachment = false; + + /** + * Set if is single, is a page, or is an attachment. + * + * @since 2.1.0 + * @access public + * @var bool + */ var $is_singular = false; + + /** + * Set if query is for robots. + * + * @since 2.1.0 + * @access public + * @var bool + */ var $is_robots = false; + + /** + * Set if query contains posts. + * + * Basically, the homepage if the option isn't set for the static homepage. + * + * @since 2.1.0 + * @access public + * @var bool + */ var $is_posts_page = false; + /** + * Resets query flags to false. + * + * The query flags are what page info WordPress was able to figure out. + * + * @since 2.0.0 + * @access private + */ function init_query_flags() { $this->is_single = false; $this->is_page = false; @@ -430,6 +1105,12 @@ class WP_Query { $this->is_posts_page = false; } + /** + * Initiates object properties and sets default values. + * + * @since 1.5.0 + * @access public + */ function init () { unset($this->posts); unset($this->query); @@ -443,11 +1124,25 @@ class WP_Query { $this->init_query_flags(); } - // Reparse the query vars. + /** + * Reparse the query vars. + * + * @since 1.5.0 + * @access public + */ function parse_query_vars() { $this->parse_query(''); } + /** + * Fills in the query variables, which do not exist within the parameter. + * + * @since 2.1.0 + * @access public + * + * @param array $array Defined query variables. + * @return array Complete query variables with undefined ones filled in empty. + */ function fill_query_vars($array) { $keys = array( 'error' @@ -499,7 +1194,14 @@ class WP_Query { return $array; } - // Parse a query string and set query type booleans. + /** + * Parse a query string and set query type booleans. + * + * @since 1.5.0 + * @access public + * + * @param string|array $query + */ function parse_query ($query) { if ( !empty($query) || !isset($this->query) ) { $this->init(); @@ -707,7 +1409,7 @@ class WP_Query { $this->is_author = true; } - if ( ($this->is_date || $this->is_author || $this->is_category || $this->is_tag || $this->is_tax ) ) + if ( ($this->is_date || $this->is_author || $this->is_category || $this->is_tag ) ) $this->is_archive = true; } @@ -791,6 +1493,12 @@ class WP_Query { do_action_ref_array('parse_query', array(&$this)); } + /** + * Sets the 404 property and saves whether query is feed. + * + * @since 2.0.0 + * @access public + */ function set_404() { $is_feed = $this->is_feed; @@ -800,6 +1508,15 @@ class WP_Query { $this->is_feed = $is_feed; } + /** + * Retrieve query variable. + * + * @since 1.5.0 + * @access public + * + * @param string $query_var Query variable key. + * @return mixed + */ function get($query_var) { if (isset($this->query_vars[$query_var])) { return $this->query_vars[$query_var]; @@ -808,10 +1525,31 @@ class WP_Query { return ''; } + /** + * Set query variable. + * + * @since 1.5.0 + * @access public + * + * @param string $query_var Query variable key. + * @param mixed $value Query variable value. + */ function set($query_var, $value) { $this->query_vars[$query_var] = $value; } + /** + * Retrieve the posts based on query variables. + * + * There are a few filters and actions that can be used to modify the post + * database query. + * + * @since 1.5.0 + * @access public + * @uses do_action_ref_array() Calls 'pre_get_posts' hook before retrieving posts. + * + * @return array List of posts. + */ function &get_posts() { global $wpdb, $user_ID; @@ -1549,7 +2287,7 @@ class WP_Query { if ( !empty($sticky_posts) ) { $stickies__in = implode(',', array_map( 'absint', $sticky_posts )); $stickies = $wpdb->get_results( "SELECT * FROM $wpdb->posts WHERE $wpdb->posts.ID IN ($stickies__in)" ); - // TODO Make sure post is published or viewable by the current user + /** @todo Make sure post is published or viewable by the current user */ foreach ( $stickies as $sticky_post ) { if ( 'publish' != $sticky_post->post_status ) continue; @@ -1572,6 +2310,14 @@ class WP_Query { return $this->posts; } + /** + * Setup the next post and iterate current post index. + * + * @since 1.5.0 + * @access public + * + * @return object Next post. + */ function next_post() { $this->current_post++; @@ -1580,6 +2326,17 @@ class WP_Query { return $this->post; } + /** + * Sets up the current post. + * + * Retrieves the next post, sets up the post, sets the 'in the loop' + * property to true. + * + * @since 1.5.0 + * @access public + * @uses $post + * @uses do_action() Calls 'loop_start' if loop has just started + */ function the_post() { global $post; $this->in_the_loop = true; @@ -1590,6 +2347,17 @@ class WP_Query { do_action('loop_start'); } + /** + * Whether there are more posts available in the loop. + * + * Calls action 'loop_end', when the loop is complete. + * + * @since 1.5.0 + * @access public + * @uses do_action() Calls 'loop_start' if loop has just started + * + * @return bool True if posts are available, false if end of loop. + */ function have_posts() { if ($this->current_post + 1 < $this->post_count) { return true; @@ -1603,6 +2371,12 @@ class WP_Query { return false; } + /** + * Rewind the posts and reset post index. + * + * @since 1.5.0 + * @access public + */ function rewind_posts() { $this->current_post = -1; if ($this->post_count > 0) { @@ -1610,6 +2384,14 @@ class WP_Query { } } + /** + * Iterate current comment index and return comment object. + * + * @since 2.2.0 + * @access public + * + * @return object Comment object. + */ function next_comment() { $this->current_comment++; @@ -1617,6 +2399,14 @@ class WP_Query { return $this->comment; } + /** + * Sets up the current comment. + * + * @since 2.2.0 + * @access public + * @global object $comment Current comment. + * @uses do_action() Calls 'comment_loop_start' hook when first comment is processed. + */ function the_comment() { global $comment; @@ -1627,6 +2417,16 @@ class WP_Query { } } + /** + * Whether there are more comments available. + * + * Automatically rewinds comments when finished. + * + * @since 2.2.0 + * @access public + * + * @return bool True, if more comments. False, if no more posts. + */ function have_comments() { if ($this->current_comment + 1 < $this->comment_count) { return true; @@ -1637,6 +2437,12 @@ class WP_Query { return false; } + /** + * Rewind the comments, resets the comment index and comment to first. + * + * @since 2.2.0 + * @access public + */ function rewind_comments() { $this->current_comment = -1; if ($this->comment_count > 0) { @@ -1644,11 +2450,32 @@ class WP_Query { } } + /** + * Sets up the WordPress query by parsing query string. + * + * @since 1.5.0 + * @access public + * + * @param string $query URL query string. + * @return array List of posts. + */ function &query($query) { $this->parse_query($query); return $this->get_posts(); } + /** + * Retrieve queried object. + * + * If queried object is not set, then the queried object will be set from + * the category, tag, taxonomy, posts page, single post, page, or author + * query variable. After it is set up, it will be returned. + * + * @since 1.5.0 + * @access public + * + * @return object + */ function get_queried_object() { if (isset($this->queried_object)) { return $this->queried_object; @@ -1697,6 +2524,14 @@ class WP_Query { return $this->queried_object; } + /** + * Retrieve ID of the current queried object. + * + * @since 1.5.0 + * @access public + * + * @return int + */ function get_queried_object_id() { $this->get_queried_object(); @@ -1707,6 +2542,17 @@ class WP_Query { return 0; } + /** + * PHP4 type constructor. + * + * Sets up the WordPress query, if parameter is not empty. + * + * @since 1.5.0 + * @access public + * + * @param string $query URL query string. + * @return WP_Query + */ function WP_Query ($query = '') { if (! empty($query)) { $this->query($query); @@ -1714,8 +2560,17 @@ class WP_Query { } } - -// Redirect old slugs +/** + * Redirect old slugs to the correct permalink. + * + * Attempts to find the current slug from the past slugs. + * + * @since 2.1.0 + * @uses $wp_query + * @uses $wpdb + * + * @return null If no link is found, null is returned. + */ function wp_old_slug_redirect () { global $wp_query; if ( is_404() && '' != $wp_query->query_vars['name'] ) : @@ -1747,12 +2602,14 @@ function wp_old_slug_redirect () { endif; } - -// -// Private helper functions -// - -// Setup global post data. +/** + * Setup global post data. + * + * @since 1.5.0 + * + * @param object $post Post data. + * @return bool True when finished. + */ function setup_postdata($post) { global $id, $authordata, $day, $currentmonth, $page, $pages, $multipage, $more, $numpages;