WordPress.org

Make WordPress Core

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

File WP_Query-hook-docs.5.diff, 20.9 KB (added by dougwollison, 5 years ago)

Also fixed missing () on function names.

  • 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: many of the conditional tags aren't yet available at this point (e.g. is_main_query()).
     2165                 *
     2166                 * @since 2.0.0
     2167                 *
     2168                 * @param WP_Query &$this The WP_Query instance (passed by reference).
     2169                 */
     2170                do_action_ref_array( 'pre_get_posts', array( &$this ) );
    21482171
    21492172                // Shorthand.
    21502173                $q = &$this->query_vars;
     
    27742797                // Apply filters on where and join prior to paging so that any
    27752798                // manipulations to them are reflected in the paging by day queries.
    27762799                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 ) );
     2800                        /**
     2801                         * Filter the WHERE clause of the query.
     2802                         *
     2803                         * @since 1.5.2
     2804                         *
     2805                         * @param string   $where The WHERE clause of the query.
     2806                         * @param WP_Query &$this The WP_Query instance (passed by reference).
     2807                         */
     2808                        $where = apply_filters_ref_array( 'posts_where', array( $where, &$this ) );
     2809
     2810                        /**
     2811                         * Filter the JOIN clause of the query.
     2812                         *
     2813                         * @since 1.5.2
     2814                         *
     2815                         * @param string   $where The JOIN clause of the query.
     2816                         * @param WP_Query &$this The WP_Query instance (passed by reference).
     2817                         */
     2818                        $join = apply_filters_ref_array( 'posts_join', array( $join, &$this ) );
    27792819                }
    27802820
    27812821                // Paging
     
    28062846                        }
    28072847
    28082848                        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 ) );
     2849                                /**
     2850                                 * Filter the JOIN clause of the comments feed query before sending.
     2851                                 *
     2852                                 * @since 1.5.2
     2853                                 *
     2854                                 * @param string   $cjoin The JOIN clause of the query.
     2855                                 * @param WP_Query &$this The WP_Query instance (passed by reference).
     2856                                 */
     2857                                $cjoin = apply_filters_ref_array( 'comment_feed_join', array( $cjoin, &$this ) );
     2858
     2859                                /**
     2860                                 * Filter the WHERE clause of the comments feed query before sending.
     2861                                 *
     2862                                 * @since 1.5.2
     2863                                 *
     2864                                 * @param string   $cwhere The WHERE clause of the query.
     2865                                 * @param WP_Query &$this  The WP_Query instance (passed by reference).
     2866                                 */
     2867                                $cwhere = apply_filters_ref_array( 'comment_feed_where', array( $cwhere, &$this ) );
     2868
     2869                                /**
     2870                                 * Filter the GROUP BY clause of the comments feed query before sending.
     2871                                 *
     2872                                 * @since 1.5.2
     2873                                 *
     2874                                 * @param string   $cgroupby The GROUP BY clause of the query.
     2875                                 * @param WP_Query &$this    The WP_Query instance (passed by reference).
     2876                                 */
     2877                                $cgroupby = apply_filters_ref_array( 'comment_feed_groupby', array( $cgroupby, &$this ) );
     2878
     2879                                /**
     2880                                 * Filter the ORDER BY clause of the comments feed query before sending.
     2881                                 *
     2882                                 * @since 1.5.2
     2883                                 *
     2884                                 * @param string   $corderby The ORDER BY clause of the query.
     2885                                 * @param WP_Query &$this    The WP_Query instance (passed by reference).
     2886                                 */
     2887                                $corderby = apply_filters_ref_array( 'comment_feed_orderby', array( 'comment_date_gmt DESC', &$this ) );
     2888
     2889                                /**
     2890                                 * Filter the LIMIT clause of the comments feed query before sending.
     2891                                 *
     2892                                 * @since 1.5.2
     2893                                 *
     2894                                 * @param string   $climits The JOIN clause of the query.
     2895                                 * @param WP_Query &$this   The WP_Query instance (passed by reference).
     2896                                 */
     2897                                $climits = apply_filters_ref_array( 'comment_feed_limits', array( 'LIMIT ' . get_option('posts_per_rss'), &$this ) );
    28142898                        }
    28152899                        $cgroupby = ( ! empty( $cgroupby ) ) ? 'GROUP BY ' . $cgroupby : '';
    28162900                        $corderby = ( ! empty( $corderby ) ) ? 'ORDER BY ' . $corderby : '';
     
    28332917
    28342918                $pieces = array( 'where', 'groupby', 'join', 'orderby', 'distinct', 'fields', 'limits' );
    28352919
    2836                 // Apply post-paging filters on where and join. Only plugins that
    2837                 // manipulate paging queries should use these hooks.
    28382920                if ( !$q['suppress_filters'] ) {
     2921                        /**
     2922                         * Filter the WHERE clause of the query.
     2923                         *
     2924                         * Specifically for manipulating paging queries.
     2925                         *
     2926                         * @since 1.5.2
     2927                         *
     2928                         * @param string   $where The WHERE clause of the query.
     2929                         * @param WP_Query &$this The WP_Query instance (passed by reference).
     2930                         */
    28392931                        $where          = apply_filters_ref_array( 'posts_where_paged', array( $where, &$this ) );
     2932
     2933                        /**
     2934                         * Filter the GROUP BY clause of the query.
     2935                         *
     2936                         * @since 2.0.0
     2937                         *
     2938                         * @param string   $groupby The GROUP BY clause of the query.
     2939                         * @param WP_Query &$this   The WP_Query instance (passed by reference).
     2940                         */
    28402941                        $groupby        = apply_filters_ref_array( 'posts_groupby',             array( $groupby, &$this ) );
     2942
     2943                        /**
     2944                         * Filter the JOIN clause of the query.
     2945                         *
     2946                         * Specifically for manipulating paging queries.
     2947                         *
     2948                         * @since 1.5.2
     2949                         *
     2950                         * @param string   $join  The JOIN clause of the query.
     2951                         * @param WP_Query &$this The WP_Query instance (passed by reference).
     2952                         */
    28412953                        $join           = apply_filters_ref_array( 'posts_join_paged',  array( $join, &$this ) );
     2954
     2955                        /**
     2956                         * Filter the ORDER BY clause of the query.
     2957                         *
     2958                         * @since 1.5.2
     2959                         *
     2960                         * @param string   $orderby The ORDER BY clause of the query.
     2961                         * @param WP_Query &$this   The WP_Query instance (passed by reference).
     2962                         */
    28422963                        $orderby        = apply_filters_ref_array( 'posts_orderby',             array( $orderby, &$this ) );
     2964
     2965                        /**
     2966                         * Filter the DISTINCT clause of the query.
     2967                         *
     2968                         * @since 2.1.0
     2969                         *
     2970                         * @param string   $distinct The DISTINCT clause of the query.
     2971                         * @param WP_Query &$this    The WP_Query instance (passed by reference).
     2972                         */
    28432973                        $distinct       = apply_filters_ref_array( 'posts_distinct',    array( $distinct, &$this ) );
     2974
     2975                        /**
     2976                         * Filter the LIMIT clause of the query.
     2977                         *
     2978                         * @since 2.1.0
     2979                         *
     2980                         * @param string   $limits The LIMIT clause of the query.
     2981                         * @param WP_Query &$this  The WP_Query instance (passed by reference).
     2982                         */
    28442983                        $limits         = apply_filters_ref_array( 'post_limits',               array( $limits, &$this ) );
     2984
     2985                        /**
     2986                         * Filter the SELECT clause of the query.
     2987                         *
     2988                         * @since 2.1.0
     2989                         *
     2990                         * @param string   $fields The SELECT clause of the query.
     2991                         * @param WP_Query &$this  The WP_Query instance (passed by reference).
     2992                         */
    28452993                        $fields         = apply_filters_ref_array( 'posts_fields',              array( $fields, &$this ) );
    28462994
    2847                         // Filter all clauses at once, for convenience
    2848                         $clauses = (array) apply_filters_ref_array( 'posts_clauses', array( compact( $pieces ), &$this ) );
     2995                        $clauses = compact( $pieces );
     2996                        /**
     2997                         * Filter all clauses at once, for convenience.
     2998                         *
     2999                         * Covers the WHERE, GROUP BY, JOIN, ORDER BY, DISTINCT,
     3000                         * fields (SELECT), and LIMITS clauses.
     3001                         *
     3002                         * @since 3.1.0
     3003                         *
     3004                         * @param array    $clauses The list of clauses for the query.
     3005                         * @param WP_Query &$this  The WP_Query instance (passed by reference).
     3006                         */
     3007                        $clauses = (array) apply_filters_ref_array( 'posts_clauses', array( $clauses, &$this ) );
     3008
    28493009                        foreach ( $pieces as $piece )
    28503010                                $$piece = isset( $clauses[ $piece ] ) ? $clauses[ $piece ] : '';
    28513011                }
    28523012
    2853                 // Announce current selection parameters. For use by caching plugins.
    2854                 do_action( 'posts_selection', $where . $groupby . $orderby . $limits . $join );
     3013                $selection = $where . $groupby . $orderby . $limits . $join;
     3014                /**
     3015                 * Fires to announce current selection parameters.
     3016                 *
     3017                 * For use by caching plugins.
     3018                 *
     3019                 * @since 2.3.0
     3020                 *
     3021                 * @param string $selection The assembled selection query.
     3022                 */
     3023                do_action( 'posts_selection', $selection );
    28553024
    28563025                // Filter again for the benefit of caching plugins. Regular plugins should use the hooks above.
    28573026                if ( !$q['suppress_filters'] ) {
     3027                        /**
     3028                         * Filter the WHERE clause of the query.
     3029                         *
     3030                         * For use by caching plugins.
     3031                         *
     3032                         * @since 2.5.0
     3033                         *
     3034                         * @param string   $where The WHERE clause of the query.
     3035                         * @param WP_Query &$this The WP_Query instance (passed by reference).
     3036                         */
    28583037                        $where          = apply_filters_ref_array( 'posts_where_request',               array( $where, &$this ) );
     3038
     3039                        /**
     3040                         * Filter the GROUP BY clause of the query.
     3041                         *
     3042                         * For use by caching plugins.
     3043                         *
     3044                         * @since 2.5.0
     3045                         *
     3046                         * @param string   $groupby The GROUP BY clause of the query.
     3047                         * @param WP_Query &$this   The WP_Query instance (passed by reference).
     3048                         */
    28593049                        $groupby        = apply_filters_ref_array( 'posts_groupby_request',             array( $groupby, &$this ) );
     3050
     3051                        /**
     3052                         * Filter the JOIN clause of the query.
     3053                         *
     3054                         * For use by caching plugins.
     3055                         *
     3056                         * @since 2.5.0
     3057                         *
     3058                         * @param string   $join  The JOIN clause of the query.
     3059                         * @param WP_Query &$this The WP_Query instance (passed by reference).
     3060                         */
    28603061                        $join           = apply_filters_ref_array( 'posts_join_request',                array( $join, &$this ) );
     3062
     3063                        /**
     3064                         * Filter the ORDER BY clause of the query.
     3065                         *
     3066                         * For use by caching plugins.
     3067                         *
     3068                         * @since 2.5.0
     3069                         *
     3070                         * @param string   $orderby The ORDER BY clause of the query.
     3071                         * @param WP_Query &$this   The WP_Query instance (passed by reference).
     3072                         */
    28613073                        $orderby        = apply_filters_ref_array( 'posts_orderby_request',             array( $orderby, &$this ) );
     3074
     3075                        /**
     3076                         * Filter the DISTINCT clause of the query.
     3077                         *
     3078                         * For use by caching plugins.
     3079                         *
     3080                         * @since 2.5.0
     3081                         *
     3082                         * @param string   $distinct The DISTINCT clause of the query.
     3083                         * @param WP_Query &$this    The WP_Query instance (passed by reference).
     3084                         */
    28623085                        $distinct       = apply_filters_ref_array( 'posts_distinct_request',    array( $distinct, &$this ) );
     3086
     3087                        /**
     3088                         * Filter the SELECT clause of the query.
     3089                         *
     3090                         * For use by caching plugins.
     3091                         *
     3092                         * @since 2.5.0
     3093                         *
     3094                         * @param string   $fields The SELECT clause of the query.
     3095                         * @param WP_Query &$this  The WP_Query instance (passed by reference).
     3096                         */
    28633097                        $fields         = apply_filters_ref_array( 'posts_fields_request',              array( $fields, &$this ) );
     3098
     3099                        /**
     3100                         * Filter the LIMIT clause of the query.
     3101                         *
     3102                         * For use by caching plugins.
     3103                         *
     3104                         * @since 2.5.0
     3105                         *
     3106                         * @param string   $limits The LIMIT clause of the query.
     3107                         * @param WP_Query &$this  The WP_Query instance (passed by reference).
     3108                         */
    28643109                        $limits         = apply_filters_ref_array( 'post_limits_request',               array( $limits, &$this ) );
    28653110
    2866                         // Filter all clauses at once, for convenience
    2867                         $clauses = (array) apply_filters_ref_array( 'posts_clauses_request', array( compact( $pieces ), &$this ) );
     3111                        $clauses = compact( $pieces );
     3112                        /**
     3113                         * Filter all clauses at once, for convenience.
     3114                         *
     3115                         * For use by caching plugins.
     3116                         *
     3117                         * Covers the WHERE, GROUP BY, JOIN, ORDER BY, DISTINCT,
     3118                         * fields (SELECT), and LIMITS clauses.
     3119                         *
     3120                         * @since 3.1.0
     3121                         *
     3122                         * @param array    $pieces The pieces of the query.
     3123                         * @param WP_Query &$this  The WP_Query instance (passed by reference).
     3124                         */
     3125                        $clauses = (array) apply_filters_ref_array( 'posts_clauses_request', array( $clauses, &$this ) );
    28683126                        foreach ( $pieces as $piece )
    28693127                                $$piece = isset( $clauses[ $piece ] ) ? $clauses[ $piece ] : '';
    28703128                }
     
    28813139                $this->request = $old_request = "SELECT $found_rows $distinct $fields FROM $wpdb->posts $join WHERE 1=1 $where $groupby $orderby $limits";
    28823140
    28833141                if ( !$q['suppress_filters'] ) {
    2884                         $this->request = apply_filters_ref_array( 'posts_request', array( $this->request, &$this ) );
     3142                        $request = $this->request;
     3143                        /**
     3144                         * Filter the completed SQL query before sending.
     3145                         *
     3146                         * @since 2.0.0
     3147                         *
     3148                         * @param array    $request The complete SQL query.
     3149                         * @param WP_Query &$this   The WP_Query instance (passed by reference).
     3150                         */
     3151                        $this->request = apply_filters_ref_array( 'posts_request', array( $request, &$this ) );
    28853152                }
    28863153
    28873154                if ( 'ids' == $q['fields'] ) {
     
    29053172                }
    29063173
    29073174                $split_the_query = ( $old_request == $this->request && "$wpdb->posts.*" == $fields && !empty( $limits ) && $q['posts_per_page'] < 500 );
     3175
     3176                /**
     3177                 * Filter the $split_the_query boolean.
     3178                 *
     3179                 * Splitting the query will cause it to fetch just the IDs of the found posts
     3180                 * (and then individually fetch each post by ID), rather than fetching every
     3181                 * complete row at once. One massive result vs. many small results.
     3182                 *
     3183                 * @since 3.4.0
     3184                 *
     3185                 * @param bool     $split_the_query Whether or not to split the query.
     3186                 * @param WP_Query $this            The WP_Query instance.
     3187                 */
    29083188                $split_the_query = apply_filters( 'split_the_query', $split_the_query, $this );
    29093189
    29103190                if ( $split_the_query ) {
     
    29123192
    29133193                        $this->request = "SELECT $found_rows $distinct $wpdb->posts.ID FROM $wpdb->posts $join WHERE 1=1 $where $groupby $orderby $limits";
    29143194
    2915                         $this->request = apply_filters( 'posts_request_ids', $this->request, $this );
     3195                        $request = $this->request;
     3196                        /**
     3197                         * Filter the Post IDs SQL request before sending.
     3198                         *
     3199                         * @since 3.4.0
     3200                         *
     3201                         * @param string   $request The post ID request.
     3202                         * @param WP_Query $this    The WP_Query instance.
     3203                         */
     3204                        $this->request = apply_filters( 'posts_request_ids', $request, $this );
    29163205
    29173206                        $ids = $wpdb->get_col( $this->request );
    29183207
     
    29323221                if ( $this->posts )
    29333222                        $this->posts = array_map( 'get_post', $this->posts );
    29343223
    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 ) );
     3224                if ( !$q['suppress_filters'] ){
     3225                        $posts = $this->posts;
     3226                        /**
     3227                         * Filter the raw post results array, prior to status checks.
     3228                         *
     3229                         * @since 2.3.0
     3230                         *
     3231                         * @param array    $posts The post results array.
     3232                         * @param WP_Query &$this The WP_Query instance (passed by reference).
     3233                         */
     3234                        $this->posts = apply_filters_ref_array( 'posts_results', array( $posts, &$this ) );
     3235                }
    29383236
    29393237                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 ) );
     3238                        // duplicate_hook
     3239                        $cjoin = apply_filters_ref_array( 'comment_feed_join', array( '', &$this ) );
     3240
     3241                        // duplicate_hook
     3242                        $cwhere = apply_filters_ref_array( 'comment_feed_where', array( "WHERE comment_post_ID = '{$this->posts[0]->ID}' AND comment_approved = '1'", &$this ) );
     3243
     3244                        // duplicate_hook
     3245                        $cgroupby = apply_filters_ref_array( 'comment_feed_groupby', array( '', &$this ) );
    29433246                        $cgroupby = ( ! empty( $cgroupby ) ) ? 'GROUP BY ' . $cgroupby : '';
    2944                         $corderby = apply_filters_ref_array('comment_feed_orderby', array( 'comment_date_gmt DESC', &$this ) );
     3247
     3248                        // duplicate_hook
     3249                        $corderby = apply_filters_ref_array( 'comment_feed_orderby', array( 'comment_date_gmt DESC', &$this ) );
    29453250                        $corderby = ( ! empty( $corderby ) ) ? 'ORDER BY ' . $corderby : '';
    2946                         $climits = apply_filters_ref_array('comment_feed_limits', array( 'LIMIT ' . get_option('posts_per_rss'), &$this ) );
     3251
     3252                        // duplicate_hook
     3253                        $climits = apply_filters_ref_array( 'comment_feed_limits', array( 'LIMIT ' . get_option('posts_per_rss'), &$this ) );
     3254
    29473255                        $comments_request = "SELECT $wpdb->comments.* FROM $wpdb->comments $cjoin $cwhere $cgroupby $corderby $climits";
    29483256                        $this->comments = $wpdb->get_results($comments_request);
    29493257                        $this->comment_count = count($this->comments);
     
    29773285                                }
    29783286                        }
    29793287
    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 ) ) );
     3288                        if ( $this->is_preview && $this->posts && current_user_can( $edit_cap, $this->posts[0]->ID ) ){
     3289                                $post_preview = $this->posts[0];
     3290                                /**
     3291                                 * Filter the single post for preview mode.
     3292                                 *
     3293                                 * @since 2.7.0
     3294                                 *
     3295                                 * @param WP_Post  $post_preview  The Post object.
     3296                                 * @param WP_Query &$this         The WP_Query instance (passed by reference).
     3297                                 */
     3298                                $this->posts[0] = get_post( apply_filters_ref_array( 'the_preview', array( $post_preview, &$this ) ) );
     3299                        }
    29823300                }
    29833301
    29843302                // Put sticky posts at the top of the posts array
     
    30223340                        }
    30233341                }
    30243342
    3025                 if ( !$q['suppress_filters'] )
    3026                         $this->posts = apply_filters_ref_array('the_posts', array( $this->posts, &$this ) );
     3343                if ( !$q['suppress_filters'] ){
     3344                        $posts = $this->posts;
     3345                        /**
     3346                         * Filter the array of retreived posts after they've been fetched and
     3347                         * internally processed.
     3348                         *
     3349                         * @since 1.5.2
     3350                         *
     3351                         * @param array    $posts The array of retrieved posts.
     3352                         * @param WP_Query &$this The WP_Query instance (passed by reference).
     3353                         */
     3354                        $this->posts = apply_filters_ref_array( 'the_posts', array( $posts, &$this ) );
     3355                }
    30273356
    30283357                // Ensure that any posts added/modified via one of the filters above are
    30293358                // of the type WP_Post and are filtered.
     
    30593388                if ( $q['no_found_rows'] || ( is_array( $this->posts ) && ! $this->posts ) )
    30603389                        return;
    30613390
    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
     3391                if ( ! empty( $limits ) ){
     3392                        $found_posts = 'SELECT FOUND_ROWS()';
     3393                        /**
     3394                         * Filter the query to run for retrieving the found posts.
     3395                         *
     3396                         * @since 2.1.0
     3397                         *
     3398                         * @param string   $found_posts The query to run to find the found posts.
     3399                         * @param WP_Query &$this       The WP_Query instance (passed by reference).
     3400                         */
     3401                        $this->found_posts = $wpdb->get_var( apply_filters_ref_array( 'found_posts_query', array( $found_posts, &$this ) ) );
     3402                }
     3403                else{
    30653404                        $this->found_posts = count( $this->posts );
     3405                }
    30663406
    3067                 $this->found_posts = apply_filters_ref_array( 'found_posts', array( $this->found_posts, &$this ) );
     3407                $found_posts = $this->found_posts;
     3408                /**
     3409                 * Filter the number of found posts.
     3410                 *
     3411                 * @since 2.1.0
     3412                 *
     3413                 * @param int      $found_posts The number of posts found.
     3414                 * @param WP_Query &$this       The WP_Query instance (passed by reference).
     3415                 */
     3416                $this->found_posts = apply_filters_ref_array( 'found_posts', array( $found_posts, &$this ) );
    30683417
    30693418                if ( ! empty( $limits ) )
    30703419                        $this->max_num_pages = ceil( $this->found_posts / $q['posts_per_page'] );
     
    31023451                $this->in_the_loop = true;
    31033452
    31043453                if ( $this->current_post == -1 ) // loop has just started
    3105                         do_action_ref_array('loop_start', array(&$this));
     3454                        /**
     3455                         * Fires once the loop is started.
     3456                         *
     3457                         * @since 2.0.0
     3458                         *
     3459                         * @param WP_Query &$this The WP_Query instance (passed by reference).
     3460                         */
     3461                        do_action_ref_array( 'loop_start', array( &$this ) );
    31063462
    31073463                $post = $this->next_post();
    31083464                setup_postdata($post);
     
    31233479                if ( $this->current_post + 1 < $this->post_count ) {
    31243480                        return true;
    31253481                } elseif ( $this->current_post + 1 == $this->post_count && $this->post_count > 0 ) {
    3126                         do_action_ref_array('loop_end', array(&$this));
     3482                        /**
     3483                         * Fires once the loop has ended.
     3484                         *
     3485                         * @since 2.0.0
     3486                         *
     3487                         * @param WP_Query &$this The WP_Query instance (passed by reference).
     3488                         */
     3489                        do_action_ref_array( 'loop_end', array( &$this ) );
    31273490                        // Do some cleaning up after the loop
    31283491                        $this->rewind_posts();
    31293492                }
     
    31743537                $comment = $this->next_comment();
    31753538
    31763539                if ( $this->current_comment == 0 ) {
    3177                         do_action('comment_loop_start');
     3540                        /**
     3541                         * Fires once the comment loop is started.
     3542                         *
     3543                         * @since 2.2.0
     3544                         */
     3545                        do_action( 'comment_loop_start' );
    31783546                }
    31793547        }
    31803548
     
    39354303                $pages = array( $post->post_content );
    39364304        }
    39374305
    3938         do_action_ref_array('the_post', array(&$post));
     4306        /**
     4307         * Fires once the post data has been setup.
     4308         *
     4309         * @since 2.8.0
     4310         *
     4311         * @param WP_Post &$post The Post object (passed by reference).
     4312         */
     4313        do_action_ref_array( 'the_post', array( &$post ) );
    39394314
    39404315        return true;
    39414316}