Changeset 31663 for trunk/src/wp-includes/user.php

Timestamp:

03/07/2015 04:05:11 PM (10 years ago)

Author:

boonebgorges

Message:

Improve 'orderby' syntax for WP_User_Query.

This changeset ports a number of 'orderby' features from WP_Query and
WP_Comment_Query:

• Allow multiple 'orderby' values to be passed as a space-separated list.
• Allow multiple 'orderby' values to be passed as a flat array.
• Allow multi-dimensional 'orderby', with orderby fields as array keys and ASC/DESC as the corresponding values.

See #31265.

File:

• trunk/src/wp-includes/user.php (modified) (4 diffs)

trunk/src/wp-includes/user.php

@@ -501 +501 @@
      *
      * @since 3.1.0
-     * @since 4.2.0 Added 'meta_value_num' support for `$orderby` parameter.
+     * @since 4.2.0 Added 'meta_value_num' support for `$orderby` parameter. Added multi-dimensional array syntax
+     *              for `$orderby` parameter.
      * @access public
      *
@@ -522 +523 @@
      *     @type array        $search_columns  Array of column names to be searched. Accepts 'ID', 'login',
      *                                         'nicename', 'email', 'url'. Default empty array.
-     *     @type string       $orderby         Field to sort the retrieved users by. Accepts 'ID', 'display_name',
-     *                                         'login', 'nicename', 'email', 'url', 'registered', 'post_count',
-     *                                         'meta_value' or 'meta_value_num'. To use 'meta_value' or
-     *                                         'meta_value_num', `$meta_key` must be also be defined.
-     *                                         Default 'user_login'.
-     *     @type string       $order           Designates ascending or descending order of users. Accepts 'ASC',
-     *                                         'DESC'. Default 'ASC'.
+     *     @type string|array $orderby         Field to sort the retrieved users by. May be a single value,
+     *                                     an array of values, or a multi-dimensional array with fields as keys
+     *                                     and orders ('ASC' or 'DESC') as values. Accepted values are'ID',
+     *                                     'display_name' (or 'name'), 'user_login' (or 'login'),
+     *                                     'user_nicename' (or 'nicename'), 'user_email' (or 'email'),
+     *                                     'user_url' (or 'url'), 'user_registered' (or 'registered'),
+     *                                     'post_count', 'meta_value', or 'meta_value_num'. To use 'meta_value'
+     *                                     or 'meta_value_num', `$meta_key` must be also be defined.
+     *                                     Default 'user_login'.
+     *     @type string       $order           Designates ascending or descending order of users. Order values
+     *                                         passed as part of an `$orderby` array take precedence over this
+     *                                         parameter. Accepts 'ASC', 'DESC'. Default 'ASC'.
      *     @type int          $offset          Number of users to offset in retrieved results. Can be used in
      *                                         conjunction with pagination. Default 0.
@@ -612 +618 @@
 
         // sorting
