Make WordPress Core

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

File WP_Query-hook-docs.2.diff, 18.7 KB (added by dougwollison, 10 years ago)

Updated "object" to "instance" when talking about $this.

  • 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 actions to be run 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 actions to be run 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 actions to run after parse_query and before get_posts actually begins.
     2163                 *
     2164                 * @since 2.0.0
     2165                 *
     2166                 * @param WP_Query &$this The WP_Query instance (passed by refrence).
     2167                 */
     2168                do_action_ref_array( 'pre_get_posts', array( &$this ) );
    21482169
    21492170                // Shorthand.
    21502171                $q = &$this->query_vars;
     
    27742795                // Apply filters on where and join prior to paging so that any
    27752796                // manipulations to them are reflected in the paging by day queries.
    27762797                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 ) );
     2798                        /**
     2799                         * Filter the WHERE portion of the posts query before sending.
     2800                         *
     2801                         * @since 1.5.2
     2802                         *
     2803                         * @param string   $where The WHERE portion of the query.
     2804                         * @param WP_Query &$this The WP_Query instance (passed by refrence).
     2805                         */
     2806                        $where = apply_filters_ref_array( 'posts_where', array( $where, &$this ) );
     2807
     2808                        /**
     2809                         * Filter the JOIN portion of the posts query before sending.
     2810                         *
     2811                         * @since 1.5.2
     2812                         *
     2813                         * @param string   $where The JOIN portion of the query.
     2814                         * @param WP_Query &$this The WP_Query instance (passed by refrence).
     2815                         */
     2816                        $join = apply_filters_ref_array( 'posts_join', array( $join, &$this ) );
    27792817                }
    27802818
    27812819                // Paging
     
    28062844                        }
    28072845
    28082846                        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 ) );
     2847                                /**
     2848                                 * Filter the JOIN portion of the comments feed query before sending.
     2849                                 *
     2850                                 * @since 1.5.2
     2851                                 *
     2852                                 * @param string   $cjoin The JOIN portion of the query.
     2853                                 * @param WP_Query &$this The WP_Query instance (passed by refrence).
     2854                                 */
     2855                                $cjoin = apply_filters_ref_array( 'comment_feed_join', array( $cjoin, &$this ) );
     2856
     2857                                /**
     2858                                 * Filter the WHERE portion of the comments feed query before sending.
     2859                                 *
     2860                                 * @since 1.5.2
     2861                                 *
     2862                                 * @param string   $cwhere The WHERE portion of the query.
     2863                                 * @param WP_Query &$this  The WP_Query instance (passed by refrence).
     2864                                 */
     2865                                $cwhere = apply_filters_ref_array( 'comment_feed_where', array( $cwhere, &$this ) );
     2866
     2867                                /**
     2868                                 * Filter the GROUP BY portion of the comments feed query before sending.
     2869                                 *
     2870                                 * @since 1.5.2
     2871                                 *
     2872                                 * @param string   $cgroupby The GROUP BY portion of the query.
     2873                                 * @param WP_Query &$this    The WP_Query instance (passed by refrence).
     2874                                 */
     2875                                $cgroupby = apply_filters_ref_array( 'comment_feed_groupby', array( $cgroupby, &$this ) );
     2876
     2877                                /**
     2878                                 * Filter the ORDER BY portion of the comments feed query before sending.
     2879                                 *
     2880                                 * @since 1.5.2
     2881                                 *
     2882                                 * @param string   $corderby The ORDER BY portion of the query.
     2883                                 * @param WP_Query &$this    The WP_Query instance (passed by refrence).
     2884                                 */
     2885                                $corderby = apply_filters_ref_array( 'comment_feed_orderby', array( 'comment_date_gmt DESC', &$this ) );
     2886
     2887                                /**
     2888                                 * Filter the LIMIT portion of the comments feed query before sending.
     2889                                 *
     2890                                 * @since 1.5.2
     2891                                 *
     2892                                 * @param string   $climits The JOIN portion of the query.
     2893                                 * @param WP_Query &$this   The WP_Query instance (passed by refrence).
     2894                                 */
     2895                                $climits = apply_filters_ref_array( 'comment_feed_limits', array( 'LIMIT ' . get_option('posts_per_rss'), &$this ) );
    28142896                        }
    28152897                        $cgroupby = ( ! empty( $cgroupby ) ) ? 'GROUP BY ' . $cgroupby : '';
    28162898                        $corderby = ( ! empty( $corderby ) ) ? 'ORDER BY ' . $corderby : '';
     
    28362918                // Apply post-paging filters on where and join. Only plugins that
    28372919                // manipulate paging queries should use these hooks.
    28382920                if ( !$q['suppress_filters'] ) {
     2921                        /**
     2922                         * Filter the WHERE portion of the posts query before sending.
     2923                         *
     2924                         * @since 1.5.2
     2925                         *
     2926                         * @param string   $where The WHERE portion of the query.
     2927                         * @param WP_Query &$this The WP_Query instance (passed by refrence).
     2928                         */
    28392929                        $where          = apply_filters_ref_array( 'posts_where_paged', array( $where, &$this ) );
     2930
     2931                        /**
     2932                         * Filter the GROUP BY portion of the posts query before sending.
     2933                         *
     2934                         * @since 2.0.0
     2935                         *
     2936                         * @param string   $groupby The GROUP BY portion of the query.
     2937                         * @param WP_Query &$this   The WP_Query instance (passed by refrence).
     2938                         */
    28402939                        $groupby        = apply_filters_ref_array( 'posts_groupby',             array( $groupby, &$this ) );
     2940
     2941                        /**
     2942                         * Filter the JOIN portion of the posts query before sending.
     2943                         *
     2944                         * @since 1.5.2
     2945                         *
     2946                         * @param string   $join  The JOIN portion of the query.
     2947                         * @param WP_Query &$this The WP_Query instance (passed by refrence).
     2948                         */
    28412949                        $join           = apply_filters_ref_array( 'posts_join_paged',  array( $join, &$this ) );
     2950
     2951                        /**
     2952                         * Filter the ORDER BY portion of the posts query before sending.
     2953                         *
     2954                         * @since 1.5.2
     2955                         *
     2956                         * @param string   $orderby The ORDER BY portion of the query.
     2957                         * @param WP_Query &$this   The WP_Query instance (passed by refrence).
     2958                         */
    28422959                        $orderby        = apply_filters_ref_array( 'posts_orderby',             array( $orderby, &$this ) );
     2960
     2961                        /**
     2962                         * Filter the DISTINCT portion of the posts query before sending.
     2963                         *
     2964                         * @since 2.1.0
     2965                         *
     2966                         * @param string   $distinct The DISTINCT portion of the query.
     2967                         * @param WP_Query &$this    The WP_Query instance (passed by refrence).
     2968                         */
    28432969                        $distinct       = apply_filters_ref_array( 'posts_distinct',    array( $distinct, &$this ) );
     2970
     2971                        /**
     2972                         * Filter the LIMIT portion of the posts query before sending.
     2973                         *
     2974                         * @since 2.1.0
     2975                         *
     2976                         * @param string   $limits The LIMIT portion of the query.
     2977                         * @param WP_Query &$this  The WP_Query instance (passed by refrence).
     2978                         */
    28442979                        $limits         = apply_filters_ref_array( 'post_limits',               array( $limits, &$this ) );
     2980
     2981                        /**
     2982                         * Filter the SELECT portion of the posts query before sending.
     2983                         *
     2984                         * @since 2.1.0
     2985                         *
     2986                         * @param string   $fields The SELECT portion of the query.
     2987                         * @param WP_Query &$this  The WP_Query instance (passed by refrence).
     2988                         */
    28452989                        $fields         = apply_filters_ref_array( 'posts_fields',              array( $fields, &$this ) );
    28462990
    2847                         // Filter all clauses at once, for convenience
     2991                        /**
     2992                         * Filter all clauses at once, for convenience.
     2993                         *
     2994                         * @since 3.1.0
     2995                         *
     2996                         * @param array    $pieces The pieces of the query.
     2997                         * @param WP_Query &$this  The WP_Query instance (passed by refrence).
     2998                         */
    28482999                        $clauses = (array) apply_filters_ref_array( 'posts_clauses', array( compact( $pieces ), &$this ) );
     3000
    28493001                        foreach ( $pieces as $piece )
    28503002                                $$piece = isset( $clauses[ $piece ] ) ? $clauses[ $piece ] : '';
    28513003                }
    28523004
    28533005                // Announce current selection parameters. For use by caching plugins.
     3006                /**
     3007                 * Fires actions to be run once post selection preperation has been completed.
     3008                 *
     3009                 * Largely for use by caching plugins.
     3010                 *
     3011                 * @since 2.3.0
     3012                 *
     3013                 * @param string $selection The assembled selection query.
     3014                 */
    28543015                do_action( 'posts_selection', $where . $groupby . $orderby . $limits . $join );
    28553016
    28563017                // Filter again for the benefit of caching plugins. Regular plugins should use the hooks above.
    28573018                if ( !$q['suppress_filters'] ) {
     3019                        /**
     3020                         * Filter the WHERE portion of the posts query before sending.
     3021                         *
     3022                         * @since 2.5.0
     3023                         *
     3024                         * @param string   $where The WHERE portion of the query.
     3025                         * @param WP_Query &$this The WP_Query instance (passed by refrence).
     3026                         */
    28583027                        $where          = apply_filters_ref_array( 'posts_where_request',               array( $where, &$this ) );
     3028
     3029                        /**
     3030                         * Filter the GROUP BY portion of the posts query before sending.
     3031                         *
     3032                         * @since 2.5.0
     3033                         *
     3034                         * @param string   $groupby The GROUP BY portion of the query.
     3035                         * @param WP_Query &$this   The WP_Query instance (passed by refrence).
     3036                         */
    28593037                        $groupby        = apply_filters_ref_array( 'posts_groupby_request',             array( $groupby, &$this ) );
     3038
     3039                        /**
     3040                         * Filter the JOIN portion of the posts query before sending.
     3041                         *
     3042                         * @since 2.5.0
     3043                         *
     3044                         * @param string   $join  The JOIN portion of the query.
     3045                         * @param WP_Query &$this The WP_Query instance (passed by refrence).
     3046                         */
    28603047                        $join           = apply_filters_ref_array( 'posts_join_request',                array( $join, &$this ) );
     3048
     3049                        /**
     3050                         * Filter the ORDER BY portion of the posts query before sending.
     3051                         *
     3052                         * @since 2.5.0
     3053                         *
     3054                         * @param string   $orderby The ORDER BY portion of the query.
     3055                         * @param WP_Query &$this   The WP_Query instance (passed by refrence).
     3056                         */
    28613057                        $orderby        = apply_filters_ref_array( 'posts_orderby_request',             array( $orderby, &$this ) );
     3058
     3059                        /**
     3060                         * Filter the DISTINCT portion of the posts query before sending.
     3061                         *
     3062                         * @since 2.5.0
     3063                         *
     3064                         * @param string   $distinct The DISTINCT portion of the query.
     3065                         * @param WP_Query &$this    The WP_Query instance (passed by refrence).
     3066                         */
    28623067                        $distinct       = apply_filters_ref_array( 'posts_distinct_request',    array( $distinct, &$this ) );
     3068
     3069                        /**
     3070                         * Filter the SELECT portion of the posts query before sending.
     3071                         *
     3072                         * @since 2.5.0
     3073                         *
     3074                         * @param string   $fields The SELECT portion of the query.
     3075                         * @param WP_Query &$this  The WP_Query instance (passed by refrence).
     3076                         */
    28633077                        $fields         = apply_filters_ref_array( 'posts_fields_request',              array( $fields, &$this ) );
     3078
     3079                        /**
     3080                         * Filter the LIMIT portion of the posts query before sending.
     3081                         *
     3082                         * @since 2.5.0
     3083                         *
     3084                         * @param string   $limits The LIMIT portion of the query.
     3085                         * @param WP_Query &$this  The WP_Query instance (passed by refrence).
     3086                         */
    28643087                        $limits         = apply_filters_ref_array( 'post_limits_request',               array( $limits, &$this ) );
    28653088
    2866                         // Filter all clauses at once, for convenience
     3089                        /**
     3090                         * Filter all clauses at once, for convenience.
     3091                         *
     3092                         * @since 3.1.0
     3093                         *
     3094                         * @param array    $pieces The pieces of the query.
     3095                         * @param WP_Query &$this  The WP_Query instance (passed by refrence).
     3096                         */
    28673097                        $clauses = (array) apply_filters_ref_array( 'posts_clauses_request', array( compact( $pieces ), &$this ) );
    28683098                        foreach ( $pieces as $piece )
    28693099                                $$piece = isset( $clauses[ $piece ] ) ? $clauses[ $piece ] : '';
     
    28813111                $this->request = $old_request = "SELECT $found_rows $distinct $fields FROM $wpdb->posts $join WHERE 1=1 $where $groupby $orderby $limits";
    28823112
    28833113                if ( !$q['suppress_filters'] ) {
     3114                        /**
     3115                         * Filter the completed SQL query before sending.
     3116                         *
     3117                         * @since 2.0.0
     3118                         *
     3119                         * @param array    $request The complete SQL query.
     3120                         * @param WP_Query &$this   The WP_Query instance (passed by refrence).
     3121                         */
    28843122                        $this->request = apply_filters_ref_array( 'posts_request', array( $this->request, &$this ) );
    28853123                }
    28863124
     
    29053143                }
    29063144
    29073145                $split_the_query = ( $old_request == $this->request && "$wpdb->posts.*" == $fields && !empty( $limits ) && $q['posts_per_page'] < 500 );
     3146
     3147                /**
     3148                 * Filter the $split_the_query boolean.
     3149                 *
     3150                 * @since 3.4.0
     3151                 *
     3152                 * @param bool     $split_the_query Whether or not to split the query.
     3153                 * @param WP_Query $this            The WP_Query instance.
     3154                 */
    29083155                $split_the_query = apply_filters( 'split_the_query', $split_the_query, $this );
    29093156
    29103157                if ( $split_the_query ) {
     
    29123159
    29133160                        $this->request = "SELECT $found_rows $distinct $wpdb->posts.ID FROM $wpdb->posts $join WHERE 1=1 $where $groupby $orderby $limits";
    29143161
     3162                        /**
     3163                         * Filter the Post ID request before sending.
     3164                         *
     3165                         * @since 3.4.0
     3166                         *
     3167                         * @param string   $request The post ID request.
     3168                         * @param WP_Query $this    The WP_Query instance.
     3169                         */
    29153170                        $this->request = apply_filters( 'posts_request_ids', $this->request, $this );
    29163171
    29173172                        $ids = $wpdb->get_col( $this->request );
     
    29323187                if ( $this->posts )
    29333188                        $this->posts = array_map( 'get_post', $this->posts );
    29343189
    2935                 // Raw results filter. Prior to status checks.
    29363190                if ( !$q['suppress_filters'] )
    2937                         $this->posts = apply_filters_ref_array('posts_results', array( $this->posts, &$this ) );
     3191                        /**
     3192                         * Filter the raw post results array, prior to status checks.
     3193                         *
     3194                         * @since 2.3.0
     3195                         *
     3196                         * @param array    $posts The post results array.
     3197                         * @param WP_Query &$this The WP_Query instance (passed by reference).
     3198                         */
     3199                        $this->posts = apply_filters_ref_array( 'posts_results', array( $this->posts, &$this ) );
    29383200
    29393201                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 ) );
     3202                        // duplicate_hook
     3203                        $cjoin = apply_filters_ref_array( 'comment_feed_join', array( '', &$this ) );
     3204
     3205                        // duplicate_hook
     3206                        $cwhere = apply_filters_ref_array( 'comment_feed_where', array( "WHERE comment_post_ID = '{$this->posts[0]->ID}' AND comment_approved = '1'", &$this ) );
     3207
     3208                        // duplicate_hook
     3209                        $cgroupby = apply_filters_ref_array( 'comment_feed_groupby', array( '', &$this ) );
    29433210                        $cgroupby = ( ! empty( $cgroupby ) ) ? 'GROUP BY ' . $cgroupby : '';
    2944                         $corderby = apply_filters_ref_array('comment_feed_orderby', array( 'comment_date_gmt DESC', &$this ) );
     3211
     3212                        // duplicate_hook
     3213                        $corderby = apply_filters_ref_array( 'comment_feed_orderby', array( 'comment_date_gmt DESC', &$this ) );
    29453214                        $corderby = ( ! empty( $corderby ) ) ? 'ORDER BY ' . $corderby : '';
    2946                         $climits = apply_filters_ref_array('comment_feed_limits', array( 'LIMIT ' . get_option('posts_per_rss'), &$this ) );
     3215
     3216                        // duplicate_hook
     3217                        $climits = apply_filters_ref_array( 'comment_feed_limits', array( 'LIMIT ' . get_option('posts_per_rss'), &$this ) );
     3218
    29473219                        $comments_request = "SELECT $wpdb->comments.* FROM $wpdb->comments $cjoin $cwhere $cgroupby $corderby $climits";
    29483220                        $this->comments = $wpdb->get_results($comments_request);
    29493221                        $this->comment_count = count($this->comments);
     
    29783250                        }
    29793251
    29803252                        if ( $this->is_preview && $this->posts && current_user_can( $edit_cap, $this->posts[0]->ID ) )
     3253                                /**
     3254                                 * Filter the single post for preview mode.
     3255                                 *
     3256                                 * @since 2.7.0
     3257                                 *
     3258                                 * @param WP_Post  $post  The Post object.
     3259                                 * @param WP_Query &$this The WP_Query instance (passed by reference).
     3260                                 */
    29813261                                $this->posts[0] = get_post( apply_filters_ref_array( 'the_preview', array( $this->posts[0], &$this ) ) );
    29823262                }
    29833263
     
    30233303                }
    30243304
    30253305                if ( !$q['suppress_filters'] )
    3026                         $this->posts = apply_filters_ref_array('the_posts', array( $this->posts, &$this ) );
     3306                        /**
     3307                         * Filter the array of retreived posts after they've been fetched and
     3308                         * internally processed.
     3309                         *
     3310                         * @since 1.5.2
     3311                         *
     3312                         * @param array    $posts The array of retrieved posts.
     3313                         * @param WP_Query &$this The WP_Query instance (passed by reference).
     3314                         */
     3315                        $this->posts = apply_filters_ref_array( 'the_posts', array( $this->posts, &$this ) );
    30273316
    30283317                // Ensure that any posts added/modified via one of the filters above are
    30293318                // of the type WP_Post and are filtered.
     
    30603349                        return;
    30613350
    30623351                if ( ! empty( $limits ) )
     3352                        /**
     3353                         * Filter the query to run for retrieving the found posts.
     3354                         *
     3355                         * @since 2.1.0
     3356                         *
     3357                         * @param string   $query The query to run to find the found posts.
     3358                         * @param WP_Query &$this The WP_Query instance (passed by reference).
     3359                         */
    30633360                        $this->found_posts = $wpdb->get_var( apply_filters_ref_array( 'found_posts_query', array( 'SELECT FOUND_ROWS()', &$this ) ) );
    30643361                else
    30653362                        $this->found_posts = count( $this->posts );
    30663363
     3364                /**
     3365                 * Filter the number of found posts.
     3366                 *
     3367                 * @since 2.1.0
     3368                 *
     3369                 * @param int      $found_posts The number of posts found.
     3370                 * @param WP_Query &$this       The WP_Query instance (passed by reference).
     3371                 */
    30673372                $this->found_posts = apply_filters_ref_array( 'found_posts', array( $this->found_posts, &$this ) );
    30683373
    30693374                if ( ! empty( $limits ) )
     
    31023407                $this->in_the_loop = true;
    31033408
    31043409                if ( $this->current_post == -1 ) // loop has just started
    3105                         do_action_ref_array('loop_start', array(&$this));
     3410                        /**
     3411                         * Fires actions to be run once the loop is started.
     3412                         *
     3413                         * @since 2.0.0
     3414                         *
     3415                         * @param WP_Query &$this The WP_Query instance (passed by reference).
     3416                         */
     3417                        do_action_ref_array( 'loop_start', array( &$this ) );
    31063418
    31073419                $post = $this->next_post();
    31083420                setup_postdata($post);
     
    31233435                if ( $this->current_post + 1 < $this->post_count ) {
    31243436                        return true;
    31253437                } elseif ( $this->current_post + 1 == $this->post_count && $this->post_count > 0 ) {
    3126                         do_action_ref_array('loop_end', array(&$this));
     3438                        /**
     3439                         * Fires actions to be run once the loop has ended.
     3440                         *
     3441                         * @since 2.0.0
     3442                         *
     3443                         * @param WP_Query &$this The WP_Query instance (passed by reference).
     3444                         */
     3445                        do_action_ref_array( 'loop_end', array( &$this ) );
    31273446                        // Do some cleaning up after the loop
    31283447                        $this->rewind_posts();
    31293448                }
     
    31743493                $comment = $this->next_comment();
    31753494
    31763495                if ( $this->current_comment == 0 ) {
    3177                         do_action('comment_loop_start');
     3496                        /**
     3497                         * Fires actions to be run once the comment loop is started.
     3498                         *
     3499                         * @since 2.2.0
     3500                         */
     3501                        do_action( 'comment_loop_start' );
    31783502                }
    31793503        }
    31803504
     
    39354259                $pages = array( $post->post_content );
    39364260        }
    39374261
    3938         do_action_ref_array('the_post', array(&$post));
     4262        /**
     4263         * Fires actions to be run once the post data has been setup.
     4264         *
     4265         * @since 2.8.0
     4266         *
     4267         * @param WP_Post &$post The Post object (passed by reference).
     4268         */
     4269        do_action_ref_array( 'the_post', array( &$post ) );
    39394270
    39404271        return true;
    39414272}