From fa62df07749a3bfaa44e944c02512215ab70a5db Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Sat, 20 Nov 2021 00:07:59 +0000 Subject: [PATCH] Query: Correct and standardise the meta query documentation. Also improves the formatting of some surrounding documentation. Props audrasjb, johnbillion Fixes #53467 Built from https://develop.svn.wordpress.org/trunk@52226 git-svn-id: http://core.svn.wordpress.org/trunk@51818 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/class-wp-comment-query.php | 228 ++++++++++++----------- wp-includes/class-wp-meta-query.php | 77 +++++--- wp-includes/class-wp-query.php | 243 +++++++++++++------------ wp-includes/class-wp-site-query.php | 116 ++++++------ wp-includes/class-wp-term-query.php | 191 +++++++++---------- wp-includes/class-wp-user-query.php | 183 +++++++++++-------- wp-includes/version.php | 2 +- 7 files changed, 576 insertions(+), 464 deletions(-) diff --git a/wp-includes/class-wp-comment-query.php b/wp-includes/class-wp-comment-query.php index a592fdb687..5e5854a2f7 100644 --- a/wp-includes/class-wp-comment-query.php +++ b/wp-includes/class-wp-comment-query.php @@ -141,114 +141,134 @@ class WP_Comment_Query { * @since 4.5.0 Introduced the `$author_url` argument. * @since 4.6.0 Introduced the `$cache_domain` argument. * @since 4.9.0 Introduced the `$paged` argument. + * @since 5.1.0 Introduced the `$meta_compare_key` argument. + * @since 5.3.0 Introduced the `$meta_type_key` argument. * * @param string|array $query { * Optional. Array or query string of comment query parameters. Default empty. * - * @type string $author_email Comment author email address. Default empty. - * @type string $author_url Comment author URL. Default empty. - * @type int[] $author__in Array of author IDs to include comments for. Default empty. - * @type int[] $author__not_in Array of author IDs to exclude comments for. Default empty. - * @type int[] $comment__in Array of comment IDs to include. Default empty. - * @type int[] $comment__not_in Array of comment IDs to exclude. Default empty. - * @type bool $count Whether to return a comment count (true) or array of - * comment objects (false). Default false. - * @type array $date_query Date query clauses to limit comments by. See WP_Date_Query. - * Default null. - * @type string $fields Comment fields to return. Accepts 'ids' for comment IDs - * only or empty for all fields. Default empty. - * @type int $ID Currently unused. - * @type array $include_unapproved Array of IDs or email addresses of users whose unapproved - * comments will be returned by the query regardless of - * `$status`. Default empty. - * @type int $karma Karma score to retrieve matching comments for. - * Default empty. - * @type string $meta_key Include comments with a matching comment meta key. - * Default empty. - * @type string $meta_value Include comments with a matching comment meta value. - * Requires `$meta_key` to be set. Default empty. - * @type array $meta_query Meta query clauses to limit retrieved comments by. - * See WP_Meta_Query. Default empty. - * @type int $number Maximum number of comments to retrieve. - * Default empty (no limit). - * @type int $paged When used with $number, defines the page of results to return. - * When used with $offset, $offset takes precedence. Default 1. - * @type int $offset Number of comments to offset the query. Used to build - * LIMIT clause. Default 0. - * @type bool $no_found_rows Whether to disable the `SQL_CALC_FOUND_ROWS` query. - * Default: true. - * @type string|array $orderby Comment status or array of statuses. To use 'meta_value' - * or 'meta_value_num', `$meta_key` must also be defined. - * To sort by a specific `$meta_query` clause, use that - * clause's array key. Accepts 'comment_agent', - * 'comment_approved', 'comment_author', - * 'comment_author_email', 'comment_author_IP', - * 'comment_author_url', 'comment_content', 'comment_date', - * 'comment_date_gmt', 'comment_ID', 'comment_karma', - * 'comment_parent', 'comment_post_ID', 'comment_type', - * 'user_id', 'comment__in', 'meta_value', 'meta_value_num', - * the value of $meta_key, and the array keys of - * `$meta_query`. Also accepts false, an empty array, or - * 'none' to disable `ORDER BY` clause. - * Default: 'comment_date_gmt'. - * @type string $order How to order retrieved comments. Accepts 'ASC', 'DESC'. - * Default: 'DESC'. - * @type int $parent Parent ID of comment to retrieve children of. - * Default empty. - * @type int[] $parent__in Array of parent IDs of comments to retrieve children for. - * Default empty. - * @type int[] $parent__not_in Array of parent IDs of comments *not* to retrieve - * children for. Default empty. - * @type int[] $post_author__in Array of author IDs to retrieve comments for. - * Default empty. - * @type int[] $post_author__not_in Array of author IDs *not* to retrieve comments for. - * Default empty. - * @type int $post_ID Currently unused. - * @type int $post_id Limit results to those affiliated with a given post ID. - * Default 0. - * @type int[] $post__in Array of post IDs to include affiliated comments for. - * Default empty. - * @type int[] $post__not_in Array of post IDs to exclude affiliated comments for. - * Default empty. - * @type int $post_author Post author ID to limit results by. Default empty. - * @type string|array $post_status Post status or array of post statuses to retrieve - * affiliated comments for. Pass 'any' to match any value. - * Default empty. - * @type string|array $post_type Post type or array of post types to retrieve affiliated - * comments for. Pass 'any' to match any value. Default empty. - * @type string $post_name Post name to retrieve affiliated comments for. - * Default empty. - * @type int $post_parent Post parent ID to retrieve affiliated comments for. - * Default empty. - * @type string $search Search term(s) to retrieve matching comments for. - * Default empty. - * @type string|array $status Comment statuses to limit results by. Accepts an array - * or space/comma-separated list of 'hold' (`comment_status=0`), - * 'approve' (`comment_status=1`), 'all', or a custom - * comment status. Default 'all'. - * @type string|array $type Include comments of a given type, or array of types. - * Accepts 'comment', 'pings' (includes 'pingback' and - * 'trackback'), or any custom type string. Default empty. - * @type string[] $type__in Include comments from a given array of comment types. - * Default empty. - * @type string[] $type__not_in Exclude comments from a given array of comment types. - * Default empty. - * @type int $user_id Include comments for a specific user ID. Default empty. - * @type bool|string $hierarchical Whether to include comment descendants in the results. - * - 'threaded' returns a tree, with each comment's children - * stored in a `children` property on the `WP_Comment` object. - * - 'flat' returns a flat array of found comments plus - * their children. - * - Boolean `false` leaves out descendants. - * The parameter is ignored (forced to `false`) when - * `$fields` is 'ids' or 'counts'. Accepts 'threaded', - * 'flat', or false. Default: false. - * @type string $cache_domain Unique cache key to be produced when this query is stored in - * an object cache. Default is 'core'. - * @type bool $update_comment_meta_cache Whether to prime the metadata cache for found comments. - * Default true. - * @type bool $update_comment_post_cache Whether to prime the cache for comment posts. - * Default false. + * @type string $author_email Comment author email address. Default empty. + * @type string $author_url Comment author URL. Default empty. + * @type int[] $author__in Array of author IDs to include comments for. Default empty. + * @type int[] $author__not_in Array of author IDs to exclude comments for. Default empty. + * @type int[] $comment__in Array of comment IDs to include. Default empty. + * @type int[] $comment__not_in Array of comment IDs to exclude. Default empty. + * @type bool $count Whether to return a comment count (true) or array of + * comment objects (false). Default false. + * @type array $date_query Date query clauses to limit comments by. See WP_Date_Query. + * Default null. + * @type string $fields Comment fields to return. Accepts 'ids' for comment IDs + * only or empty for all fields. Default empty. + * @type int $ID Currently unused. + * @type array $include_unapproved Array of IDs or email addresses of users whose unapproved + * comments will be returned by the query regardless of + * `$status`. Default empty. + * @type int $karma Karma score to retrieve matching comments for. + * Default empty. + * @type string|string[] $meta_key Meta key or keys to filter by. + * @type string|string[] $meta_value Meta value or values to filter by. + * @type string $meta_compare MySQL operator used for comparing the meta value. + * See WP_Meta_Query::__construct for accepted values and default value. + * @type string $meta_compare_key MySQL operator used for comparing the meta key. + * See WP_Meta_Query::__construct for accepted values and default value. + * @type string $meta_type MySQL data type that the meta_value column will be CAST to for comparisons. + * See WP_Meta_Query::__construct for accepted values and default value. + * @type string $meta_type_key MySQL data type that the meta_key column will be CAST to for comparisons. + * See WP_Meta_Query::__construct for accepted values and default value. + * @type array $meta_query An associative array of WP_Meta_Query arguments. + * See WP_Meta_Query::__construct for accepted values. + * @type int $number Maximum number of comments to retrieve. + * Default empty (no limit). + * @type int $paged When used with `$number`, defines the page of results to return. + * When used with `$offset`, `$offset` takes precedence. Default 1. + * @type int $offset Number of comments to offset the query. Used to build + * LIMIT clause. Default 0. + * @type bool $no_found_rows Whether to disable the `SQL_CALC_FOUND_ROWS` query. + * Default: true. + * @type string|array $orderby Comment status or array of statuses. To use 'meta_value' + * or 'meta_value_num', `$meta_key` must also be defined. + * To sort by a specific `$meta_query` clause, use that + * clause's array key. Accepts: + * - 'comment_agent' + * - 'comment_approved' + * - 'comment_author' + * - 'comment_author_email' + * - 'comment_author_IP' + * - 'comment_author_url' + * - 'comment_content' + * - 'comment_date' + * - 'comment_date_gmt' + * - 'comment_ID' + * - 'comment_karma' + * - 'comment_parent' + * - 'comment_post_ID' + * - 'comment_type' + * - 'user_id' + * - 'comment__in' + * - 'meta_value' + * - 'meta_value_num' + * - The value of `$meta_key` + * - The array keys of `$meta_query` + * - false, an empty array, or 'none' to disable `ORDER BY` clause. + * Default: 'comment_date_gmt'. + * @type string $order How to order retrieved comments. Accepts 'ASC', 'DESC'. + * Default: 'DESC'. + * @type int $parent Parent ID of comment to retrieve children of. + * Default empty. + * @type int[] $parent__in Array of parent IDs of comments to retrieve children for. + * Default empty. + * @type int[] $parent__not_in Array of parent IDs of comments *not* to retrieve + * children for. Default empty. + * @type int[] $post_author__in Array of author IDs to retrieve comments for. + * Default empty. + * @type int[] $post_author__not_in Array of author IDs *not* to retrieve comments for. + * Default empty. + * @type int $post_ID Currently unused. + * @type int $post_id Limit results to those affiliated with a given post ID. + * Default 0. + * @type int[] $post__in Array of post IDs to include affiliated comments for. + * Default empty. + * @type int[] $post__not_in Array of post IDs to exclude affiliated comments for. + * Default empty. + * @type int $post_author Post author ID to limit results by. Default empty. + * @type string|array $post_status Post status or array of post statuses to retrieve + * affiliated comments for. Pass 'any' to match any value. + * Default empty. + * @type string|array $post_type Post type or array of post types to retrieve affiliated + * comments for. Pass 'any' to match any value. Default empty. + * @type string $post_name Post name to retrieve affiliated comments for. + * Default empty. + * @type int $post_parent Post parent ID to retrieve affiliated comments for. + * Default empty. + * @type string $search Search term(s) to retrieve matching comments for. + * Default empty. + * @type string|array $status Comment statuses to limit results by. Accepts an array + * or space/comma-separated list of 'hold' (`comment_status=0`), + * 'approve' (`comment_status=1`), 'all', or a custom + * comment status. Default 'all'. + * @type string|array $type Include comments of a given type, or array of types. + * Accepts 'comment', 'pings' (includes 'pingback' and + * 'trackback'), or any custom type string. Default empty. + * @type string[] $type__in Include comments from a given array of comment types. + * Default empty. + * @type string[] $type__not_in Exclude comments from a given array of comment types. + * Default empty. + * @type int $user_id Include comments for a specific user ID. Default empty. + * @type bool|string $hierarchical Whether to include comment descendants in the results. + * - 'threaded' returns a tree, with each comment's children + * stored in a `children` property on the `WP_Comment` object. + * - 'flat' returns a flat array of found comments plus + * their children. + * - Boolean `false` leaves out descendants. + * The parameter is ignored (forced to `false`) when + * `$fields` is 'ids' or 'counts'. Accepts 'threaded', + * 'flat', or false. Default: false. + * @type string $cache_domain Unique cache key to be produced when this query is stored in + * an object cache. Default is 'core'. + * @type bool $update_comment_meta_cache Whether to prime the metadata cache for found comments. + * Default true. + * @type bool $update_comment_post_cache Whether to prime the cache for comment posts. + * Default false. * } */ public function __construct( $query = '' ) { diff --git a/wp-includes/class-wp-meta-query.php b/wp-includes/class-wp-meta-query.php index 0b3ffab033..39708d85ce 100644 --- a/wp-includes/class-wp-meta-query.php +++ b/wp-includes/class-wp-meta-query.php @@ -99,37 +99,68 @@ class WP_Meta_Query { * * @since 3.2.0 * @since 4.2.0 Introduced support for naming query clauses by associative array keys. - * @since 5.1.0 Introduced $compare_key clause parameter, which enables LIKE key matches. - * @since 5.3.0 Increased the number of operators available to $compare_key. Introduced $type_key, - * which enables the $key to be cast to a new data type for comparisons. + * @since 5.1.0 Introduced `$compare_key` clause parameter, which enables LIKE key matches. + * @since 5.3.0 Increased the number of operators available to `$compare_key`. Introduced `$type_key`, + * which enables the `$key` to be cast to a new data type for comparisons. * * @param array $meta_query { * Array of meta query clauses. When first-order clauses or sub-clauses use strings as * their array keys, they may be referenced in the 'orderby' parameter of the parent query. * - * @type string $relation Optional. The MySQL keyword used to join - * the clauses of the query. Accepts 'AND', or 'OR'. Default 'AND'. + * @type string $relation Optional. The MySQL keyword used to join the clauses of the query. + * Accepts 'AND' or 'OR'. Default 'AND'. * @type array ...$0 { * Optional. An array of first-order clause parameters, or another fully-formed meta query. * - * @type string $key Meta key to filter by. - * @type string $compare_key MySQL operator used for comparing the $key. Accepts '=', '!=' - * 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'REGEXP', 'NOT REGEXP', 'RLIKE', - * 'EXISTS' (alias of '=') or 'NOT EXISTS' (alias of '!='). - * Default is 'IN' when `$key` is an array, '=' otherwise. - * @type string $type_key MySQL data type that the meta_key column will be CAST to for - * comparisons. Accepts 'BINARY' for case-sensitive regular expression - * comparisons. Default is ''. - * @type string $value Meta value to filter by. - * @type string $compare MySQL operator used for comparing the $value. Accepts '=', - * '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', - * 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'REGEXP', - * 'NOT REGEXP', 'RLIKE', 'EXISTS' or 'NOT EXISTS'. - * Default is 'IN' when `$value` is an array, '=' otherwise. - * @type string $type MySQL data type that the meta_value column will be CAST to for - * comparisons. Accepts 'NUMERIC', 'BINARY', 'CHAR', 'DATE', - * 'DATETIME', 'DECIMAL', 'SIGNED', 'TIME', or 'UNSIGNED'. - * Default is 'CHAR'. + * @type string|string[] $key Meta key or keys to filter by. + * @type string $compare_key MySQL operator used for comparing the $key. Accepts: + * - '=' + * - '!=' + * - 'LIKE' + * - 'NOT LIKE' + * - 'IN' + * - 'NOT IN' + * - 'REGEXP' + * - 'NOT REGEXP' + * - 'RLIKE', + * - 'EXISTS' (alias of '=') + * - 'NOT EXISTS' (alias of '!=') + * Default is 'IN' when `$key` is an array, '=' otherwise. + * @type string $type_key MySQL data type that the meta_key column will be CAST to for + * comparisons. Accepts 'BINARY' for case-sensitive regular expression + * comparisons. Default is ''. + * @type string|string[] $value Meta value or values to filter by. + * @type string $compare MySQL operator used for comparing the $value. Accepts: + * - '=', + * - '!=' + * - '>' + * - '>=' + * - '<' + * - '<=' + * - 'LIKE' + * - 'NOT LIKE' + * - 'IN' + * - 'NOT IN' + * - 'BETWEEN' + * - 'NOT BETWEEN' + * - 'REGEXP' + * - 'NOT REGEXP' + * - 'RLIKE' + * - 'EXISTS' + * - 'NOT EXISTS' + * Default is 'IN' when `$value` is an array, '=' otherwise. + * @type string $type MySQL data type that the meta_value column will be CAST to for + * comparisons. Accepts: + * - 'NUMERIC' + * - 'BINARY' + * - 'CHAR' + * - 'DATE' + * - 'DATETIME' + * - 'DECIMAL' + * - 'SIGNED' + * - 'TIME' + * - 'UNSIGNED' + * Default is 'CHAR'. * } * } */ diff --git a/wp-includes/class-wp-query.php b/wp-includes/class-wp-query.php index 1f9516eec4..83351762eb 100644 --- a/wp-includes/class-wp-query.php +++ b/wp-includes/class-wp-query.php @@ -630,118 +630,137 @@ class WP_Query { * @param string|array $query { * Optional. Array or string of Query parameters. * - * @type int $attachment_id Attachment post ID. Used for 'attachment' post_type. - * @type int|string $author Author ID, or comma-separated list of IDs. - * @type string $author_name User 'user_nicename'. - * @type int[] $author__in An array of author IDs to query from. - * @type int[] $author__not_in An array of author IDs not to query from. - * @type bool $cache_results Whether to cache post information. Default true. - * @type int|string $cat Category ID or comma-separated list of IDs (this or any children). - * @type int[] $category__and An array of category IDs (AND in). - * @type int[] $category__in An array of category IDs (OR in, no children). - * @type int[] $category__not_in An array of category IDs (NOT in). - * @type string $category_name Use category slug (not name, this or any children). - * @type array|int $comment_count Filter results by comment count. Provide an integer to match - * comment count exactly. Provide an array with integer 'value' - * and 'compare' operator ('=', '!=', '>', '>=', '<', '<=' ) to - * compare against comment_count in a specific way. - * @type string $comment_status Comment status. - * @type int $comments_per_page The number of comments to return per page. - * Default 'comments_per_page' option. - * @type array $date_query An associative array of WP_Date_Query arguments. - * See WP_Date_Query::__construct(). - * @type int $day Day of the month. Default empty. Accepts numbers 1-31. - * @type bool $exact Whether to search by exact keyword. Default false. - * @type string $fields Post fields to query for. Accepts: - * - '' Returns an array of complete post objects (`WP_Post[]`). - * - 'ids' Returns an array of post IDs (`int[]`). - * - 'id=>parent' Returns an associative array of parent post IDs, - * keyed by post ID (`int[]`). - * Default ''. - * @type int $hour Hour of the day. Default empty. Accepts numbers 0-23. - * @type int|bool $ignore_sticky_posts Whether to ignore sticky posts or not. Setting this to false - * excludes stickies from 'post__in'. Accepts 1|true, 0|false. - * Default false. - * @type int $m Combination YearMonth. Accepts any four-digit year and month - * numbers 1-12. Default empty. - * @type string $meta_compare Comparison operator to test the 'meta_value'. - * @type string $meta_compare_key Comparison operator to test the 'meta_key'. - * @type string $meta_key Custom field key. - * @type array $meta_query An associative array of WP_Meta_Query arguments. See WP_Meta_Query. - * @type string $meta_value Custom field value. - * @type int $meta_value_num Custom field value number. - * @type string $meta_type_key Cast for 'meta_key'. See WP_Meta_Query::construct(). - * @type int $menu_order The menu order of the posts. - * @type int $minute Minute of the hour. Default empty. Accepts numbers 0-59. - * @type int $monthnum The two-digit month. Default empty. Accepts numbers 1-12. - * @type string $name Post slug. - * @type bool $nopaging Show all posts (true) or paginate (false). Default false. - * @type bool $no_found_rows Whether to skip counting the total rows found. Enabling can improve - * performance. Default false. - * @type int $offset The number of posts to offset before retrieval. - * @type string $order Designates ascending or descending order of posts. Default 'DESC'. - * Accepts 'ASC', 'DESC'. - * @type string|array $orderby Sort retrieved posts by parameter. One or more options may be - * passed. To use 'meta_value', or 'meta_value_num', - * 'meta_key=keyname' must be also be defined. To sort by a - * specific `$meta_query` clause, use that clause's array key. - * Accepts 'none', 'name', 'author', 'date', 'title', - * 'modified', 'menu_order', 'parent', 'ID', 'rand', - * 'relevance', 'RAND(x)' (where 'x' is an integer seed value), - * 'comment_count', 'meta_value', 'meta_value_num', 'post__in', - * 'post_name__in', 'post_parent__in', and the array keys - * of `$meta_query`. Default is 'date', except when a search - * is being performed, when the default is 'relevance'. - * @type int $p Post ID. - * @type int $page Show the number of posts that would show up on page X of a - * static front page. - * @type int $paged The number of the current page. - * @type int $page_id Page ID. - * @type string $pagename Page slug. - * @type string $perm Show posts if user has the appropriate capability. - * @type string $ping_status Ping status. - * @type int[] $post__in An array of post IDs to retrieve, sticky posts will be included. - * @type int[] $post__not_in An array of post IDs not to retrieve. Note: a string of comma- - * separated IDs will NOT work. - * @type string $post_mime_type The mime type of the post. Used for 'attachment' post_type. - * @type string[] $post_name__in An array of post slugs that results must match. - * @type int $post_parent Page ID to retrieve child pages for. Use 0 to only retrieve - * top-level pages. - * @type int[] $post_parent__in An array containing parent page IDs to query child pages from. - * @type int[] $post_parent__not_in An array containing parent page IDs not to query child pages from. - * @type string|array $post_type A post type slug (string) or array of post type slugs. - * Default 'any' if using 'tax_query'. - * @type string|array $post_status A post status (string) or array of post statuses. - * @type int $posts_per_page The number of posts to query for. Use -1 to request all posts. - * @type int $posts_per_archive_page The number of posts to query for by archive page. Overrides - * 'posts_per_page' when is_archive(), or is_search() are true. - * @type string $s Search keyword(s). Prepending a term with a hyphen will - * exclude posts matching that term. Eg, 'pillow -sofa' will - * return posts containing 'pillow' but not 'sofa'. The - * character used for exclusion can be modified using the - * the 'wp_query_search_exclusion_prefix' filter. - * @type int $second Second of the minute. Default empty. Accepts numbers 0-59. - * @type bool $sentence Whether to search by phrase. Default false. - * @type bool $suppress_filters Whether to suppress filters. Default false. - * @type string $tag Tag slug. Comma-separated (either), Plus-separated (all). - * @type int[] $tag__and An array of tag IDs (AND in). - * @type int[] $tag__in An array of tag IDs (OR in). - * @type int[] $tag__not_in An array of tag IDs (NOT in). - * @type int $tag_id Tag id or comma-separated list of IDs. - * @type string[] $tag_slug__and An array of tag slugs (AND in). - * @type string[] $tag_slug__in An array of tag slugs (OR in). unless 'ignore_sticky_posts' is - * true. Note: a string of comma-separated IDs will NOT work. - * @type array $tax_query An associative array of WP_Tax_Query arguments. - * See WP_Tax_Query->__construct(). - * @type string $title Post title. - * @type bool $update_post_meta_cache Whether to update the post meta cache. Default true. - * @type bool $update_post_term_cache Whether to update the post term cache. Default true. - * @type bool $lazy_load_term_meta Whether to lazy-load term meta. Setting to false will - * disable cache priming for term meta, so that each - * get_term_meta() call will hit the database. - * Defaults to the value of `$update_post_term_cache`. - * @type int $w The week number of the year. Default empty. Accepts numbers 0-53. - * @type int $year The four-digit year. Default empty. Accepts any four-digit year. + * @type int $attachment_id Attachment post ID. Used for 'attachment' post_type. + * @type int|string $author Author ID, or comma-separated list of IDs. + * @type string $author_name User 'user_nicename'. + * @type int[] $author__in An array of author IDs to query from. + * @type int[] $author__not_in An array of author IDs not to query from. + * @type bool $cache_results Whether to cache post information. Default true. + * @type int|string $cat Category ID or comma-separated list of IDs (this or any children). + * @type int[] $category__and An array of category IDs (AND in). + * @type int[] $category__in An array of category IDs (OR in, no children). + * @type int[] $category__not_in An array of category IDs (NOT in). + * @type string $category_name Use category slug (not name, this or any children). + * @type array|int $comment_count Filter results by comment count. Provide an integer to match + * comment count exactly. Provide an array with integer 'value' + * and 'compare' operator ('=', '!=', '>', '>=', '<', '<=' ) to + * compare against comment_count in a specific way. + * @type string $comment_status Comment status. + * @type int $comments_per_page The number of comments to return per page. + * Default 'comments_per_page' option. + * @type array $date_query An associative array of WP_Date_Query arguments. + * See WP_Date_Query::__construct(). + * @type int $day Day of the month. Default empty. Accepts numbers 1-31. + * @type bool $exact Whether to search by exact keyword. Default false. + * @type string $fields Post fields to query for. Accepts: + * - '' Returns an array of complete post objects (`WP_Post[]`). + * - 'ids' Returns an array of post IDs (`int[]`). + * - 'id=>parent' Returns an associative array of parent post IDs, + * keyed by post ID (`int[]`). + * Default ''. + * @type int $hour Hour of the day. Default empty. Accepts numbers 0-23. + * @type int|bool $ignore_sticky_posts Whether to ignore sticky posts or not. Setting this to false + * excludes stickies from 'post__in'. Accepts 1|true, 0|false. + * Default false. + * @type int $m Combination YearMonth. Accepts any four-digit year and month + * numbers 1-12. Default empty. + * @type string|string[] $meta_key Meta key or keys to filter by. + * @type string|string[] $meta_value Meta value or values to filter by. + * @type string $meta_compare MySQL operator used for comparing the meta value. + * See WP_Meta_Query::__construct for accepted values and default value. + * @type string $meta_compare_key MySQL operator used for comparing the meta key. + * See WP_Meta_Query::__construct for accepted values and default value. + * @type string $meta_type MySQL data type that the meta_value column will be CAST to for comparisons. + * See WP_Meta_Query::__construct for accepted values and default value. + * @type string $meta_type_key MySQL data type that the meta_key column will be CAST to for comparisons. + * See WP_Meta_Query::__construct for accepted values and default value. + * @type array $meta_query An associative array of WP_Meta_Query arguments. + * See WP_Meta_Query::__construct for accepted values. + * @type int $menu_order The menu order of the posts. + * @type int $minute Minute of the hour. Default empty. Accepts numbers 0-59. + * @type int $monthnum The two-digit month. Default empty. Accepts numbers 1-12. + * @type string $name Post slug. + * @type bool $nopaging Show all posts (true) or paginate (false). Default false. + * @type bool $no_found_rows Whether to skip counting the total rows found. Enabling can improve + * performance. Default false. + * @type int $offset The number of posts to offset before retrieval. + * @type string $order Designates ascending or descending order of posts. Default 'DESC'. + * Accepts 'ASC', 'DESC'. + * @type string|array $orderby Sort retrieved posts by parameter. One or more options may be passed. + * To use 'meta_value', or 'meta_value_num', 'meta_key=keyname' must be + * also be defined. To sort by a specific `$meta_query` clause, use that + * clause's array key. Accepts: + * - 'none' + * - 'name' + * - 'author' + * - 'date' + * - 'title' + * - 'modified' + * - 'menu_order' + * - 'parent' + * - 'ID' + * - 'rand' + * - 'relevance' + * - 'RAND(x)' (where 'x' is an integer seed value) + * - 'comment_count' + * - 'meta_value' + * - 'meta_value_num' + * - 'post__in' + * - 'post_name__in' + * - 'post_parent__in' + * - The array keys of `$meta_query`. + * Default is 'date', except when a search is being performed, when + * the default is 'relevance'. + * @type int $p Post ID. + * @type int $page Show the number of posts that would show up on page X of a + * static front page. + * @type int $paged The number of the current page. + * @type int $page_id Page ID. + * @type string $pagename Page slug. + * @type string $perm Show posts if user has the appropriate capability. + * @type string $ping_status Ping status. + * @type int[] $post__in An array of post IDs to retrieve, sticky posts will be included. + * @type int[] $post__not_in An array of post IDs not to retrieve. Note: a string of comma- + * separated IDs will NOT work. + * @type string $post_mime_type The mime type of the post. Used for 'attachment' post_type. + * @type string[] $post_name__in An array of post slugs that results must match. + * @type int $post_parent Page ID to retrieve child pages for. Use 0 to only retrieve + * top-level pages. + * @type int[] $post_parent__in An array containing parent page IDs to query child pages from. + * @type int[] $post_parent__not_in An array containing parent page IDs not to query child pages from. + * @type string|array $post_type A post type slug (string) or array of post type slugs. + * Default 'any' if using 'tax_query'. + * @type string|array $post_status A post status (string) or array of post statuses. + * @type int $posts_per_page The number of posts to query for. Use -1 to request all posts. + * @type int $posts_per_archive_page The number of posts to query for by archive page. Overrides + * 'posts_per_page' when is_archive(), or is_search() are true. + * @type string $s Search keyword(s). Prepending a term with a hyphen will + * exclude posts matching that term. Eg, 'pillow -sofa' will + * return posts containing 'pillow' but not 'sofa'. The + * character used for exclusion can be modified using the + * the 'wp_query_search_exclusion_prefix' filter. + * @type int $second Second of the minute. Default empty. Accepts numbers 0-59. + * @type bool $sentence Whether to search by phrase. Default false. + * @type bool $suppress_filters Whether to suppress filters. Default false. + * @type string $tag Tag slug. Comma-separated (either), Plus-separated (all). + * @type int[] $tag__and An array of tag IDs (AND in). + * @type int[] $tag__in An array of tag IDs (OR in). + * @type int[] $tag__not_in An array of tag IDs (NOT in). + * @type int $tag_id Tag id or comma-separated list of IDs. + * @type string[] $tag_slug__and An array of tag slugs (AND in). + * @type string[] $tag_slug__in An array of tag slugs (OR in). unless 'ignore_sticky_posts' is + * true. Note: a string of comma-separated IDs will NOT work. + * @type array $tax_query An associative array of WP_Tax_Query arguments. + * See WP_Tax_Query->__construct(). + * @type string $title Post title. + * @type bool $update_post_meta_cache Whether to update the post meta cache. Default true. + * @type bool $update_post_term_cache Whether to update the post term cache. Default true. + * @type bool $lazy_load_term_meta Whether to lazy-load term meta. Setting to false will + * disable cache priming for term meta, so that each + * get_term_meta() call will hit the database. + * Defaults to the value of `$update_post_term_cache`. + * @type int $w The week number of the year. Default empty. Accepts numbers 0-53. + * @type int $year The four-digit year. Default empty. Accepts any four-digit year. * } */ public function parse_query( $query = '' ) { diff --git a/wp-includes/class-wp-site-query.php b/wp-includes/class-wp-site-query.php index 4445f6880f..703c9580f1 100644 --- a/wp-includes/class-wp-site-query.php +++ b/wp-includes/class-wp-site-query.php @@ -109,62 +109,74 @@ class WP_Site_Query { * @since 4.6.0 * @since 4.8.0 Introduced the 'lang_id', 'lang__in', and 'lang__not_in' parameters. * @since 5.1.0 Introduced the 'update_site_meta_cache', 'meta_query', 'meta_key', - * 'meta_value', 'meta_type' and 'meta_compare' parameters. + * 'meta_compare_key', 'meta_value', 'meta_type', and 'meta_compare' parameters. + * @since 5.3.0 Introduced the 'meta_type_key' parameter. * * @param string|array $query { * Optional. Array or query string of site query parameters. Default empty. * - * @type int[] $site__in Array of site IDs to include. Default empty. - * @type int[] $site__not_in Array of site IDs to exclude. Default empty. - * @type bool $count Whether to return a site count (true) or array of site objects. - * Default false. - * @type array $date_query Date query clauses to limit sites by. See WP_Date_Query. - * Default null. - * @type string $fields Site fields to return. Accepts 'ids' (returns an array of site IDs) - * or empty (returns an array of complete site objects). Default empty. - * @type int $ID A site ID to only return that site. Default empty. - * @type int $number Maximum number of sites to retrieve. Default 100. - * @type int $offset Number of sites to offset the query. Used to build LIMIT clause. - * Default 0. - * @type bool $no_found_rows Whether to disable the `SQL_CALC_FOUND_ROWS` query. Default true. - * @type string|array $orderby Site status or array of statuses. Accepts 'id', 'domain', 'path', - * 'network_id', 'last_updated', 'registered', 'domain_length', - * 'path_length', 'site__in' and 'network__in'. Also accepts false, - * an empty array, or 'none' to disable `ORDER BY` clause. - * Default 'id'. - * @type string $order How to order retrieved sites. Accepts 'ASC', 'DESC'. Default 'ASC'. - * @type int $network_id Limit results to those affiliated with a given network ID. If 0, - * include all networks. Default 0. - * @type int[] $network__in Array of network IDs to include affiliated sites for. Default empty. - * @type int[] $network__not_in Array of network IDs to exclude affiliated sites for. Default empty. - * @type string $domain Limit results to those affiliated with a given domain. Default empty. - * @type string[] $domain__in Array of domains to include affiliated sites for. Default empty. - * @type string[] $domain__not_in Array of domains to exclude affiliated sites for. Default empty. - * @type string $path Limit results to those affiliated with a given path. Default empty. - * @type string[] $path__in Array of paths to include affiliated sites for. Default empty. - * @type string[] $path__not_in Array of paths to exclude affiliated sites for. Default empty. - * @type int $public Limit results to public sites. Accepts '1' or '0'. Default empty. - * @type int $archived Limit results to archived sites. Accepts '1' or '0'. Default empty. - * @type int $mature Limit results to mature sites. Accepts '1' or '0'. Default empty. - * @type int $spam Limit results to spam sites. Accepts '1' or '0'. Default empty. - * @type int $deleted Limit results to deleted sites. Accepts '1' or '0'. Default empty. - * @type int $lang_id Limit results to a language ID. Default empty. - * @type string[] $lang__in Array of language IDs to include affiliated sites for. Default empty. - * @type string[] $lang__not_in Array of language IDs to exclude affiliated sites for. Default empty. - * @type string $search Search term(s) to retrieve matching sites for. Default empty. - * @type string[] $search_columns Array of column names to be searched. Accepts 'domain' and 'path'. - * Default empty array. - * @type bool $update_site_cache Whether to prime the cache for found sites. Default true. - * @type bool $update_site_meta_cache Whether to prime the metadata cache for found sites. Default true. - * @type array $meta_query Meta query clauses to limit retrieved sites by. See `WP_Meta_Query`. - * Default empty. - * @type string $meta_key Limit sites to those matching a specific metadata key. - * Can be used in conjunction with `$meta_value`. Default empty. - * @type string $meta_value Limit sites to those matching a specific metadata value. - * Usually used in conjunction with `$meta_key`. Default empty. - * @type string $meta_type Data type that the `$meta_value` column will be CAST to for - * comparisons. Default empty. - * @type string $meta_compare Comparison operator to test the `$meta_value`. Default empty. + * @type int[] $site__in Array of site IDs to include. Default empty. + * @type int[] $site__not_in Array of site IDs to exclude. Default empty. + * @type bool $count Whether to return a site count (true) or array of site objects. + * Default false. + * @type array $date_query Date query clauses to limit sites by. See WP_Date_Query. + * Default null. + * @type string $fields Site fields to return. Accepts 'ids' (returns an array of site IDs) + * or empty (returns an array of complete site objects). Default empty. + * @type int $ID A site ID to only return that site. Default empty. + * @type int $number Maximum number of sites to retrieve. Default 100. + * @type int $offset Number of sites to offset the query. Used to build LIMIT clause. + * Default 0. + * @type bool $no_found_rows Whether to disable the `SQL_CALC_FOUND_ROWS` query. Default true. + * @type string|array $orderby Site status or array of statuses. Accepts: + * - 'id' + * - 'domain' + * - 'path' + * - 'network_id' + * - 'last_updated' + * - 'registered' + * - 'domain_length' + * - 'path_length' + * - 'site__in' + * - 'network__in' + * - false, an empty array, or 'none' to disable `ORDER BY` clause. + * Default 'id'. + * @type string $order How to order retrieved sites. Accepts 'ASC', 'DESC'. Default 'ASC'. + * @type int $network_id Limit results to those affiliated with a given network ID. If 0, + * include all networks. Default 0. + * @type int[] $network__in Array of network IDs to include affiliated sites for. Default empty. + * @type int[] $network__not_in Array of network IDs to exclude affiliated sites for. Default empty. + * @type string $domain Limit results to those affiliated with a given domain. Default empty. + * @type string[] $domain__in Array of domains to include affiliated sites for. Default empty. + * @type string[] $domain__not_in Array of domains to exclude affiliated sites for. Default empty. + * @type string $path Limit results to those affiliated with a given path. Default empty. + * @type string[] $path__in Array of paths to include affiliated sites for. Default empty. + * @type string[] $path__not_in Array of paths to exclude affiliated sites for. Default empty. + * @type int $public Limit results to public sites. Accepts '1' or '0'. Default empty. + * @type int $archived Limit results to archived sites. Accepts '1' or '0'. Default empty. + * @type int $mature Limit results to mature sites. Accepts '1' or '0'. Default empty. + * @type int $spam Limit results to spam sites. Accepts '1' or '0'. Default empty. + * @type int $deleted Limit results to deleted sites. Accepts '1' or '0'. Default empty. + * @type int $lang_id Limit results to a language ID. Default empty. + * @type string[] $lang__in Array of language IDs to include affiliated sites for. Default empty. + * @type string[] $lang__not_in Array of language IDs to exclude affiliated sites for. Default empty. + * @type string $search Search term(s) to retrieve matching sites for. Default empty. + * @type string[] $search_columns Array of column names to be searched. Accepts 'domain' and 'path'. + * Default empty array. + * @type bool $update_site_cache Whether to prime the cache for found sites. Default true. + * @type bool $update_site_meta_cache Whether to prime the metadata cache for found sites. Default true. + * @type string|string[] $meta_key Meta key or keys to filter by. + * @type string|string[] $meta_value Meta value or values to filter by. + * @type string $meta_compare MySQL operator used for comparing the meta value. + * See WP_Meta_Query::__construct for accepted values and default value. + * @type string $meta_compare_key MySQL operator used for comparing the meta key. + * See WP_Meta_Query::__construct for accepted values and default value. + * @type string $meta_type MySQL data type that the meta_value column will be CAST to for comparisons. + * See WP_Meta_Query::__construct for accepted values and default value. + * @type string $meta_type_key MySQL data type that the meta_key column will be CAST to for comparisons. + * See WP_Meta_Query::__construct for accepted values and default value. + * @type array $meta_query An associative array of WP_Meta_Query arguments. + * See WP_Meta_Query::__construct for accepted values. * } */ public function __construct( $query = '' ) { diff --git a/wp-includes/class-wp-term-query.php b/wp-includes/class-wp-term-query.php index f5388e6624..68b9f2954c 100644 --- a/wp-includes/class-wp-term-query.php +++ b/wp-includes/class-wp-term-query.php @@ -88,103 +88,108 @@ class WP_Term_Query { * @since 4.6.0 Introduced 'term_taxonomy_id' parameter. * @since 4.7.0 Introduced 'object_ids' parameter. * @since 4.9.0 Added 'slug__in' support for 'orderby'. + * @since 5.1.0 Introduced the 'meta_compare_key' parameter. + * @since 5.3.0 Introduced the 'meta_type_key' parameter. * * @param string|array $query { * Optional. Array or query string of term query parameters. Default empty. * - * @type string|array $taxonomy Taxonomy name, or array of taxonomies, to which results should - * be limited. - * @type int|int[] $object_ids Object ID, or array of object IDs. Results will be - * limited to terms associated with these objects. - * @type string $orderby Field(s) to order terms by. Accepts: - * * Term fields ('name', 'slug', 'term_group', 'term_id', 'id', - * 'description', 'parent', 'term_order'). Unless `$object_ids` - * is not empty, 'term_order' is treated the same as 'term_id'. - * * 'count' to use the number of objects associated with the term. - * * 'include' to match the 'order' of the `$include` param. - * * 'slug__in' to match the 'order' of the `$slug` param. - * * 'meta_value' - * * 'meta_value_num'. - * * The value of `$meta_key`. - * * The array keys of `$meta_query`. - * * 'none' to omit the ORDER BY clause. - * Default 'name'. - * @type string $order Whether to order terms in ascending or descending order. - * Accepts 'ASC' (ascending) or 'DESC' (descending). - * Default 'ASC'. - * @type bool|int $hide_empty Whether to hide terms not assigned to any posts. Accepts - * 1|true or 0|false. Default 1|true. - * @type int[]|string $include Array or comma/space-separated string of term IDs to include. - * Default empty array. - * @type int[]|string $exclude Array or comma/space-separated string of term IDs to exclude. - * If `$include` is non-empty, `$exclude` is ignored. - * Default empty array. - * @type int[]|string $exclude_tree Array or comma/space-separated string of term IDs to exclude - * along with all of their descendant terms. If `$include` is - * non-empty, `$exclude_tree` is ignored. Default empty array. - * @type int|string $number Maximum number of terms to return. Accepts ''|0 (all) or any - * positive number. Default ''|0 (all). Note that $number may - * not return accurate results when coupled with `$object_ids`. - * See #41796 for details. - * @type int $offset The number by which to offset the terms query. Default empty. - * @type string $fields Term fields to query for. Accepts: - * * 'all' Returns an array of complete term objects (`WP_Term[]`). - * * 'all_with_object_id' Returns an array of term objects - * with the 'object_id' param (`WP_Term[]`). Works only - * when the `$object_ids` parameter is populated. - * * 'ids' Returns an array of term IDs (`int[]`). - * * 'tt_ids' Returns an array of term taxonomy IDs (`int[]`). - * * 'names' Returns an array of term names (`string[]`). - * * 'slugs' Returns an array of term slugs (`string[]`). - * * 'count' Returns the number of matching terms (`int`). - * * 'id=>parent' Returns an associative array of parent term IDs, - * keyed by term ID (`int[]`). - * * 'id=>name' Returns an associative array of term names, - * keyed by term ID (`string[]`). - * * 'id=>slug' Returns an associative array of term slugs, - * keyed by term ID (`string[]`). - * Default 'all'. - * @type bool $count Whether to return a term count. If true, will take precedence - * over `$fields`. Default false. - * @type string|array $name Name or array of names to return term(s) for. - * Default empty. - * @type string|array $slug Slug or array of slugs to return term(s) for. - * Default empty. - * @type int|int[] $term_taxonomy_id Term taxonomy ID, or array of term taxonomy IDs, - * to match when querying terms. - * @type bool $hierarchical Whether to include terms that have non-empty descendants - * (even if `$hide_empty` is set to true). Default true. - * @type string $search Search criteria to match terms. Will be SQL-formatted with - * wildcards before and after. Default empty. - * @type string $name__like Retrieve terms with criteria by which a term is LIKE - * `$name__like`. Default empty. - * @type string $description__like Retrieve terms where the description is LIKE - * `$description__like`. Default empty. - * @type bool $pad_counts Whether to pad the quantity of a term's children in the - * quantity of each term's "count" object variable. - * Default false. - * @type string $get Whether to return terms regardless of ancestry or whether the - * terms are empty. Accepts 'all' or '' (disabled). - * Default ''. - * @type int $child_of Term ID to retrieve child terms of. If multiple taxonomies - * are passed, `$child_of` is ignored. Default 0. - * @type int $parent Parent term ID to retrieve direct-child terms of. - * Default empty. - * @type bool $childless True to limit results to terms that have no children. - * This parameter has no effect on non-hierarchical taxonomies. - * Default false. - * @type string $cache_domain Unique cache key to be produced when this query is stored in - * an object cache. Default 'core'. - * @type bool $update_term_meta_cache Whether to prime meta caches for matched terms. Default true. - * @type array $meta_query Meta query clauses to limit retrieved terms by. - * See `WP_Meta_Query`. Default empty. - * @type string $meta_key Limit terms to those matching a specific metadata key. - * Can be used in conjunction with `$meta_value`. Default empty. - * @type string $meta_value Limit terms to those matching a specific metadata value. - * Usually used in conjunction with `$meta_key`. Default empty. - * @type string $meta_type MySQL data type that the `$meta_value` will be CAST to for - * comparisons. Default empty. - * @type string $meta_compare Comparison operator to test the 'meta_value'. Default empty. + * @type string|array $taxonomy Taxonomy name, or array of taxonomies, to which results should + * be limited. + * @type int|int[] $object_ids Object ID, or array of object IDs. Results will be + * limited to terms associated with these objects. + * @type string $orderby Field(s) to order terms by. Accepts: + * - Term fields ('name', 'slug', 'term_group', 'term_id', 'id', + * 'description', 'parent', 'term_order'). Unless `$object_ids` + * is not empty, 'term_order' is treated the same as 'term_id'. + * - 'count' to use the number of objects associated with the term. + * - 'include' to match the 'order' of the `$include` param. + * - 'slug__in' to match the 'order' of the `$slug` param. + * - 'meta_value' + * - 'meta_value_num'. + * - The value of `$meta_key`. + * - The array keys of `$meta_query`. + * - 'none' to omit the ORDER BY clause. + * Default 'name'. + * @type string $order Whether to order terms in ascending or descending order. + * Accepts 'ASC' (ascending) or 'DESC' (descending). + * Default 'ASC'. + * @type bool|int $hide_empty Whether to hide terms not assigned to any posts. Accepts + * 1|true or 0|false. Default 1|true. + * @type int[]|string $include Array or comma/space-separated string of term IDs to include. + * Default empty array. + * @type int[]|string $exclude Array or comma/space-separated string of term IDs to exclude. + * If `$include` is non-empty, `$exclude` is ignored. + * Default empty array. + * @type int[]|string $exclude_tree Array or comma/space-separated string of term IDs to exclude + * along with all of their descendant terms. If `$include` is + * non-empty, `$exclude_tree` is ignored. Default empty array. + * @type int|string $number Maximum number of terms to return. Accepts ''|0 (all) or any + * positive number. Default ''|0 (all). Note that `$number` may + * not return accurate results when coupled with `$object_ids`. + * See #41796 for details. + * @type int $offset The number by which to offset the terms query. Default empty. + * @type string $fields Term fields to query for. Accepts: + * - 'all' Returns an array of complete term objects (`WP_Term[]`). + * - 'all_with_object_id' Returns an array of term objects + * with the 'object_id' param (`WP_Term[]`). Works only + * when the `$object_ids` parameter is populated. + * - 'ids' Returns an array of term IDs (`int[]`). + * - 'tt_ids' Returns an array of term taxonomy IDs (`int[]`). + * - 'names' Returns an array of term names (`string[]`). + * - 'slugs' Returns an array of term slugs (`string[]`). + * - 'count' Returns the number of matching terms (`int`). + * - 'id=>parent' Returns an associative array of parent term IDs, + * keyed by term ID (`int[]`). + * - 'id=>name' Returns an associative array of term names, + * keyed by term ID (`string[]`). + * - 'id=>slug' Returns an associative array of term slugs, + * keyed by term ID (`string[]`). + * Default 'all'. + * @type bool $count Whether to return a term count. If true, will take precedence + * over `$fields`. Default false. + * @type string|array $name Name or array of names to return term(s) for. + * Default empty. + * @type string|array $slug Slug or array of slugs to return term(s) for. + * Default empty. + * @type int|int[] $term_taxonomy_id Term taxonomy ID, or array of term taxonomy IDs, + * to match when querying terms. + * @type bool $hierarchical Whether to include terms that have non-empty descendants + * (even if `$hide_empty` is set to true). Default true. + * @type string $search Search criteria to match terms. Will be SQL-formatted with + * wildcards before and after. Default empty. + * @type string $name__like Retrieve terms with criteria by which a term is LIKE + * `$name__like`. Default empty. + * @type string $description__like Retrieve terms where the description is LIKE + * `$description__like`. Default empty. + * @type bool $pad_counts Whether to pad the quantity of a term's children in the + * quantity of each term's "count" object variable. + * Default false. + * @type string $get Whether to return terms regardless of ancestry or whether the + * terms are empty. Accepts 'all' or '' (disabled). + * Default ''. + * @type int $child_of Term ID to retrieve child terms of. If multiple taxonomies + * are passed, `$child_of` is ignored. Default 0. + * @type int $parent Parent term ID to retrieve direct-child terms of. + * Default empty. + * @type bool $childless True to limit results to terms that have no children. + * This parameter has no effect on non-hierarchical taxonomies. + * Default false. + * @type string $cache_domain Unique cache key to be produced when this query is stored in + * an object cache. Default 'core'. + * @type bool $update_term_meta_cache Whether to prime meta caches for matched terms. Default true. + * @type string|string[] $meta_key Meta key or keys to filter by. + * @type string|string[] $meta_value Meta value or values to filter by. + * @type string $meta_compare MySQL operator used for comparing the meta value. + * See WP_Meta_Query::__construct for accepted values and default value. + * @type string $meta_compare_key MySQL operator used for comparing the meta key. + * See WP_Meta_Query::__construct for accepted values and default value. + * @type string $meta_type MySQL data type that the meta_value column will be CAST to for comparisons. + * See WP_Meta_Query::__construct for accepted values and default value. + * @type string $meta_type_key MySQL data type that the meta_key column will be CAST to for comparisons. + * See WP_Meta_Query::__construct for accepted values and default value. + * @type array $meta_query An associative array of WP_Meta_Query arguments. + * See WP_Meta_Query::__construct for accepted values. * } */ public function __construct( $query = '' ) { diff --git a/wp-includes/class-wp-user-query.php b/wp-includes/class-wp-user-query.php index 936ffe89bf..e0a669f732 100644 --- a/wp-includes/class-wp-user-query.php +++ b/wp-includes/class-wp-user-query.php @@ -136,6 +136,8 @@ class WP_User_Query { * querying for all users with using -1. * @since 4.7.0 Added 'nicename', 'nicename__in', 'nicename__not_in', 'login', 'login__in', * and 'login__not_in' parameters. + * @since 5.1.0 Introduced the 'meta_compare_key' parameter. + * @since 5.3.0 Introduced the 'meta_type_key' parameter. * @since 5.9.0 Added 'capability', 'capability__in', and 'capability__not_in' parameters. * * @global wpdb $wpdb WordPress database abstraction object. @@ -144,85 +146,108 @@ class WP_User_Query { * @param string|array $query { * Optional. Array or string of Query parameters. * - * @type int $blog_id The site ID. Default is the current site. - * @type string|array $role An array or a comma-separated list of role names that users must match - * to be included in results. Note that this is an inclusive list: users - * must match *each* role. Default empty. - * @type string[] $role__in An array of role names. Matched users must have at least one of these - * roles. Default empty array. - * @type string[] $role__not_in An array of role names to exclude. Users matching one or more of these - * roles will not be included in results. Default empty array. - * @type string $capability An array or a comma-separated list of capability names that users must match - * to be included in results. Note that this is an inclusive list: users - * must match *each* capability. - * Does NOT work for capabilities not in the database or filtered via {@see 'map_meta_cap'}. - * Default empty. - * @type string[] $capability__in An array of capability names. Matched users must have at least one of these - * capabilities. - * Does NOT work for capabilities not in the database or filtered via {@see 'map_meta_cap'}. - * Default empty array. - * @type string[] $capability__not_in An array of capability names to exclude. Users matching one or more of these - * capabilities will not be included in results. - * Does NOT work for capabilities not in the database or filtered via {@see 'map_meta_cap'}. - * Default empty array. - * @type string $meta_key User meta key. Default empty. - * @type string $meta_value User meta value. Default empty. - * @type string $meta_compare Comparison operator to test the `$meta_value`. Accepts '=', '!=', - * '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', - * 'BETWEEN', 'NOT BETWEEN', 'EXISTS', 'NOT EXISTS', 'REGEXP', - * 'NOT REGEXP', or 'RLIKE'. Default '='. - * @type int[] $include An array of user IDs to include. Default empty array. - * @type int[] $exclude An array of user IDs to exclude. Default empty array. - * @type string $search Search keyword. Searches for possible string matches on columns. - * When `$search_columns` is left empty, it tries to determine which - * column to search in based on search string. Default empty. - * @type string[] $search_columns Array of column names to be searched. Accepts 'ID', 'user_login', - * 'user_email', 'user_url', 'user_nicename', 'display_name'. - * Default empty array. - * @type string|array $orderby Field(s) 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'), 'include', 'user_login' - * (or 'login'), 'login__in', 'user_nicename' (or 'nicename'), - * 'nicename__in', 'user_email (or 'email'), 'user_url' (or 'url'), - * 'user_registered' (or 'registered'), 'post_count', 'meta_value', - * 'meta_value_num', the value of `$meta_key`, or an array key of - * `$meta_query`. 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. - * @type int $number Number of users to limit the query for. Can be used in - * conjunction with pagination. Value -1 (all) is supported, but - * should be used with caution on larger sites. - * Default -1 (all users). - * @type int $paged When used with number, defines the page of results to return. - * Default 1. - * @type bool $count_total Whether to count the total number of users found. If pagination - * is not needed, setting this to false can improve performance. - * Default true. - * @type string|array $fields Which fields to return. Single or all fields (string), or array - * of fields. Accepts 'ID', 'display_name', 'user_login', - * 'user_nicename', 'user_email', 'user_url', 'user_registered'. - * Use 'all' for all fields and 'all_with_meta' to include - * meta fields. Default 'all'. - * @type string $who Type of users to query. Accepts 'authors'. - * Default empty (all users). - * @type bool|array $has_published_posts Pass an array of post types to filter results to users who have - * published posts in those post types. `true` is an alias for all - * public post types. - * @type string $nicename The user nicename. Default empty. - * @type string[] $nicename__in An array of nicenames to include. Users matching one of these - * nicenames will be included in results. Default empty array. - * @type string[] $nicename__not_in An array of nicenames to exclude. Users matching one of these - * nicenames will not be included in results. Default empty array. - * @type string $login The user login. Default empty. - * @type string[] $login__in An array of logins to include. Users matching one of these - * logins will be included in results. Default empty array. - * @type string[] $login__not_in An array of logins to exclude. Users matching one of these - * logins will not be included in results. Default empty array. + * @type int $blog_id The site ID. Default is the current site. + * @type string|array $role An array or a comma-separated list of role names that users must match + * to be included in results. Note that this is an inclusive list: users + * must match *each* role. Default empty. + * @type string[] $role__in An array of role names. Matched users must have at least one of these + * roles. Default empty array. + * @type string[] $role__not_in An array of role names to exclude. Users matching one or more of these + * roles will not be included in results. Default empty array. + * @type string|string[] $meta_key Meta key or keys to filter by. + * @type string|string[] $meta_value Meta value or values to filter by. + * @type string $meta_compare MySQL operator used for comparing the meta value. + * See WP_Meta_Query::__construct for accepted values and default value. + * @type string $meta_compare_key MySQL operator used for comparing the meta key. + * See WP_Meta_Query::__construct for accepted values and default value. + * @type string $meta_type MySQL data type that the meta_value column will be CAST to for comparisons. + * See WP_Meta_Query::__construct for accepted values and default value. + * @type string $meta_type_key MySQL data type that the meta_key column will be CAST to for comparisons. + * See WP_Meta_Query::__construct for accepted values and default value. + * @type array $meta_query An associative array of WP_Meta_Query arguments. + * See WP_Meta_Query::__construct for accepted values. + * @type string $capability An array or a comma-separated list of capability names that users must match + * to be included in results. Note that this is an inclusive list: users + * must match *each* capability. + * Does NOT work for capabilities not in the database or filtered via {@see 'map_meta_cap'}. + * Default empty. + * @type string[] $capability__in An array of capability names. Matched users must have at least one of these + * capabilities. + * Does NOT work for capabilities not in the database or filtered via {@see 'map_meta_cap'}. + * Default empty array. + * @type string[] $capability__not_in An array of capability names to exclude. Users matching one or more of these + * capabilities will not be included in results. + * Does NOT work for capabilities not in the database or filtered via {@see 'map_meta_cap'}. + * Default empty array. + * @type int[] $include An array of user IDs to include. Default empty array. + * @type int[] $exclude An array of user IDs to exclude. Default empty array. + * @type string $search Search keyword. Searches for possible string matches on columns. + * When `$search_columns` is left empty, it tries to determine which + * column to search in based on search string. Default empty. + * @type string[] $search_columns Array of column names to be searched. Accepts 'ID', 'user_login', + * 'user_email', 'user_url', 'user_nicename', 'display_name'. + * Default empty array. + * @type string|array $orderby Field(s) 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') + * - 'include' + * - 'user_login' (or 'login') + * - 'login__in' + * - 'user_nicename' (or 'nicename'), + * - 'nicename__in' + * - 'user_email (or 'email') + * - 'user_url' (or 'url'), + * - 'user_registered' (or 'registered') + * - 'post_count' + * - 'meta_value', + * - 'meta_value_num' + * - The value of `$meta_key` + * - An array key of `$meta_query` + * 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. + * @type int $number Number of users to limit the query for. Can be used in + * conjunction with pagination. Value -1 (all) is supported, but + * should be used with caution on larger sites. + * Default -1 (all users). + * @type int $paged When used with number, defines the page of results to return. + * Default 1. + * @type bool $count_total Whether to count the total number of users found. If pagination + * is not needed, setting this to false can improve performance. + * Default true. + * @type string|array $fields Which fields to return. Single or all fields (string), or array + * of fields. Accepts: + * - 'ID' + * - 'display_name' + * - 'user_login' + * - 'user_nicename' + * - 'user_email' + * - 'user_url' + * - 'user_registered' + * - 'all' for all fields + * - 'all_with_meta' to include meta fields. + * Default 'all'. + * @type string $who Type of users to query. Accepts 'authors'. + * Default empty (all users). + * @type bool|array $has_published_posts Pass an array of post types to filter results to users who have + * published posts in those post types. `true` is an alias for all + * public post types. + * @type string $nicename The user nicename. Default empty. + * @type string[] $nicename__in An array of nicenames to include. Users matching one of these + * nicenames will be included in results. Default empty array. + * @type string[] $nicename__not_in An array of nicenames to exclude. Users matching one of these + * nicenames will not be included in results. Default empty array. + * @type string $login The user login. Default empty. + * @type string[] $login__in An array of logins to include. Users matching one of these + * logins will be included in results. Default empty array. + * @type string[] $login__not_in An array of logins to exclude. Users matching one of these + * logins will not be included in results. Default empty array. * } */ public function prepare_query( $query = array() ) { diff --git a/wp-includes/version.php b/wp-includes/version.php index d37aed574e..8bf3c9eccb 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '5.9-alpha-52225'; +$wp_version = '5.9-alpha-52226'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.