Ticket #25514: WP_Query-hook-docs.3.diff
| File WP_Query-hook-docs.3.diff, 20.2 KB (added by , 9 years ago) |
|---|
-
wp-includes/query.php
1709 1709 $this->query_vars_hash = md5( serialize( $this->query_vars ) ); 1710 1710 $this->query_vars_changed = false; 1711 1711 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 ) ); 1713 1720 } 1714 1721 1715 1722 /* … … 1903 1910 1904 1911 $this->tax_query = new WP_Tax_Query( $tax_query ); 1905 1912 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 */ 1906 1920 do_action( 'parse_tax_query', $this ); 1907 1921 } 1908 1922 … … 2144 2158 2145 2159 $this->parse_query(); 2146 2160 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 ) ); 2148 2171 2149 2172 // Shorthand. 2150 2173 $q = &$this->query_vars; … … 2774 2797 // Apply filters on where and join prior to paging so that any 2775 2798 // manipulations to them are reflected in the paging by day queries. 2776 2799 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 ) ); 2779 2819 } 2780 2820 2781 2821 // Paging … … 2806 2846 } 2807 2847 2808 2848 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 ) ); 2814 2898 } 2815 2899 $cgroupby = ( ! empty( $cgroupby ) ) ? 'GROUP BY ' . $cgroupby : ''; 2816 2900 $corderby = ( ! empty( $corderby ) ) ? 'ORDER BY ' . $corderby : ''; … … 2833 2917 2834 2918 $pieces = array( 'where', 'groupby', 'join', 'orderby', 'distinct', 'fields', 'limits' ); 2835 2919 2836 // Apply post-paging filters on where and join. Only plugins that2837 // manipulate paging queries should use these hooks.2838 2920 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 */ 2839 2931 $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 */ 2840 2941 $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 */ 2841 2953 $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 */ 2842 2963 $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 */ 2843 2973 $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 */ 2844 2983 $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 */ 2845 2993 $fields = apply_filters_ref_array( 'posts_fields', array( $fields, &$this ) ); 2846 2994 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 * @since 3.1.0 3000 * 3001 * @param array $clauses The list of clauses for the query. 3002 * @param WP_Query &$this The WP_Query instance (passed by reference). 3003 */ 3004 $clauses = (array) apply_filters_ref_array( 'posts_clauses', array( $clauses, &$this ) ); 3005 2849 3006 foreach ( $pieces as $piece ) 2850 3007 $$piece = isset( $clauses[ $piece ] ) ? $clauses[ $piece ] : ''; 2851 3008 } 2852 3009 2853 // Announce current selection parameters. For use by caching plugins. 2854 do_action( 'posts_selection', $where . $groupby . $orderby . $limits . $join ); 3010 $selection = $where . $groupby . $orderby . $limits . $join; 3011 /** 3012 * Fires to announce current selection parameters. 3013 * 3014 * For use by caching plugins. 3015 * 3016 * @since 2.3.0 3017 * 3018 * @param string $selection The assembled selection query. 3019 */ 3020 do_action( 'posts_selection', $selection ); 2855 3021 2856 3022 // Filter again for the benefit of caching plugins. Regular plugins should use the hooks above. 2857 3023 if ( !$q['suppress_filters'] ) { 3024 /** 3025 * Filter the WHERE clause of the query. 3026 * 3027 * @since 2.5.0 3028 * 3029 * @param string $where The WHERE clause of the query. 3030 * @param WP_Query &$this The WP_Query instance (passed by reference). 3031 */ 2858 3032 $where = apply_filters_ref_array( 'posts_where_request', array( $where, &$this ) ); 3033 3034 /** 3035 * Filter the GROUP BY clause of the query. 3036 * 3037 * @since 2.5.0 3038 * 3039 * @param string $groupby The GROUP BY clause of the query. 3040 * @param WP_Query &$this The WP_Query instance (passed by reference). 3041 */ 2859 3042 $groupby = apply_filters_ref_array( 'posts_groupby_request', array( $groupby, &$this ) ); 3043 3044 /** 3045 * Filter the JOIN clause of the query. 3046 * 3047 * @since 2.5.0 3048 * 3049 * @param string $join The JOIN clause of the query. 3050 * @param WP_Query &$this The WP_Query instance (passed by reference). 3051 */ 2860 3052 $join = apply_filters_ref_array( 'posts_join_request', array( $join, &$this ) ); 3053 3054 /** 3055 * Filter the ORDER BY clause of the query. 3056 * 3057 * @since 2.5.0 3058 * 3059 * @param string $orderby The ORDER BY clause of the query. 3060 * @param WP_Query &$this The WP_Query instance (passed by reference). 3061 */ 2861 3062 $orderby = apply_filters_ref_array( 'posts_orderby_request', array( $orderby, &$this ) ); 3063 3064 /** 3065 * Filter the DISTINCT clause of the query. 3066 * 3067 * @since 2.5.0 3068 * 3069 * @param string $distinct The DISTINCT clause of the query. 3070 * @param WP_Query &$this The WP_Query instance (passed by reference). 3071 */ 2862 3072 $distinct = apply_filters_ref_array( 'posts_distinct_request', array( $distinct, &$this ) ); 3073 3074 /** 3075 * Filter the SELECT clause of the query. 3076 * 3077 * @since 2.5.0 3078 * 3079 * @param string $fields The SELECT clause of the query. 3080 * @param WP_Query &$this The WP_Query instance (passed by reference). 3081 */ 2863 3082 $fields = apply_filters_ref_array( 'posts_fields_request', array( $fields, &$this ) ); 3083 3084 /** 3085 * Filter the LIMIT clause of the query. 3086 * 3087 * @since 2.5.0 3088 * 3089 * @param string $limits The LIMIT clause of the query. 3090 * @param WP_Query &$this The WP_Query instance (passed by reference). 3091 */ 2864 3092 $limits = apply_filters_ref_array( 'post_limits_request', array( $limits, &$this ) ); 2865 3093 2866 // Filter all clauses at once, for convenience 3094 /** 3095 * Filter all clauses at once, for convenience. 3096 * 3097 * @since 3.1.0 3098 * 3099 * @param array $pieces The pieces of the query. 3100 * @param WP_Query &$this The WP_Query instance (passed by reference). 3101 */ 2867 3102 $clauses = (array) apply_filters_ref_array( 'posts_clauses_request', array( compact( $pieces ), &$this ) ); 2868 3103 foreach ( $pieces as $piece ) 2869 3104 $$piece = isset( $clauses[ $piece ] ) ? $clauses[ $piece ] : ''; … … 2881 3116 $this->request = $old_request = "SELECT $found_rows $distinct $fields FROM $wpdb->posts $join WHERE 1=1 $where $groupby $orderby $limits"; 2882 3117 2883 3118 if ( !$q['suppress_filters'] ) { 2884 $this->request = apply_filters_ref_array( 'posts_request', array( $this->request, &$this ) ); 3119 $request = $this->request; 3120 /** 3121 * Filter the completed SQL query before sending. 3122 * 3123 * @since 2.0.0 3124 * 3125 * @param array $request The complete SQL query. 3126 * @param WP_Query &$this The WP_Query instance (passed by reference). 3127 */ 3128 $this->request = apply_filters_ref_array( 'posts_request', array( $request, &$this ) ); 2885 3129 } 2886 3130 2887 3131 if ( 'ids' == $q['fields'] ) { … … 2905 3149 } 2906 3150 2907 3151 $split_the_query = ( $old_request == $this->request && "$wpdb->posts.*" == $fields && !empty( $limits ) && $q['posts_per_page'] < 500 ); 3152 3153 /** 3154 * Filter the $split_the_query boolean. 3155 * 3156 * Splitting the query will cause it to fetch just the IDs of the found posts 3157 * (and then individually fetch each post by ID), rather than fetching every 3158 * complete row at once. One massive result vs. many small results. 3159 * 3160 * @since 3.4.0 3161 * 3162 * @param bool $split_the_query Whether or not to split the query. 3163 * @param WP_Query $this The WP_Query instance. 3164 */ 2908 3165 $split_the_query = apply_filters( 'split_the_query', $split_the_query, $this ); 2909 3166 2910 3167 if ( $split_the_query ) { … … 2912 3169 2913 3170 $this->request = "SELECT $found_rows $distinct $wpdb->posts.ID FROM $wpdb->posts $join WHERE 1=1 $where $groupby $orderby $limits"; 2914 3171 2915 $this->request = apply_filters( 'posts_request_ids', $this->request, $this ); 3172 $request = $this->request; 3173 /** 3174 * Filter the Post IDs SQL request before sending. 3175 * 3176 * @since 3.4.0 3177 * 3178 * @param string $request The post ID request. 3179 * @param WP_Query $this The WP_Query instance. 3180 */ 3181 $this->request = apply_filters( 'posts_request_ids', $request, $this ); 2916 3182 2917 3183 $ids = $wpdb->get_col( $this->request ); 2918 3184 … … 2932 3198 if ( $this->posts ) 2933 3199 $this->posts = array_map( 'get_post', $this->posts ); 2934 3200 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 ) ); 3201 if ( !$q['suppress_filters'] ){ 3202 $posts = $this->posts; 3203 /** 3204 * Filter the raw post results array, prior to status checks. 3205 * 3206 * @since 2.3.0 3207 * 3208 * @param array $posts The post results array. 3209 * @param WP_Query &$this The WP_Query instance (passed by reference). 3210 */ 3211 $this->posts = apply_filters_ref_array( 'posts_results', array( $posts, &$this ) ); 3212 } 2938 3213 2939 3214 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 ) ); 3215 // duplicate_hook 3216 $cjoin = apply_filters_ref_array( 'comment_feed_join', array( '', &$this ) ); 3217 3218 // duplicate_hook 3219 $cwhere = apply_filters_ref_array( 'comment_feed_where', array( "WHERE comment_post_ID = '{$this->posts[0]->ID}' AND comment_approved = '1'", &$this ) ); 3220 3221 // duplicate_hook 3222 $cgroupby = apply_filters_ref_array( 'comment_feed_groupby', array( '', &$this ) ); 2943 3223 $cgroupby = ( ! empty( $cgroupby ) ) ? 'GROUP BY ' . $cgroupby : ''; 2944 $corderby = apply_filters_ref_array('comment_feed_orderby', array( 'comment_date_gmt DESC', &$this ) ); 3224 3225 // duplicate_hook 3226 $corderby = apply_filters_ref_array( 'comment_feed_orderby', array( 'comment_date_gmt DESC', &$this ) ); 2945 3227 $corderby = ( ! empty( $corderby ) ) ? 'ORDER BY ' . $corderby : ''; 2946 $climits = apply_filters_ref_array('comment_feed_limits', array( 'LIMIT ' . get_option('posts_per_rss'), &$this ) ); 3228 3229 // duplicate_hook 3230 $climits = apply_filters_ref_array( 'comment_feed_limits', array( 'LIMIT ' . get_option('posts_per_rss'), &$this ) ); 3231 2947 3232 $comments_request = "SELECT $wpdb->comments.* FROM $wpdb->comments $cjoin $cwhere $cgroupby $corderby $climits"; 2948 3233 $this->comments = $wpdb->get_results($comments_request); 2949 3234 $this->comment_count = count($this->comments); … … 2977 3262 } 2978 3263 } 2979 3264 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 ) ) ); 3265 if ( $this->is_preview && $this->posts && current_user_can( $edit_cap, $this->posts[0]->ID ) ){ 3266 $post_preview = $this->posts[0]; 3267 /** 3268 * Filter the single post for preview mode. 3269 * 3270 * @since 2.7.0 3271 * 3272 * @param WP_Post $post_preview The Post object. 3273 * @param WP_Query &$this The WP_Query instance (passed by reference). 3274 */ 3275 $this->posts[0] = get_post( apply_filters_ref_array( 'the_preview', array( $post_preview, &$this ) ) ); 3276 } 2982 3277 } 2983 3278 2984 3279 // Put sticky posts at the top of the posts array … … 3022 3317 } 3023 3318 } 3024 3319 3025 if ( !$q['suppress_filters'] ) 3026 $this->posts = apply_filters_ref_array('the_posts', array( $this->posts, &$this ) ); 3320 if ( !$q['suppress_filters'] ){ 3321 $posts = $this->posts; 3322 /** 3323 * Filter the array of retreived posts after they've been fetched and 3324 * internally processed. 3325 * 3326 * @since 1.5.2 3327 * 3328 * @param array $posts The array of retrieved posts. 3329 * @param WP_Query &$this The WP_Query instance (passed by reference). 3330 */ 3331 $this->posts = apply_filters_ref_array( 'the_posts', array( $posts, &$this ) ); 3332 } 3027 3333 3028 3334 // Ensure that any posts added/modified via one of the filters above are 3029 3335 // of the type WP_Post and are filtered. … … 3059 3365 if ( $q['no_found_rows'] || ( is_array( $this->posts ) && ! $this->posts ) ) 3060 3366 return; 3061 3367 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 3368 if ( ! empty( $limits ) ){ 3369 $found_posts = 'SELECT FOUND_ROWS()'; 3370 /** 3371 * Filter the query to run for retrieving the found posts. 3372 * 3373 * @since 2.1.0 3374 * 3375 * @param string $found_posts The query to run to find the found posts. 3376 * @param WP_Query &$this The WP_Query instance (passed by reference). 3377 */ 3378 $this->found_posts = $wpdb->get_var( apply_filters_ref_array( 'found_posts_query', array( $found_posts, &$this ) ) ); 3379 } 3380 else{ 3065 3381 $this->found_posts = count( $this->posts ); 3382 } 3066 3383 3067 $this->found_posts = apply_filters_ref_array( 'found_posts', array( $this->found_posts, &$this ) ); 3384 $found_posts = $this->found_posts; 3385 /** 3386 * Filter the number of found posts. 3387 * 3388 * @since 2.1.0 3389 * 3390 * @param int $found_posts The number of posts found. 3391 * @param WP_Query &$this The WP_Query instance (passed by reference). 3392 */ 3393 $this->found_posts = apply_filters_ref_array( 'found_posts', array( $found_posts, &$this ) ); 3068 3394 3069 3395 if ( ! empty( $limits ) ) 3070 3396 $this->max_num_pages = ceil( $this->found_posts / $q['posts_per_page'] ); … … 3102 3428 $this->in_the_loop = true; 3103 3429 3104 3430 if ( $this->current_post == -1 ) // loop has just started 3105 do_action_ref_array('loop_start', array(&$this)); 3431 /** 3432 * Fires once the loop is started. 3433 * 3434 * @since 2.0.0 3435 * 3436 * @param WP_Query &$this The WP_Query instance (passed by reference). 3437 */ 3438 do_action_ref_array( 'loop_start', array( &$this ) ); 3106 3439 3107 3440 $post = $this->next_post(); 3108 3441 setup_postdata($post); … … 3123 3456 if ( $this->current_post + 1 < $this->post_count ) { 3124 3457 return true; 3125 3458 } elseif ( $this->current_post + 1 == $this->post_count && $this->post_count > 0 ) { 3126 do_action_ref_array('loop_end', array(&$this)); 3459 /** 3460 * Fires once the loop has ended. 3461 * 3462 * @since 2.0.0 3463 * 3464 * @param WP_Query &$this The WP_Query instance (passed by reference). 3465 */ 3466 do_action_ref_array( 'loop_end', array( &$this ) ); 3127 3467 // Do some cleaning up after the loop 3128 3468 $this->rewind_posts(); 3129 3469 } … … 3174 3514 $comment = $this->next_comment(); 3175 3515 3176 3516 if ( $this->current_comment == 0 ) { 3177 do_action('comment_loop_start'); 3517 /** 3518 * Fires once the comment loop is started. 3519 * 3520 * @since 2.2.0 3521 */ 3522 do_action( 'comment_loop_start' ); 3178 3523 } 3179 3524 } 3180 3525 … … 3935 4280 $pages = array( $post->post_content ); 3936 4281 } 3937 4282 3938 do_action_ref_array('the_post', array(&$post)); 4283 /** 4284 * Fires once the post data has been setup. 4285 * 4286 * @since 2.8.0 4287 * 4288 * @param WP_Post &$post The Post object (passed by reference). 4289 */ 4290 do_action_ref_array( 'the_post', array( &$post ) ); 3939 4291 3940 4292 return true; 3941 4293 }