Ticket #25514: WP_Query-hook-docs.diff
| File WP_Query-hook-docs.diff, 18.6 KB (added by , 10 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 actions to be run after parse_query is complete. 1714 * 1715 * @since 1.5.2 1716 * 1717 * @param WP_Query &$this The WP_Query object (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 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 object. 1919 */ 1906 1920 do_action( 'parse_tax_query', $this ); 1907 1921 } 1908 1922 … … 2143 2157 global $wpdb; 2144 2158 2145 2159 $this->parse_query(); 2160 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 object (passed by refrence). 2167 */ 2168 do_action_ref_array( 'pre_get_posts', array( &$this ) ); 2146 2169 2147 do_action_ref_array('pre_get_posts', array(&$this));2148 2149 2170 // Shorthand. 2150 2171 $q = &$this->query_vars; 2151 2172 … … 2774 2795 // Apply filters on where and join prior to paging so that any 2775 2796 // manipulations to them are reflected in the paging by day queries. 2776 2797 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 object (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 object (passed by refrence). 2815 */ 2816 $join = apply_filters_ref_array( 'posts_join', array( $join, &$this ) ); 2779 2817 } 2780 2818 2781 2819 // Paging … … 2806 2844 } 2807 2845 2808 2846 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 object (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 object (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 object (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 object (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 object (passed by refrence). 2894 */ 2895 $climits = apply_filters_ref_array( 'comment_feed_limits', array( 'LIMIT ' . get_option('posts_per_rss'), &$this ) ); 2814 2896 } 2815 2897 $cgroupby = ( ! empty( $cgroupby ) ) ? 'GROUP BY ' . $cgroupby : ''; 2816 2898 $corderby = ( ! empty( $corderby ) ) ? 'ORDER BY ' . $corderby : ''; … … 2836 2918 // Apply post-paging filters on where and join. Only plugins that 2837 2919 // manipulate paging queries should use these hooks. 2838 2920 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 object (passed by refrence). 2928 */ 2839 2929 $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 object (passed by refrence). 2938 */ 2840 2939 $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 object (passed by refrence). 2948 */ 2841 2949 $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 object (passed by refrence). 2958 */ 2842 2959 $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 object (passed by refrence). 2968 */ 2843 2969 $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 object (passed by refrence). 2978 */ 2844 2979 $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 object (passed by refrence). 2988 */ 2845 2989 $fields = apply_filters_ref_array( 'posts_fields', array( $fields, &$this ) ); 2846 2847 // Filter all clauses at once, for convenience 2990 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 object (passed by refrence). 2998 */ 2848 2999 $clauses = (array) apply_filters_ref_array( 'posts_clauses', array( compact( $pieces ), &$this ) ); 3000 2849 3001 foreach ( $pieces as $piece ) 2850 3002 $$piece = isset( $clauses[ $piece ] ) ? $clauses[ $piece ] : ''; 2851 3003 } 2852 3004 2853 3005 // 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 */ 2854 3015 do_action( 'posts_selection', $where . $groupby . $orderby . $limits . $join ); 2855 3016 2856 3017 // Filter again for the benefit of caching plugins. Regular plugins should use the hooks above. 2857 3018 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 object (passed by refrence). 3026 */ 2858 3027 $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 object (passed by refrence). 3036 */ 2859 3037 $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 object (passed by refrence). 3046 */ 2860 3047 $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 object (passed by refrence). 3056 */ 2861 3057 $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 object (passed by refrence). 3066 */ 2862 3067 $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 object (passed by refrence). 3076 */ 2863 3077 $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 object (passed by refrence). 3086 */ 2864 3087 $limits = apply_filters_ref_array( 'post_limits_request', array( $limits, &$this ) ); 2865 3088 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 object (passed by refrence). 3096 */ 2867 3097 $clauses = (array) apply_filters_ref_array( 'posts_clauses_request', array( compact( $pieces ), &$this ) ); 2868 3098 foreach ( $pieces as $piece ) 2869 3099 $$piece = isset( $clauses[ $piece ] ) ? $clauses[ $piece ] : ''; … … 2881 3111 $this->request = $old_request = "SELECT $found_rows $distinct $fields FROM $wpdb->posts $join WHERE 1=1 $where $groupby $orderby $limits"; 2882 3112 2883 3113 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 object (passed by refrence). 3121 */ 2884 3122 $this->request = apply_filters_ref_array( 'posts_request', array( $this->request, &$this ) ); 2885 3123 } 2886 3124 … … 2905 3143 } 2906 3144 2907 3145 $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 object. 3154 */ 2908 3155 $split_the_query = apply_filters( 'split_the_query', $split_the_query, $this ); 2909 3156 2910 3157 if ( $split_the_query ) { … … 2912 3159 2913 3160 $this->request = "SELECT $found_rows $distinct $wpdb->posts.ID FROM $wpdb->posts $join WHERE 1=1 $where $groupby $orderby $limits"; 2914 3161 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 object. 3169 */ 2915 3170 $this->request = apply_filters( 'posts_request_ids', $this->request, $this ); 2916 3171 2917 3172 $ids = $wpdb->get_col( $this->request ); … … 2932 3187 if ( $this->posts ) 2933 3188 $this->posts = array_map( 'get_post', $this->posts ); 2934 3189 2935 // Raw results filter. Prior to status checks.2936 3190 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 object (passed by reference). 3198 */ 3199 $this->posts = apply_filters_ref_array( 'posts_results', array( $this->posts, &$this ) ); 2938 3200 2939 3201 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 ) ); 2943 3210 $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 ) ); 2945 3214 $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 2947 3219 $comments_request = "SELECT $wpdb->comments.* FROM $wpdb->comments $cjoin $cwhere $cgroupby $corderby $climits"; 2948 3220 $this->comments = $wpdb->get_results($comments_request); 2949 3221 $this->comment_count = count($this->comments); … … 2978 3250 } 2979 3251 2980 3252 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 object (passed by reference). 3260 */ 2981 3261 $this->posts[0] = get_post( apply_filters_ref_array( 'the_preview', array( $this->posts[0], &$this ) ) ); 2982 3262 } 2983 3263 … … 3023 3303 } 3024 3304 3025 3305 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 object (passed by reference). 3314 */ 3315 $this->posts = apply_filters_ref_array( 'the_posts', array( $this->posts, &$this ) ); 3027 3316 3028 3317 // Ensure that any posts added/modified via one of the filters above are 3029 3318 // of the type WP_Post and are filtered. … … 3060 3349 return; 3061 3350 3062 3351 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 object (passed by reference). 3359 */ 3063 3360 $this->found_posts = $wpdb->get_var( apply_filters_ref_array( 'found_posts_query', array( 'SELECT FOUND_ROWS()', &$this ) ) ); 3064 3361 else 3065 3362 $this->found_posts = count( $this->posts ); 3066 3363 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 object (passed by reference). 3371 */ 3067 3372 $this->found_posts = apply_filters_ref_array( 'found_posts', array( $this->found_posts, &$this ) ); 3068 3373 3069 3374 if ( ! empty( $limits ) ) … … 3102 3407 $this->in_the_loop = true; 3103 3408 3104 3409 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 object (passed by reference). 3416 */ 3417 do_action_ref_array( 'loop_start', array( &$this ) ); 3106 3418 3107 3419 $post = $this->next_post(); 3108 3420 setup_postdata($post); … … 3123 3435 if ( $this->current_post + 1 < $this->post_count ) { 3124 3436 return true; 3125 3437 } 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 object (passed by reference). 3444 */ 3445 do_action_ref_array( 'loop_end', array( &$this ) ); 3127 3446 // Do some cleaning up after the loop 3128 3447 $this->rewind_posts(); 3129 3448 } … … 3174 3493 $comment = $this->next_comment(); 3175 3494 3176 3495 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' ); 3178 3502 } 3179 3503 } 3180 3504 … … 3935 4259 $pages = array( $post->post_content ); 3936 4260 } 3937 4261 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 ) ); 3939 4270 3940 4271 return true; 3941 4272 }