WordPress.org

Make WordPress Core

Changeset 27210


Ignore:
Timestamp:
02/20/2014 05:53:33 PM (8 years ago)
Author:
DrewAPicture
Message:

Inline documentation hooks in wp-includes/query.php.

Covers documentation for the various remaining query hooks, notably including but not limited to:

  • parse_query
  • parse_tax_query
  • pre_get_posts
  • posts_results
  • the_posts
  • found_posts
  • the_post

Props dougwollison, DrewAPicture.
See #25514.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/query.php

    r27208 r27210  
    17141714        $this->query_vars_changed = false;
    17151715
    1716         do_action_ref_array('parse_query', array(&$this));
     1716        /**
     1717         * Fires after the main query vars have been parsed.
     1718         *
     1719         * @since 1.5.0
     1720         *
     1721         * @param WP_Query &$this The WP_Query instance (passed by reference).
     1722         */
     1723        do_action_ref_array( 'parse_query', array( &$this ) );
    17171724    }
    17181725
     
    19211928        $this->tax_query = new WP_Tax_Query( $tax_query );
    19221929
     1930        /**
     1931         * Fires after taxonomy-related query vars have been parsed.
     1932         *
     1933         * @since 3.7.0
     1934         *
     1935         * @param WP_Query $this The WP_Query instance.
     1936         */
    19231937        do_action( 'parse_tax_query', $this );
    19241938    }
     
    21562170        $this->parse_query();
    21572171
    2158         do_action_ref_array('pre_get_posts', array(&$this));
     2172        /**
     2173         * Fires after the query variable object is created, but before the actual query is run.
     2174         *
     2175         * Note: If using conditional tags, use the method versions within the passed instance
     2176         * (e.g. $this->is_main_query() instead of is_main_query()). This is because the functions
     2177         * like is_main_query() test against the global $wp_query instance, not the passed one.
     2178         *
     2179         * @since 2.0.0
     2180         *
     2181         * @param WP_Query &$this The WP_Query instance (passed by reference).
     2182         */
     2183        do_action_ref_array( 'pre_get_posts', array( &$this ) );
    21592184
    21602185        // Shorthand.
     
    31473172
    31483173        if ( !$q['suppress_filters'] ) {
     3174            /**
     3175             * Filter the completed SQL query before sending.
     3176             *
     3177             * @since 2.0.0
     3178             *
     3179             * @param array    $request The complete SQL query.
     3180             * @param WP_Query &$this   The WP_Query instance (passed by reference).
     3181             */
    31493182            $this->request = apply_filters_ref_array( 'posts_request', array( $this->request, &$this ) );
    31503183        }
     
    31713204
    31723205        $split_the_query = ( $old_request == $this->request && "$wpdb->posts.*" == $fields && !empty( $limits ) && $q['posts_per_page'] < 500 );
     3206
     3207        /**
     3208         * Filter whether to split the query.
     3209         *
     3210         * Splitting the query will cause it to fetch just the IDs of the found posts
     3211         * (and then individually fetch each post by ID), rather than fetching every
     3212         * complete row at once. One massive result vs. many small results.
     3213         *
     3214         * @since 3.4.0
     3215         *
     3216         * @param bool     $split_the_query Whether or not to split the query.
     3217         * @param WP_Query $this            The WP_Query instance.
     3218         */
    31733219        $split_the_query = apply_filters( 'split_the_query', $split_the_query, $this );
    31743220
     
    31783224            $this->request = "SELECT $found_rows $distinct $wpdb->posts.ID FROM $wpdb->posts $join WHERE 1=1 $where $groupby $orderby $limits";
    31793225
     3226            /**
     3227             * Filter the Post IDs SQL request before sending.
     3228             *
     3229             * @since 3.4.0
     3230             *
     3231             * @param string   $request The post ID request.
     3232             * @param WP_Query $this    The WP_Query instance.
     3233             */
    31803234            $this->request = apply_filters( 'posts_request_ids', $this->request, $this );
    31813235
     
    31983252            $this->posts = array_map( 'get_post', $this->posts );
    31993253
    3200         // Raw results filter. Prior to status checks.
    3201         if ( !$q['suppress_filters'] )
    3202             $this->posts = apply_filters_ref_array('posts_results', array( $this->posts, &$this ) );
     3254        if ( ! $q['suppress_filters'] ) {
     3255            /**
     3256             * Filter the raw post results array, prior to status checks.
     3257             *
     3258             * @since 2.3.0
     3259             *
     3260             * @param array    $posts The post results array.
     3261             * @param WP_Query &$this The WP_Query instance (passed by reference).
     3262             */
     3263            $this->posts = apply_filters_ref_array( 'posts_results', array( $this->posts, &$this ) );
     3264        }
    32033265
    32043266        if ( !empty($this->posts) && $this->is_comment_feed && $this->is_singular ) {
     
    32533315            }
    32543316
    3255             if ( $this->is_preview && $this->posts && current_user_can( $edit_cap, $this->posts[0]->ID ) )
     3317            if ( $this->is_preview && $this->posts && current_user_can( $edit_cap, $this->posts[0]->ID ) ) {
     3318                /**
     3319                 * Filter the single post for preview mode.
     3320                 *
     3321                 * @since 2.7.0
     3322                 *
     3323                 * @param WP_Post  $post_preview  The Post object.
     3324                 * @param WP_Query &$this         The WP_Query instance (passed by reference).
     3325                 */
    32563326                $this->posts[0] = get_post( apply_filters_ref_array( 'the_preview', array( $this->posts[0], &$this ) ) );
     3327            }
    32573328        }
    32583329
     
    32983369        }
    32993370
    3300         if ( !$q['suppress_filters'] )
    3301             $this->posts = apply_filters_ref_array('the_posts', array( $this->posts, &$this ) );
     3371        if ( ! $q['suppress_filters'] ) {
     3372            /**
     3373             * Filter the array of retrieved posts after they've been fetched and
     3374             * internally processed.
     3375             *
     3376             * @since 1.5.0
     3377             *
     3378             * @param array    $posts The array of retrieved posts.
     3379             * @param WP_Query &$this The WP_Query instance (passed by reference).
     3380             */
     3381            $this->posts = apply_filters_ref_array( 'the_posts', array( $this->posts, &$this ) );
     3382        }
    33023383
    33033384        // Ensure that any posts added/modified via one of the filters above are
     
    33353416            return;
    33363417
    3337         if ( ! empty( $limits ) )
     3418        if ( ! empty( $limits ) ) {
     3419            /**
     3420             * Filter the query to run for retrieving the found posts.
     3421             *
     3422             * @since 2.1.0
     3423             *
     3424             * @param string   $found_posts The query to run to find the found posts.
     3425             * @param WP_Query &$this       The WP_Query instance (passed by reference).
     3426             */
    33383427            $this->found_posts = $wpdb->get_var( apply_filters_ref_array( 'found_posts_query', array( 'SELECT FOUND_ROWS()', &$this ) ) );
    3339         else
     3428        } else {
    33403429            $this->found_posts = count( $this->posts );
    3341 
     3430        }
     3431
     3432        /**
     3433         * Filter the number of found posts for the query.
     3434         *
     3435         * @since 2.1.0
     3436         *
     3437         * @param int      $found_posts The number of posts found.
     3438         * @param WP_Query &$this       The WP_Query instance (passed by reference).
     3439         */
    33423440        $this->found_posts = apply_filters_ref_array( 'found_posts', array( $this->found_posts, &$this ) );
    33433441
     
    33783476
    33793477        if ( $this->current_post == -1 ) // loop has just started
    3380             do_action_ref_array('loop_start', array(&$this));
     3478            /**
     3479             * Fires once the loop is started.
     3480             *
     3481             * @since 2.0.0
     3482             *
     3483             * @param WP_Query &$this The WP_Query instance (passed by reference).
     3484             */
     3485            do_action_ref_array( 'loop_start', array( &$this ) );
    33813486
    33823487        $post = $this->next_post();
     
    33993504            return true;
    34003505        } elseif ( $this->current_post + 1 == $this->post_count && $this->post_count > 0 ) {
    3401             do_action_ref_array('loop_end', array(&$this));
     3506            /**
     3507             * Fires once the loop has ended.
     3508             *
     3509             * @since 2.0.0
     3510             *
     3511             * @param WP_Query &$this The WP_Query instance (passed by reference).
     3512             */
     3513            do_action_ref_array( 'loop_end', array( &$this ) );
    34023514            // Do some cleaning up after the loop
    34033515            $this->rewind_posts();
     
    34503562
    34513563        if ( $this->current_comment == 0 ) {
    3452             do_action('comment_loop_start');
     3564            /**
     3565             * Fires once the comment loop is started.
     3566             *
     3567             * @since 2.2.0
     3568             */
     3569            do_action( 'comment_loop_start' );
    34533570        }
    34543571    }
     
    42434360    }
    42444361
    4245     do_action_ref_array('the_post', array(&$post));
     4362    /**
     4363     * Fires once the post data has been setup.
     4364     *
     4365     * @since 2.8.0
     4366     *
     4367     * @param WP_Post &$post The Post object (passed by reference).
     4368     */
     4369    do_action_ref_array( 'the_post', array( &$post ) );
    42464370
    42474371    return true;
Note: See TracChangeset for help on using the changeset viewer.