Changeset 27207 for trunk/src/wp-includes/query.php

Timestamp:

02/20/2014 05:40:14 PM (11 years ago)

Author:

DrewAPicture

Message:

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

Covers documentation for SQL clause hooks specified for use by caching plugins, including:

• posts_selection
• posts_where_request
• posts_groupby_request
• posts_join_request
• posts_orderby_request
• posts_distinct_request
• posts_fields_request
• post_limits_request
• posts_clauses_request

Props dougwollison, DrewAPicture.
See #25514.

File:

• trunk/src/wp-includes/query.php (modified) (1 diff)

trunk/src/wp-includes/query.php

@@ -2973 +2973 @@
         }
 
-        // Announce current selection parameters. For use by caching plugins.
+        /**
+         * Fires to announce the query's current selection parameters.
+         *
+         * For use by caching plugins.
+         *
+         * @since 2.3.0
+         *
+         * @param string $selection The assembled selection query.
+         */
         do_action( 'posts_selection', $where . $groupby . $orderby . $limits . $join );
 
-        // Filter again for the benefit of caching plugins. Regular plugins should use the hooks above.
+        /*
+         * Filter again for the benefit of caching plugins.
+         * Regular plugins should use the hooks above.
+         */
         if ( !$q['suppress_filters'] ) {
+            /**
+             * Filter the WHERE clause of the query.
+             *
+             * For use by caching plugins.
+             *
+             * @since 2.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_request',       array( $where, &$this ) );
+
+            /**
+             * Filter the GROUP BY clause of the query.
+             *
+             * For use by caching plugins.
+             *
+             * @since 2.5.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_request',     array( $groupby, &$this ) );
+
+            /**
+             * Filter the JOIN clause of the query.
+             *
+             * For use by caching plugins.
+             *
+             * @since 2.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_request',        array( $join, &$this ) );
+
+            /**
+             * Filter the ORDER BY clause of the query.
+             *
+             * For use by caching plugins.
+             *
+             * @since 2.5.0
+             *
+             * @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_request',     array( $orderby, &$this ) );
+
+            /**
+             * Filter the DISTINCT clause of the query.
+             *
+             * For use by caching plugins.
+             *
+             * @since 2.5.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_request',    array( $distinct, &$this ) );
+
+            /**
+             * Filter the SELECT clause of the query.
+             *
+             * For use by caching plugins.
+             *
+             * @since 2.5.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_request',      array( $fields, &$this ) );
+
+            /**
+             * Filter the LIMIT clause of the query.
+             *
+             * For use by caching plugins.
+             *
+             * @since 2.5.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_request',       array( $limits, &$this ) );
 
-            // Filter all clauses at once, for convenience
+            /**
+             * Filter all query clauses at once, for convenience.
+             *
+             * For use by caching plugins.
+             *
+             * Covers the WHERE, GROUP BY, JOIN, ORDER BY, DISTINCT,
+             * fields (SELECT), and LIMITS clauses.
+             *
+             * @since 3.1.0
+             *
+             * @param array    $pieces The pieces of the query.
+             * @param WP_Query &$this  The WP_Query instance (passed by reference).
+             */
             $clauses = (array) apply_filters_ref_array( 'posts_clauses_request', array( compact( $pieces ), &$this ) );
             foreach ( $pieces as $piece )