Inline documentation for various SQL clause hooks in wp-includes/query.php.

Covers documentation for general SQL clause hooks, including:
* `posts_where`
* `posts_join`
* `posts_where_paged`
* `posts_groupby`
* `posts_join_paged`
* `posts_orderby`
* `posts_distinct`
* `post_limits`
* `posts_fields`
* `posts_clauses`

Props dougwollison, DrewAPicture.
See #25514.


Built from https://develop.svn.wordpress.org/trunk@27206


git-svn-id: http://core.svn.wordpress.org/trunk@27063 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-includes/query.php

@@ -2759,7 +2759,7 @@ class WP_Query {
 			$where_status = implode( ' OR ', $statuswheres );
 			if ( ! empty( $where_status ) ) {
 				$where .= " AND ($where_status)";
-			} 
+			}
 		} elseif ( !$this->is_singular ) {
 			$where .= " AND ($wpdb->posts.post_status = 'publish'";
 
@@ -2794,11 +2794,30 @@ class WP_Query {
 			$where .= $clauses['where'];
 		}
 
-		// Apply filters on where and join prior to paging so that any
+		/*
-		// manipulations to them are reflected in the paging by day queries.
+		 * Apply filters on where and join prior to paging so that any
+		 * manipulations to them are reflected in the paging by day queries.
+		 */
 		if ( !$q['suppress_filters'] ) {
-			$where = apply_filters_ref_array('posts_where', array( $where, &$this ) );
+			/**
-			$join = apply_filters_ref_array('posts_join', array( $join, &$this ) );
+			 * Filter the WHERE clause of the query.
+			 *
+			 * @since 1.5.0
+			 *
+			 * @param string   $where The WHERE clause of the query.
+			 * @param WP_Query &$this The WP_Query instance (passed by reference).
+			 */
+			$where = apply_filters_ref_array( 'posts_where', array( $where, &$this ) );
+
+			/**
+			 * Filter the JOIN clause of the query.
+			 *
+			 * @since 1.5.0
+			 *
+			 * @param string   $where The JOIN clause of the query.
+			 * @param WP_Query &$this The WP_Query instance (passed by reference).
+			 */
+			$join = apply_filters_ref_array( 'posts_join', array( $join, &$this ) );
 		}
 
 		// Paging
@@ -2856,21 +2875,101 @@ class WP_Query {
 
 		$pieces = array( 'where', 'groupby', 'join', 'orderby', 'distinct', 'fields', 'limits' );
 
-		// Apply post-paging filters on where and join. Only plugins that
+		/*
-		// manipulate paging queries should use these hooks.
+		 * Apply post-paging filters on where and join. Only plugins that
+		 * manipulate paging queries should use these hooks.
+		 */
 		if ( !$q['suppress_filters'] ) {
+			/**
+			 * Filter the WHERE clause of the query.
+			 *
+			 * Specifically for manipulating paging queries.
+			 *
+			 * @since 1.5.0
+			 *
+			 * @param string   $where The WHERE clause of the query.
+			 * @param WP_Query &$this The WP_Query instance (passed by reference).
+			 */
 			$where		= apply_filters_ref_array( 'posts_where_paged',	array( $where, &$this ) );
+
+			/**
+			 * Filter the GROUP BY clause of the query.
+			 *
+			 * @since 2.0.0
+			 *
+			 * @param string   $groupby The GROUP BY clause of the query.
+			 * @param WP_Query &$this   The WP_Query instance (passed by reference).
+			 */
 			$groupby	= apply_filters_ref_array( 'posts_groupby',		array( $groupby, &$this ) );
+
+			/**
+			 * Filter the JOIN clause of the query.
+			 *
+			 * Specifically for manipulating paging queries.
+			 *
+			 * @since 1.5.0
+			 *
+			 * @param string   $join  The JOIN clause of the query.
+			 * @param WP_Query &$this The WP_Query instance (passed by reference).
+			 */
 			$join		= apply_filters_ref_array( 'posts_join_paged',	array( $join, &$this ) );
+
+			/**
+			 * Filter the ORDER BY clause of the query.
+			 *
+			 * @since 1.5.1
+			 *
+			 * @param string   $orderby The ORDER BY clause of the query.
+			 * @param WP_Query &$this   The WP_Query instance (passed by reference).
+			 */
 			$orderby	= apply_filters_ref_array( 'posts_orderby',		array( $orderby, &$this ) );
+
+			/**
+			 * Filter the DISTINCT clause of the query.
+			 *
+			 * @since 2.1.0
+			 *
+			 * @param string   $distinct The DISTINCT clause of the query.
+			 * @param WP_Query &$this    The WP_Query instance (passed by reference).
+			 */
 			$distinct	= apply_filters_ref_array( 'posts_distinct',	array( $distinct, &$this ) );
+
+			/**
+			 * Filter the LIMIT clause of the query.
+			 *
+			 * @since 2.1.0
+			 *
+			 * @param string   $limits The LIMIT clause of the query.
+			 * @param WP_Query &$this  The WP_Query instance (passed by reference).
+			 */
 			$limits		= apply_filters_ref_array( 'post_limits',		array( $limits, &$this ) );
+
+			/**
+			 * Filter the SELECT clause of the query.
+			 *
+			 * @since 2.1.0
+			 *
+			 * @param string   $fields The SELECT clause of the query.
+			 * @param WP_Query &$this  The WP_Query instance (passed by reference).
+			 */
 			$fields		= apply_filters_ref_array( 'posts_fields',		array( $fields, &$this ) );
 
-			// Filter all clauses at once, for convenience
+			/**
+			 * Filter all query clauses at once, for convenience.
+			 *
+			 * Covers the WHERE, GROUP BY, JOIN, ORDER BY, DISTINCT,
+			 * fields (SELECT), and LIMITS clauses.
+			 *
+			 * @since 3.1.0
+			 *
+			 * @param array    $clauses The list of clauses for the query.
+			 * @param WP_Query &$this   The WP_Query instance (passed by reference).
+			 */
 			$clauses = (array) apply_filters_ref_array( 'posts_clauses', array( compact( $pieces ), &$this ) );
-			foreach ( $pieces as $piece )
+
+			foreach ( $pieces as $piece ) {
 				$$piece = isset( $clauses[ $piece ] ) ? $clauses[ $piece ] : '';
+			}
 		}
 
 		// Announce current selection parameters. For use by caching plugins.