-        if ( isset( $qv['orderby'] ) ) {
-            if ( in_array( $qv['orderby'], array('nicename', 'email', 'url', 'registered') ) ) {
-                $orderby = 'user_' . $qv['orderby'];
-            } elseif ( in_array( $qv['orderby'], array('user_nicename', 'user_email', 'user_url', 'user_registered') ) ) {
-                $orderby = $qv['orderby'];
-            } elseif ( 'name' == $qv['orderby'] || 'display_name' == $qv['orderby'] ) {
-                $orderby = 'display_name';
-            } elseif ( 'post_count' == $qv['orderby'] ) {
-                // todo: avoid the JOIN
-                $where = get_posts_by_author_sql('post');
-                $this->query_from .= " LEFT OUTER JOIN (
-                    SELECT post_author, COUNT(*) as post_count
-                    FROM $wpdb->posts
-                    $where
-                    GROUP BY post_author
-                ) p ON ({$wpdb->users}.ID = p.post_author)
-                ";
-                $orderby = 'post_count';
-            } elseif ( 'ID' == $qv['orderby'] || 'id' == $qv['orderby'] ) {
-                $orderby = 'ID';
-            } elseif ( 'meta_value' == $qv['orderby'] ) {
-                $orderby = "$wpdb->usermeta.meta_value";
-            } elseif ( 'meta_value_num' == $qv['orderby'] ) {
-                $orderby = "$wpdb->usermeta.meta_value+0";
-            } elseif ( 'include' === $qv['orderby'] && ! empty( $include ) ) {
-                // Sanitized earlier.
-                $include_sql = implode( ',', $include );
-                $orderby = "FIELD( $wpdb->users.ID, $include_sql )";
+        $qv['order'] = isset( $qv['order'] ) ? strtoupper( $qv['order'] ) : '';
+        $order = $this->parse_order( $qv['order'] );
+
+        if ( empty( $qv['orderby'] ) ) {
+            // Default order is by 'user_login'.
+            $ordersby = array( 'user_login' => $order );
+        } else if ( is_array( $qv['orderby'] ) ) {
+            $ordersby = $qv['orderby'];
+        } else {
+            // 'orderby' values may be a comma- or space-separated list.
+            $ordersby = preg_split( '/[,\s]+/', $qv['orderby'] );
+        }
+
+        $orderby_array = array();
+        foreach ( $ordersby as $_key => $_value ) {
+            if ( ! $_value ) {
+                continue;
+            }
+
+            if ( is_int( $_key ) ) {
+                // Integer key means this is a flat array of 'orderby' fields.
+                $_orderby = $_value;
+                $_order = $order;
             } else {
-                $orderby = 'user_login';
+                // Non-integer key means this the key is the field and the value is ASC/DESC.
+                $_orderby = $_key;
+                $_order = $_value;
             }
-        }
-
-        if ( empty( $orderby ) )
-            $orderby = 'user_login';
-
-        $qv['order'] = isset( $qv['order'] ) ? strtoupper( $qv['order'] ) : '';
-        if ( 'ASC' == $qv['order'] )
-            $order = 'ASC';
-        else
-            $order = 'DESC';
-        $this->query_orderby = "ORDER BY $orderby $order";
+
+            $parsed = $this->parse_orderby( $_orderby );
+
+            if ( ! $parsed ) {
+                continue;
+            }
+
+            $orderby_array[] = $parsed . ' ' . $this->parse_order( $_order );
+        }
+
+        // If no valid clauses were found, order by user_login.
+        if ( empty( $orderby_array ) ) {
+            $orderby_array[] = "user_login $order";
+        }
+
+        $this->query_orderby = 'ORDER BY ' . implode( ', ', $orderby_array );
 
         // limit
@@ -923 +931 @@
     public function get_total() {
         return $this->total_users;
+    }
+
+    /**
+     * Parse and sanitize 'orderby' keys passed to the user query.
+     *
+     * @since 4.2.0
+     * @access protected
+     *
+     * @global wpdb $wpdb WordPress database abstraction object.
+     *
+     * @param string $orderby Alias for the field to order by.
+     * @return string|bool Value to used in the ORDER clause, if `$orderby` is valid. False otherwise.
+     */
+    protected function parse_orderby( $orderby ) {
+        global $wpdb;
+
+        $_orderby = '';
+        if ( in_array( $orderby, array( 'login', 'nicename', 'email', 'url', 'registered' ) ) ) {
+            $_orderby = 'user_' . $orderby;
+        } elseif ( in_array( $orderby, array( 'user_login', 'user_nicename', 'user_email', 'user_url', 'user_registered' ) ) ) {
+            $_orderby = $orderby;
+        } elseif ( 'name' == $orderby || 'display_name' == $orderby ) {
+            $_orderby = 'display_name';
+        } elseif ( 'post_count' == $orderby ) {
+            // todo: avoid the JOIN
+            $where = get_posts_by_author_sql( 'post' );
+            $this->query_from .= " LEFT OUTER JOIN (
+                SELECT post_author, COUNT(*) as post_count
+                FROM $wpdb->posts
+                $where
+                GROUP BY post_author
+            ) p ON ({$wpdb->users}.ID = p.post_author)
+            ";
+            $_orderby = 'post_count';
+        } elseif ( 'ID' == $orderby || 'id' == $orderby ) {
+            $_orderby = 'ID';
+        } elseif ( 'meta_value' == $orderby ) {
+            $_orderby = "$wpdb->usermeta.meta_value";
+        } elseif ( 'meta_value_num' == $orderby ) {
+            $_orderby = "$wpdb->usermeta.meta_value+0";
+        } elseif ( 'include' === $orderby && ! empty( $this->query_vars['include'] ) ) {
+            $include = wp_parse_id_list( $this->query_vars['include'] );
+            $include_sql = implode( ',', $include );
+            $_orderby = "FIELD( $wpdb->users.ID, $include_sql )";
+        }
+
+        return $_orderby;
+    }
+
+    /**
+     * Parse an 'order' query variable and cast it to ASC or DESC as necessary.
+     *
+     * @since 4.2.0
+     * @access protected
+     *
+     * @param string $order The 'order' query variable.
+     * @return string The sanitized 'order' query variable.
+     */
+    protected function parse_order( $order ) {
+        if ( ! is_string( $order ) || empty( $order ) ) {
+            return 'DESC';
+        }
+
+        if ( 'ASC' === strtoupper( $order ) ) {
+            return 'ASC';
+        } else {
+            return 'DESC';
+        }
     }