WordPress.org

Make WordPress Core

Ticket #25514: WP_Query-hook-docs.6.diff

File WP_Query-hook-docs.6.diff, 21.1 KB (added by dougwollison, 6 months ago)

Spelling corrections; updated notes on pre_get_posts hook.

  • wp-includes/query.php

     
    17091709                $this->query_vars_hash = md5( serialize( $this->query_vars ) ); 
    17101710                $this->query_vars_changed = false; 
    17111711 
    1712                 do_action_ref_array('parse_query', array(&$this)); 
     1712                /** 
     1713                 * Fires after parse_query is complete. 
     1714                 * 
     1715                 * @since 1.5.2 
     1716                 * 
     1717                 * @param WP_Query &$this The WP_Query instance (passed by reference). 
     1718                 */ 
     1719                do_action_ref_array( 'parse_query', array( &$this ) ); 
    17131720        } 
    17141721 
    17151722        /* 
     
    19031910 
    19041911                $this->tax_query = new WP_Tax_Query( $tax_query ); 
    19051912 
     1913                /** 
     1914                 * Fires after parse_tax_query is complete. 
     1915                 * 
     1916                 * @since 3.7.0 
     1917                 * 
     1918                 * @param WP_Query $this The WP_Query instance. 
     1919                 */ 
    19061920                do_action( 'parse_tax_query', $this ); 
    19071921        } 
    19081922 
     
    21442158 
    21452159                $this->parse_query(); 
    21462160 
    2147                 do_action_ref_array('pre_get_posts', array(&$this)); 
     2161                /** 
     2162                 * Fires after the query variable object is created, but before the actual query is run. 
     2163                 * 
     2164                 * Note: If using conditional tags, use the method versions within the passed instance 
     2165                 * (e.g. $this->is_main_query() instead of is_main_query()). This is because the functions 
     2166                 * like is_main_query() test against the global $wp_query instance, not the passed one. 
     2167                 * 
     2168                 * @since 2.0.0 
     2169                 * 
     2170                 * @param WP_Query &$this The WP_Query instance (passed by reference). 
     2171                 */ 
     2172                do_action_ref_array( 'pre_get_posts', array( &$this ) ); 
    21482173 
    21492174                // Shorthand. 
    21502175                $q = &$this->query_vars; 
     
    27742799                // Apply filters on where and join prior to paging so that any 
    27752800                // manipulations to them are reflected in the paging by day queries. 
    27762801                if ( !$q['suppress_filters'] ) { 
    2777                         $where = apply_filters_ref_array('posts_where', array( $where, &$this ) ); 
    2778                         $join = apply_filters_ref_array('posts_join', array( $join, &$this ) ); 
     2802                        /** 
     2803                         * Filter the WHERE clause of the query. 
     2804                         * 
     2805                         * @since 1.5.2 
     2806                         * 
     2807                         * @param string   $where The WHERE clause of the query. 
     2808                         * @param WP_Query &$this The WP_Query instance (passed by reference). 
     2809                         */ 
     2810                        $where = apply_filters_ref_array( 'posts_where', array( $where, &$this ) ); 
     2811 
     2812                        /** 
     2813                         * Filter the JOIN clause of the query. 
     2814                         * 
     2815                         * @since 1.5.2 
     2816                         * 
     2817                         * @param string   $where The JOIN clause of the query. 
     2818                         * @param WP_Query &$this The WP_Query instance (passed by reference). 
     2819                         */ 
     2820                        $join = apply_filters_ref_array( 'posts_join', array( $join, &$this ) ); 
    27792821                } 
    27802822 
    27812823                // Paging 
     
    28062848                        } 
    28072849 
    28082850                        if ( !$q['suppress_filters'] ) { 
    2809                                 $cjoin = apply_filters_ref_array('comment_feed_join', array( $cjoin, &$this ) ); 
    2810                                 $cwhere = apply_filters_ref_array('comment_feed_where', array( $cwhere, &$this ) ); 
    2811                                 $cgroupby = apply_filters_ref_array('comment_feed_groupby', array( $cgroupby, &$this ) ); 
    2812                                 $corderby = apply_filters_ref_array('comment_feed_orderby', array( 'comment_date_gmt DESC', &$this ) ); 
    2813                                 $climits = apply_filters_ref_array('comment_feed_limits', array( 'LIMIT ' . get_option('posts_per_rss'), &$this ) ); 
     2851                                /** 
     2852                                 * Filter the JOIN clause of the comments feed query before sending. 
     2853                                 * 
     2854                                 * @since 1.5.2 
     2855                                 * 
     2856                                 * @param string   $cjoin The JOIN clause of the query. 
     2857                                 * @param WP_Query &$this The WP_Query instance (passed by reference). 
     2858                                 */ 
     2859                                $cjoin = apply_filters_ref_array( 'comment_feed_join', array( $cjoin, &$this ) ); 
     2860 
     2861                                /** 
     2862                                 * Filter the WHERE clause of the comments feed query before sending. 
     2863                                 * 
     2864                                 * @since 1.5.2 
     2865                                 * 
     2866                                 * @param string   $cwhere The WHERE clause of the query. 
     2867                                 * @param WP_Query &$this  The WP_Query instance (passed by reference). 
     2868                                 */ 
     2869                                $cwhere = apply_filters_ref_array( 'comment_feed_where', array( $cwhere, &$this ) ); 
     2870 
     2871                                /** 
     2872                                 * Filter the GROUP BY clause of the comments feed query before sending. 
     2873                                 * 
     2874                                 * @since 1.5.2 
     2875                                 * 
     2876                                 * @param string   $cgroupby The GROUP BY clause of the query. 
     2877                                 * @param WP_Query &$this    The WP_Query instance (passed by reference). 
     2878                                 */ 
     2879                                $cgroupby = apply_filters_ref_array( 'comment_feed_groupby', array( $cgroupby, &$this ) ); 
     2880 
     2881                                /** 
     2882                                 * Filter the ORDER BY clause of the comments feed query before sending. 
     2883                                 * 
     2884                                 * @since 1.5.2 
     2885                                 * 
     2886                                 * @param string   $corderby The ORDER BY clause of the query. 
     2887                                 * @param WP_Query &$this    The WP_Query instance (passed by reference). 
     2888                                 */ 
     2889                                $corderby = apply_filters_ref_array( 'comment_feed_orderby', array( 'comment_date_gmt DESC', &$this ) ); 
     2890 
     2891                                /** 
     2892                                 * Filter the LIMIT clause of the comments feed query before sending. 
     2893                                 * 
     2894                                 * @since 1.5.2 
     2895                                 * 
     2896                                 * @param string   $climits The JOIN clause of the query. 
     2897                                 * @param WP_Query &$this   The WP_Query instance (passed by reference). 
     2898                                 */ 
     2899                                $climits = apply_filters_ref_array( 'comment_feed_limits', array( 'LIMIT ' . get_option('posts_per_rss'), &$this ) ); 
    28142900                        } 
    28152901                        $cgroupby = ( ! empty( $cgroupby ) ) ? 'GROUP BY ' . $cgroupby : ''; 
    28162902                        $corderby = ( ! empty( $corderby ) ) ? 'ORDER BY ' . $corderby : ''; 
     
    28332919 
    28342920                $pieces = array( 'where', 'groupby', 'join', 'orderby', 'distinct', 'fields', 'limits' ); 
    28352921 
    2836                 // Apply post-paging filters on where and join. Only plugins that 
    2837                 // manipulate paging queries should use these hooks. 
    28382922                if ( !$q['suppress_filters'] ) { 
     2923                        /** 
     2924                         * Filter the WHERE clause of the query. 
     2925                         * 
     2926                         * Specifically for manipulating paging queries. 
     2927                         * 
     2928                         * @since 1.5.2 
     2929                         * 
     2930                         * @param string   $where The WHERE clause of the query. 
     2931                         * @param WP_Query &$this The WP_Query instance (passed by reference). 
     2932                         */ 
    28392933                        $where          = apply_filters_ref_array( 'posts_where_paged', array( $where, &$this ) ); 
     2934 
     2935                        /** 
     2936                         * Filter the GROUP BY clause of the query. 
     2937                         * 
     2938                         * @since 2.0.0 
     2939                         * 
     2940                         * @param string   $groupby The GROUP BY clause of the query. 
     2941                         * @param WP_Query &$this   The WP_Query instance (passed by reference). 
     2942                         */ 
    28402943                        $groupby        = apply_filters_ref_array( 'posts_groupby',             array( $groupby, &$this ) ); 
     2944 
     2945                        /** 
     2946                         * Filter the JOIN clause of the query. 
     2947                         * 
     2948                         * Specifically for manipulating paging queries. 
     2949                         * 
     2950                         * @since 1.5.2 
     2951                         * 
     2952                         * @param string   $join  The JOIN clause of the query. 
     2953                         * @param WP_Query &$this The WP_Query instance (passed by reference). 
     2954                         */ 
    28412955                        $join           = apply_filters_ref_array( 'posts_join_paged',  array( $join, &$this ) ); 
     2956 
     2957                        /** 
     2958                         * Filter the ORDER BY clause of the query. 
     2959                         * 
     2960                         * @since 1.5.2 
     2961                         * 
     2962                         * @param string   $orderby The ORDER BY clause of the query. 
     2963                         * @param WP_Query &$this   The WP_Query instance (passed by reference). 
     2964                         */ 
    28422965                        $orderby        = apply_filters_ref_array( 'posts_orderby',             array( $orderby, &$this ) ); 
     2966 
     2967                        /** 
     2968                         * Filter the DISTINCT clause of the query. 
     2969                         * 
     2970                         * @since 2.1.0 
     2971                         * 
     2972                         * @param string   $distinct The DISTINCT clause of the query. 
     2973                         * @param WP_Query &$this    The WP_Query instance (passed by reference). 
     2974                         */ 
    28432975                        $distinct       = apply_filters_ref_array( 'posts_distinct',    array( $distinct, &$this ) ); 
     2976 
     2977                        /** 
     2978                         * Filter the LIMIT clause of the query. 
     2979                         * 
     2980                         * @since 2.1.0 
     2981                         * 
     2982                         * @param string   $limits The LIMIT clause of the query. 
     2983                         * @param WP_Query &$this  The WP_Query instance (passed by reference). 
     2984                         */ 
    28442985                        $limits         = apply_filters_ref_array( 'post_limits',               array( $limits, &$this ) ); 
     2986 
     2987                        /** 
     2988                         * Filter the SELECT clause of the query. 
     2989                         * 
     2990                         * @since 2.1.0 
     2991                         * 
     2992                         * @param string   $fields The SELECT clause of the query. 
     2993                         * @param WP_Query &$this  The WP_Query instance (passed by reference). 
     2994                         */ 
    28452995                        $fields         = apply_filters_ref_array( 'posts_fields',              array( $fields, &$this ) ); 
    28462996 
    2847                         // Filter all clauses at once, for convenience 
    2848                         $clauses = (array) apply_filters_ref_array( 'posts_clauses', array( compact( $pieces ), &$this ) ); 
     2997                        $clauses = compact( $pieces ); 
     2998                        /** 
     2999                         * Filter all clauses at once, for convenience. 
     3000                         * 
     3001                         * Covers the WHERE, GROUP BY, JOIN, ORDER BY, DISTINCT, 
     3002                         * fields (SELECT), and LIMITS clauses. 
     3003                         * 
     3004                         * @since 3.1.0 
     3005                         * 
     3006                         * @param array    $clauses The list of clauses for the query. 
     3007                         * @param WP_Query &$this  The WP_Query instance (passed by reference). 
     3008                         */ 
     3009                        $clauses = (array) apply_filters_ref_array( 'posts_clauses', array( $clauses, &$this ) ); 
     3010 
    28493011                        foreach ( $pieces as $piece ) 
    28503012                                $$piece = isset( $clauses[ $piece ] ) ? $clauses[ $piece ] : ''; 
    28513013                } 
    28523014 
    2853                 // Announce current selection parameters. For use by caching plugins. 
    2854                 do_action( 'posts_selection', $where . $groupby . $orderby . $limits . $join ); 
     3015                $selection = $where . $groupby . $orderby . $limits . $join; 
     3016                /** 
     3017                 * Fires to announce current selection parameters. 
     3018                 * 
     3019                 * For use by caching plugins. 
     3020                 * 
     3021                 * @since 2.3.0 
     3022                 * 
     3023                 * @param string $selection The assembled selection query. 
     3024                 */ 
     3025                do_action( 'posts_selection', $selection ); 
    28553026 
    28563027                // Filter again for the benefit of caching plugins. Regular plugins should use the hooks above. 
    28573028                if ( !$q['suppress_filters'] ) { 
     3029                        /** 
     3030                         * Filter the WHERE clause of the query. 
     3031                         * 
     3032                         * For use by caching plugins. 
     3033                         * 
     3034                         * @since 2.5.0 
     3035                         * 
     3036                         * @param string   $where The WHERE clause of the query. 
     3037                         * @param WP_Query &$this The WP_Query instance (passed by reference). 
     3038                         */ 
    28583039                        $where          = apply_filters_ref_array( 'posts_where_request',               array( $where, &$this ) ); 
     3040 
     3041                        /** 
     3042                         * Filter the GROUP BY clause of the query. 
     3043                         * 
     3044                         * For use by caching plugins. 
     3045                         * 
     3046                         * @since 2.5.0 
     3047                         * 
     3048                         * @param string   $groupby The GROUP BY clause of the query. 
     3049                         * @param WP_Query &$this   The WP_Query instance (passed by reference). 
     3050                         */ 
    28593051                        $groupby        = apply_filters_ref_array( 'posts_groupby_request',             array( $groupby, &$this ) ); 
     3052 
     3053                        /** 
     3054                         * Filter the JOIN clause of the query. 
     3055                         * 
     3056                         * For use by caching plugins. 
     3057                         * 
     3058                         * @since 2.5.0 
     3059                         * 
     3060                         * @param string   $join  The JOIN clause of the query. 
     3061                         * @param WP_Query &$this The WP_Query instance (passed by reference). 
     3062                         */ 
    28603063                        $join           = apply_filters_ref_array( 'posts_join_request',                array( $join, &$this ) ); 
     3064 
     3065                        /** 
     3066                         * Filter the ORDER BY clause of the query. 
     3067                         * 
     3068                         * For use by caching plugins. 
     3069                         * 
     3070                         * @since 2.5.0 
     3071                         * 
     3072                         * @param string   $orderby The ORDER BY clause of the query. 
     3073                         * @param WP_Query &$this   The WP_Query instance (passed by reference). 
     3074                         */ 
    28613075                        $orderby        = apply_filters_ref_array( 'posts_orderby_request',             array( $orderby, &$this ) ); 
     3076 
     3077                        /** 
     3078                         * Filter the DISTINCT clause of the query. 
     3079                         * 
     3080                         * For use by caching plugins. 
     3081                         * 
     3082                         * @since 2.5.0 
     3083                         * 
     3084                         * @param string   $distinct The DISTINCT clause of the query. 
     3085                         * @param WP_Query &$this    The WP_Query instance (passed by reference). 
     3086                         */ 
    28623087                        $distinct       = apply_filters_ref_array( 'posts_distinct_request',    array( $distinct, &$this ) ); 
     3088 
     3089                        /** 
     3090                         * Filter the SELECT clause of the query. 
     3091                         * 
     3092                         * For use by caching plugins. 
     3093                         * 
     3094                         * @since 2.5.0 
     3095                         * 
     3096                         * @param string   $fields The SELECT clause of the query. 
     3097                         * @param WP_Query &$this  The WP_Query instance (passed by reference). 
     3098                         */ 
    28633099                        $fields         = apply_filters_ref_array( 'posts_fields_request',              array( $fields, &$this ) ); 
     3100 
     3101                        /** 
     3102                         * Filter the LIMIT clause of the query. 
     3103                         * 
     3104                         * For use by caching plugins. 
     3105                         * 
     3106                         * @since 2.5.0 
     3107                         * 
     3108                         * @param string   $limits The LIMIT clause of the query. 
     3109                         * @param WP_Query &$this  The WP_Query instance (passed by reference). 
     3110                         */ 
    28643111                        $limits         = apply_filters_ref_array( 'post_limits_request',               array( $limits, &$this ) ); 
    28653112 
    2866                         // Filter all clauses at once, for convenience 
    2867                         $clauses = (array) apply_filters_ref_array( 'posts_clauses_request', array( compact( $pieces ), &$this ) ); 
     3113                        $clauses = compact( $pieces ); 
     3114                        /** 
     3115                         * Filter all clauses at once, for convenience. 
     3116                         * 
     3117                         * For use by caching plugins. 
     3118                         * 
     3119                         * Covers the WHERE, GROUP BY, JOIN, ORDER BY, DISTINCT, 
     3120                         * fields (SELECT), and LIMITS clauses. 
     3121                         * 
     3122                         * @since 3.1.0 
     3123                         * 
     3124                         * @param array    $pieces The pieces of the query. 
     3125                         * @param WP_Query &$this  The WP_Query instance (passed by reference). 
     3126                         */ 
     3127                        $clauses = (array) apply_filters_ref_array( 'posts_clauses_request', array( $clauses, &$this ) ); 
    28683128                        foreach ( $pieces as $piece ) 
    28693129                                $$piece = isset( $clauses[ $piece ] ) ? $clauses[ $piece ] : ''; 
    28703130                } 
     
    28813141                $this->request = $old_request = "SELECT $found_rows $distinct $fields FROM $wpdb->posts $join WHERE 1=1 $where $groupby $orderby $limits"; 
    28823142 
    28833143                if ( !$q['suppress_filters'] ) { 
    2884                         $this->request = apply_filters_ref_array( 'posts_request', array( $this->request, &$this ) ); 
     3144                        $request = $this->request; 
     3145                        /** 
     3146                         * Filter the completed SQL query before sending. 
     3147                         * 
     3148                         * @since 2.0.0 
     3149                         * 
     3150                         * @param array    $request The complete SQL query. 
     3151                         * @param WP_Query &$this   The WP_Query instance (passed by reference). 
     3152                         */ 
     3153                        $this->request = apply_filters_ref_array( 'posts_request', array( $request, &$this ) ); 
    28853154                } 
    28863155 
    28873156                if ( 'ids' == $q['fields'] ) { 
     
    29053174                } 
    29063175 
    29073176                $split_the_query = ( $old_request == $this->request && "$wpdb->posts.*" == $fields && !empty( $limits ) && $q['posts_per_page'] < 500 ); 
     3177 
     3178                /** 
     3179                 * Filter the $split_the_query boolean. 
     3180                 * 
     3181                 * Splitting the query will cause it to fetch just the IDs of the found posts 
     3182                 * (and then individually fetch each post by ID), rather than fetching every 
     3183                 * complete row at once. One massive result vs. many small results. 
     3184                 * 
     3185                 * @since 3.4.0 
     3186                 * 
     3187                 * @param bool     $split_the_query Whether or not to split the query. 
     3188                 * @param WP_Query $this            The WP_Query instance. 
     3189                 */ 
    29083190                $split_the_query = apply_filters( 'split_the_query', $split_the_query, $this ); 
    29093191 
    29103192                if ( $split_the_query ) { 
     
    29123194 
    29133195                        $this->request = "SELECT $found_rows $distinct $wpdb->posts.ID FROM $wpdb->posts $join WHERE 1=1 $where $groupby $orderby $limits"; 
    29143196 
    2915                         $this->request = apply_filters( 'posts_request_ids', $this->request, $this ); 
     3197                        $request = $this->request; 
     3198                        /** 
     3199                         * Filter the Post IDs SQL request before sending. 
     3200                         * 
     3201                         * @since 3.4.0 
     3202                         * 
     3203                         * @param string   $request The post ID request. 
     3204                         * @param WP_Query $this    The WP_Query instance. 
     3205                         */ 
     3206                        $this->request = apply_filters( 'posts_request_ids', $request, $this ); 
    29163207 
    29173208                        $ids = $wpdb->get_col( $this->request ); 
    29183209 
     
    29323223                if ( $this->posts ) 
    29333224                        $this->posts = array_map( 'get_post', $this->posts ); 
    29343225 
    2935                 // Raw results filter. Prior to status checks. 
    2936                 if ( !$q['suppress_filters'] ) 
    2937                         $this->posts = apply_filters_ref_array('posts_results', array( $this->posts, &$this ) ); 
     3226                if ( !$q['suppress_filters'] ){ 
     3227                        $posts = $this->posts; 
     3228                        /** 
     3229                         * Filter the raw post results array, prior to status checks. 
     3230                         * 
     3231                         * @since 2.3.0 
     3232                         * 
     3233                         * @param array    $posts The post results array. 
     3234                         * @param WP_Query &$this The WP_Query instance (passed by reference). 
     3235                         */ 
     3236                        $this->posts = apply_filters_ref_array( 'posts_results', array( $posts, &$this ) ); 
     3237                } 
    29383238 
    29393239                if ( !empty($this->posts) && $this->is_comment_feed && $this->is_singular ) { 
    2940                         $cjoin = apply_filters_ref_array('comment_feed_join', array( '', &$this ) ); 
    2941                         $cwhere = apply_filters_ref_array('comment_feed_where', array( "WHERE comment_post_ID = '{$this->posts[0]->ID}' AND comment_approved = '1'", &$this ) ); 
    2942                         $cgroupby = apply_filters_ref_array('comment_feed_groupby', array( '', &$this ) ); 
     3240                        // duplicate_hook 
     3241                        $cjoin = apply_filters_ref_array( 'comment_feed_join', array( '', &$this ) ); 
     3242 
     3243                        // duplicate_hook 
     3244                        $cwhere = apply_filters_ref_array( 'comment_feed_where', array( "WHERE comment_post_ID = '{$this->posts[0]->ID}' AND comment_approved = '1'", &$this ) ); 
     3245 
     3246                        // duplicate_hook 
     3247                        $cgroupby = apply_filters_ref_array( 'comment_feed_groupby', array( '', &$this ) ); 
    29433248                        $cgroupby = ( ! empty( $cgroupby ) ) ? 'GROUP BY ' . $cgroupby : ''; 
    2944                         $corderby = apply_filters_ref_array('comment_feed_orderby', array( 'comment_date_gmt DESC', &$this ) ); 
     3249 
     3250                        // duplicate_hook 
     3251                        $corderby = apply_filters_ref_array( 'comment_feed_orderby', array( 'comment_date_gmt DESC', &$this ) ); 
    29453252                        $corderby = ( ! empty( $corderby ) ) ? 'ORDER BY ' . $corderby : ''; 
    2946                         $climits = apply_filters_ref_array('comment_feed_limits', array( 'LIMIT ' . get_option('posts_per_rss'), &$this ) ); 
     3253 
     3254                        // duplicate_hook 
     3255                        $climits = apply_filters_ref_array( 'comment_feed_limits', array( 'LIMIT ' . get_option('posts_per_rss'), &$this ) ); 
     3256 
    29473257                        $comments_request = "SELECT $wpdb->comments.* FROM $wpdb->comments $cjoin $cwhere $cgroupby $corderby $climits"; 
    29483258                        $this->comments = $wpdb->get_results($comments_request); 
    29493259                        $this->comment_count = count($this->comments); 
     
    29773287                                } 
    29783288                        } 
    29793289 
    2980                         if ( $this->is_preview && $this->posts && current_user_can( $edit_cap, $this->posts[0]->ID ) ) 
    2981                                 $this->posts[0] = get_post( apply_filters_ref_array( 'the_preview', array( $this->posts[0], &$this ) ) ); 
     3290                        if ( $this->is_preview && $this->posts && current_user_can( $edit_cap, $this->posts[0]->ID ) ){ 
     3291                                $post_preview = $this->posts[0]; 
     3292                                /** 
     3293                                 * Filter the single post for preview mode. 
     3294                                 * 
     3295                                 * @since 2.7.0 
     3296                                 * 
     3297                                 * @param WP_Post  $post_preview  The Post object. 
     3298                                 * @param WP_Query &$this         The WP_Query instance (passed by reference). 
     3299                                 */ 
     3300                                $this->posts[0] = get_post( apply_filters_ref_array( 'the_preview', array( $post_preview, &$this ) ) ); 
     3301                        } 
    29823302                } 
    29833303 
    29843304                // Put sticky posts at the top of the posts array 
     
    30223342                        } 
    30233343                } 
    30243344 
    3025                 if ( !$q['suppress_filters'] ) 
    3026                         $this->posts = apply_filters_ref_array('the_posts', array( $this->posts, &$this ) ); 
     3345                if ( !$q['suppress_filters'] ){ 
     3346                        $posts = $this->posts; 
     3347                        /** 
     3348                         * Filter the array of retrieved posts after they've been fetched and 
     3349                         * internally processed. 
     3350                         * 
     3351                         * @since 1.5.2 
     3352                         * 
     3353                         * @param array    $posts The array of retrieved posts. 
     3354                         * @param WP_Query &$this The WP_Query instance (passed by reference). 
     3355                         */ 
     3356                        $this->posts = apply_filters_ref_array( 'the_posts', array( $posts, &$this ) ); 
     3357                } 
    30273358 
    30283359                // Ensure that any posts added/modified via one of the filters above are 
    30293360                // of the type WP_Post and are filtered. 
     
    30593390                if ( $q['no_found_rows'] || ( is_array( $this->posts ) && ! $this->posts ) ) 
    30603391                        return; 
    30613392 
    3062                 if ( ! empty( $limits ) ) 
    3063                         $this->found_posts = $wpdb->get_var( apply_filters_ref_array( 'found_posts_query', array( 'SELECT FOUND_ROWS()', &$this ) ) ); 
    3064                 else 
     3393                if ( ! empty( $limits ) ){ 
     3394                        $found_posts = 'SELECT FOUND_ROWS()'; 
     3395                        /** 
     3396                         * Filter the query to run for retrieving the found posts. 
     3397                         * 
     3398                         * @since 2.1.0 
     3399                         * 
     3400                         * @param string   $found_posts The query to run to find the found posts. 
     3401                         * @param WP_Query &$this       The WP_Query instance (passed by reference). 
     3402                         */ 
     3403                        $this->found_posts = $wpdb->get_var( apply_filters_ref_array( 'found_posts_query', array( $found_posts, &$this ) ) ); 
     3404                } 
     3405                else{ 
    30653406                        $this->found_posts = count( $this->posts ); 
     3407                } 
    30663408 
    3067                 $this->found_posts = apply_filters_ref_array( 'found_posts', array( $this->found_posts, &$this ) ); 
     3409                $found_posts = $this->found_posts; 
     3410                /** 
     3411                 * Filter the number of found posts. 
     3412                 * 
     3413                 * @since 2.1.0 
     3414                 * 
     3415                 * @param int      $found_posts The number of posts found. 
     3416                 * @param WP_Query &$this       The WP_Query instance (passed by reference). 
     3417                 */ 
     3418                $this->found_posts = apply_filters_ref_array( 'found_posts', array( $found_posts, &$this ) ); 
    30683419 
    30693420                if ( ! empty( $limits ) ) 
    30703421                        $this->max_num_pages = ceil( $this->found_posts / $q['posts_per_page'] ); 
     
    31023453                $this->in_the_loop = true; 
    31033454 
    31043455                if ( $this->current_post == -1 ) // loop has just started 
    3105                         do_action_ref_array('loop_start', array(&$this)); 
     3456                        /** 
     3457                         * Fires once the loop is started. 
     3458                         * 
     3459                         * @since 2.0.0 
     3460                         * 
     3461                         * @param WP_Query &$this The WP_Query instance (passed by reference). 
     3462                         */ 
     3463                        do_action_ref_array( 'loop_start', array( &$this ) ); 
    31063464 
    31073465                $post = $this->next_post(); 
    31083466                setup_postdata($post); 
     
    31233481                if ( $this->current_post + 1 < $this->post_count ) { 
    31243482                        return true; 
    31253483                } elseif ( $this->current_post + 1 == $this->post_count && $this->post_count > 0 ) { 
    3126                         do_action_ref_array('loop_end', array(&$this)); 
     3484                        /** 
     3485                         * Fires once the loop has ended. 
     3486                         * 
     3487                         * @since 2.0.0 
     3488                         * 
     3489                         * @param WP_Query &$this The WP_Query instance (passed by reference). 
     3490                         */ 
     3491                        do_action_ref_array( 'loop_end', array( &$this ) ); 
    31273492                        // Do some cleaning up after the loop 
    31283493                        $this->rewind_posts(); 
    31293494                } 
     
    31743539                $comment = $this->next_comment(); 
    31753540 
    31763541                if ( $this->current_comment == 0 ) { 
    3177                         do_action('comment_loop_start'); 
     3542                        /** 
     3543                         * Fires once the comment loop is started. 
     3544                         * 
     3545                         * @since 2.2.0 
     3546                         */ 
     3547                        do_action( 'comment_loop_start' ); 
    31783548                } 
    31793549        } 
    31803550 
     
    39354305                $pages = array( $post->post_content ); 
    39364306        } 
    39374307 
    3938         do_action_ref_array('the_post', array(&$post)); 
     4308        /** 
     4309         * Fires once the post data has been setup. 
     4310         * 
     4311         * @since 2.8.0 
     4312         * 
     4313         * @param WP_Post &$post The Post object (passed by reference). 
     4314         */ 
     4315        do_action_ref_array( 'the_post', array( &$post ) ); 
    39394316 
    39404317        return true; 
    39414318}