From 742c77fc6fe21c1361c7e0274cac2e82d4459f4c Mon Sep 17 00:00:00 2001 From: Drew Jaynes Date: Thu, 20 Feb 2014 17:34:14 +0000 Subject: [PATCH] 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 | 117 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 108 insertions(+), 9 deletions(-) diff --git a/wp-includes/query.php b/wp-includes/query.php index 3276351f31..73dbf3d0be 100644 --- a/wp-includes/query.php +++ b/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.