When querying 'fields' equal to 'all' using the `WP_User_Query` class, this returns an array of `WP_User` objects. A `WP_User` object requires user meta to be primed, as the user's role is stored in user meta. Ensure that all users meta is primed in a single request by calling the `cache_users` function when querying 'fields' equal to 'all'. Soft deprecate fields equal to `all_with_meta` as it now acts the same as 'fields' equal to 'all'.
Props Spacedmonkey, peterwilsoncc, mehulkaklotar, timothyblynjacobs, furi3r.
Fixes#55594.
Built from https://develop.svn.wordpress.org/trunk@53655
git-svn-id: http://core.svn.wordpress.org/trunk@53214 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Restore behaviour of `fields` parameter in `WP_User_Query` to allow developers to specify any database field to be returned either individually or as part of a subset. Add these fields to the documentation.
When a subset of `fields` includes the `id` paramater, include it in the results in both upper and lowercase to maintain backward compatibility.
Follow up to [53327].
Props dd32, pbearne, kraftbj, peterwilsoncc.
Fixes#53177.
Built from https://develop.svn.wordpress.org/trunk@53362
git-svn-id: http://core.svn.wordpress.org/trunk@52951 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Improve validation of `WP_User_Query`'s `fields` argument when passed as an array to ensure it only accepts permitted values. This prevents the invalid values being included in the generated database query.
Expand unit tests to include passing invalid values as part of an array, the lower case value `id`. Correct earlier unit tests to limit database query to one result.
Follow up to [53255].
Props felipeelia.
Fixes#53177.
Built from https://develop.svn.wordpress.org/trunk@53327
git-svn-id: http://core.svn.wordpress.org/trunk@52916 1a063a9b-81f0-0310-95a4-ce76da25c4cd
While using reserved PHP keywords as parameter name labels is allowed, in the context of function calls using named parameters in PHP 8.0+, this will easily lead to confusion. To avoid that, it is recommended not to use reserved keywords as function parameter names.
This commit renames the `$string` parameter to `$search` in `WP_User_Query::get_search_sql()`.
Follow-up to [52946], [52996], [52997], [52998], [53003], [53014], [53029], [53039], [53116], [53117], [53137], [53174], [53184], [53185], [53192], [53193], [53198], [53203], [53207], [53215], [53216], [53220], [53230], [53232], [53236], [53239], [53240], [53242], [53243], [53245], [53246], [53257], [53269], [53270], [53271], [53272], [53273], [53274], [53275].
Props jrf, aristath, poena, justinahinon, SergeyBiryukov.
See #55327.
Built from https://develop.svn.wordpress.org/trunk@53276
git-svn-id: http://core.svn.wordpress.org/trunk@52865 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This change ensures the `fields` parameter is taken into account when running `WP_User_Query` by fixing the conditional statement used to process the `fields` param.
Props rilwis, peterwilsoncc, NomNom99, hellofromTonya, audrasjb, rilwis, Boniu91.
Fixes#53177.
Built from https://develop.svn.wordpress.org/trunk@53255
git-svn-id: http://core.svn.wordpress.org/trunk@52844 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Similar to the existing `role`/`role__in`/`role__not_in` query arguments, this adds support for three new query arguments in `WP_User_Query`:
* `capability`
* `capability__in`
* `capability__not_in`
These can be used to fetch users with (or without) a specific set of capabilities, for example to get all users
with the capability to edit a certain post type.
Under the hood, this will check all existing roles on the site and perform a `LIKE` query against the `capabilities` user meta field to find:
* all users with a role that has this capability
* all users with the capability being assigned directly
Note: In WordPress, not all capabilities are stored in the database. Capabilities can also be modified using filters like `map_meta_cap`. These new query arguments do NOT work for such capabilities.
The prime use case for capability queries is to get all "authors", i.e. users with the capability to edit a certain post type.
Until now, `'who' => 'authors'` was used for this, which relies on user levels. However, user levels were deprecated a long time ago and thus never added to custom roles. This led to constant frustration due to users with custom roles missing from places like author dropdowns.
This updates any usage of `'who' => 'authors'` in core to use capability queries instead.
Subsequently, `'who' => 'authors'` queries are being **deprecated** in favor of these new query arguments.
Also adds a new `capabilities` parameter (mapping to `capability__in` in `WP_User_Query`) to the REST API users controller.
Also updates `twentyfourteen_list_authors()` in Twenty Fourteen to make use of this new functionality, adding a new `twentyfourteen_list_authors_query_args` filter to make it easier to override this behavior.
Props scribu, lgladdly, boonebgorges, spacedmonkey, peterwilsoncc, SergeyBiryukov, swissspidy.
Fixes#16841.
Built from https://develop.svn.wordpress.org/trunk@51943
git-svn-id: http://core.svn.wordpress.org/trunk@51532 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This brings some consistency with the other similar actions:
* `pre_get_comments`
* `pre_get_networks`
* `pre_get_posts`
* `pre_get_sites`
* `pre_user_query`
Follow-up to [29363] and [37572].
Props andy, adamsilverstein, hellofromTonya, desrosj, SergeyBiryukov.
Fixes#50961.
Built from https://develop.svn.wordpress.org/trunk@49637
git-svn-id: http://core.svn.wordpress.org/trunk@49375 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Using the canonical function name for PHP functions is strongly recommended, as aliases may be deprecated or removed without (much) warning.
This replaces all uses of the following:
* `join()` with `implode()`
* `sizeof()` with `count()`
* `is_writeable()` with `is_writable()`
* `doubleval()` with a `(float)` cast
In part, this is a follow-up to #47746.
Props jrf.
See #50767.
Built from https://develop.svn.wordpress.org/trunk@49193
git-svn-id: http://core.svn.wordpress.org/trunk@48955 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Add a new filter `users_pre_query` - filters the users array before the query takes place. Return a non-null value to bypass WordPress's default user queries. Similar to the `posts_pre_query` filter for WP_Query added in #36687. This filter lets you short circuit the WP_User_Query MySQL query to return your own results.
Developers should note that filtering functions that require pagination information are encouraged to set the `total_users` property of the WP_User_Query object, passed to the filter by reference. If WP_User_Query does not perform a database query, it will not have enough information to generate these values itself.
Props tlovett1, birgire, boonebgorges, spacedmonkey.
Fixes#44169.
Built from https://develop.svn.wordpress.org/trunk@44373
git-svn-id: http://core.svn.wordpress.org/trunk@44203 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Prior to about 2013, many class methods lacked even access modifiers which made the `@access` notations that much more useful. Now that we've gotten to a point where the codebase is more mature from a maintenance perspective and we can finally remove these notations. Notable exceptions to this change include standalone functions notated as private as well as some classes still considered to represent "private" APIs.
See #41452.
Built from https://develop.svn.wordpress.org/trunk@41162
git-svn-id: http://core.svn.wordpress.org/trunk@41002 1a063a9b-81f0-0310-95a4-ce76da25c4cd
The `$user_total` member of `WP_User_Query`, and corresponding `get_total()` method, have always been documented as returning an `int`. `$user_total`, however, is populated by `$wpdb->get_var()`, which returns
a string (containing an integer value). Casting the return value from `get_var()` as an `int` rectifies this discrepency.
Props runciters.
Fixes#39297.
Built from https://develop.svn.wordpress.org/trunk@39915
git-svn-id: http://core.svn.wordpress.org/trunk@39852 1a063a9b-81f0-0310-95a4-ce76da25c4cd
New parameters are: `login`, `login__in`, `login__not_in`, `nicename`,
`nicename__in`, `nicename__not_in`.
`login__in` and `nicename__in` are also now valid values for the
'orderby' parameter.
Props ryanplas.
Fixes#36624.
Built from https://develop.svn.wordpress.org/trunk@38715
git-svn-id: http://core.svn.wordpress.org/trunk@38658 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Also use 'back-compat' in some inline comments where backward compatibility is the subject and shorthand feels more natural.
Note: 'backwards compatibility/compatibile' can also be considered correct, though it's primary seen in regular use in British English.
Props ocean90.
Fixes#36835.
Built from https://develop.svn.wordpress.org/trunk@37431
git-svn-id: http://core.svn.wordpress.org/trunk@37397 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Multisite functions use the term "blog" to refer to what we now call a "site," e.g. `get_current_blog_id()`. These functions are here to stay because of our commitment to backwards compatibility. What we can do is set the documentation straight.
See #35417.
Built from https://develop.svn.wordpress.org/trunk@36417
git-svn-id: http://core.svn.wordpress.org/trunk@36384 1a063a9b-81f0-0310-95a4-ce76da25c4cd
spacedmonkey
Sergey Biryukov
Peter Wilson
audrasjb
John Blackbourn
Pascal Birchler
Gary Pendergast
Adam Silverstein
Drew Jaynes
Boone Gorges
Scott Taylor
Eric Lewis