Cache the results of database queries within `WP_User_Query` class. Only cache queries that are requesting 3 or less fields so that caches are not storing full user objects. Cache results are stored in a new global cache group named `users-queries`. Add a new parameter to `WP_User_Query` called `cache_results` to allow developers to opt out of a receiving cached results. `cache_results` parameter defaults to true. Also add a new helper function called `wp_cache_set_users_last_changed`, similar to `wp_cache_set_posts_last_changed` that incroments last changed value in cache group `users`. Ensure that `wp_cache_set_users_last_changed` is called whenever user / user meta is modified for proper cache invalidation.
Props johnjamesjacoby, spacedmonkey, westi, dd32, strategio, srikanthmeenakshi, OllieJones, khoipro, rjasdfiii, flixos90, mukesh27, peterwilsoncc.
Fixes#40613.
Built from https://develop.svn.wordpress.org/trunk@55657
git-svn-id: http://core.svn.wordpress.org/trunk@55169 1a063a9b-81f0-0310-95a4-ce76da25c4cd
In #55594 user meta caching was enabled by default when making a `WP_User_Query`. Previously, this was only enabled if a developer specifically queried for 'all_with_meta'
fields. User meta caching is implemented using a pluggable function, `cache_users`. If a plugin runs a `WP_User_Query` before pluggable functions have been defined, this
will now cause a fatal error.
In this commit, a `function_exists` check is introduced to avoid calling `cache_users` if it's not defined. Additionally, a `_doing_it_wrong` notice is issued if the
`WP_User_Query::query` method is called before the 'plugins_loaded' hook.
Props carazo, subrataemfluence, oakesjosh, spacedmonkey, obenland, SergeyBiryukov, peterwilsoncc.
Fixes#56952.
Built from https://develop.svn.wordpress.org/trunk@54766
git-svn-id: http://core.svn.wordpress.org/trunk@54318 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Dynamic (non-explicitly declared) properties are deprecated as of PHP 8.2 and are expected to become a fatal error in PHP 9.0.
There are a number of ways to mitigate this:
* If it is an accidental typo for a declared property: fix the typo.
* For known properties: declare them on the class.
* For unknown properties: add the magic `__get()`, `__set()`, et al. methods to the class or let the class extend `stdClass` which has highly optimized versions of these magic methods built in.
* For unknown ''use'' of dynamic properties, the `#[AllowDynamicProperties]` attribute can be added to the class. The attribute will automatically be inherited by child classes.
Trac ticket #56034 is open to investigate and handle the third and fourth type of situations, however it has become clear this will need more time and will not be ready in time for WP 6.1.
To reduce “noise” in the meantime, both in the error logs of WP users moving onto PHP 8.2, in the test run logs of WP itself, in test runs of plugins and themes, as well as to prevent duplicate tickets from being opened for the same issue, this commit adds the `#[AllowDynamicProperties]` attribute to all “parent” classes in WP.
The logic used for this commit is as follows:
* If a class already has the attribute: no action needed.
* If a class does not `extend`: add the attribute.
* If a class does `extend`:
- If it extends `stdClass`: no action needed (as `stdClass` supports dynamic properties).
- If it extends a PHP native class: add the attribute.
- If it extends a class from one of WP's external dependencies: add the attribute.
* In all other cases: no action — the attribute should not be needed as child classes inherit from the parent.
Whether or not a class contains magic methods has not been taken into account, as a review of the currently existing magic methods has shown that those are generally not sturdy enough and often even set dynamic properties (which they should not). See the [https://www.youtube.com/watch?v=vDZWepDQQVE live stream from August 16, 2022] for more details.
This commit only affects classes in the `src` directory of WordPress core.
* Tests should not get this attribute, but should be fixed to not use dynamic properties instead. Patches for this are already being committed under ticket #56033.
* While a number bundled themes (2014, 2019, 2020, 2021) contain classes, they are not a part of this commit and may be updated separately.
Reference: [https://wiki.php.net/rfc/deprecate_dynamic_properties PHP RFC: Deprecate dynamic properties].
Follow-up to [53922].
Props jrf, hellofromTonya, markjaquith, peterwilsoncc, costdev, knutsp, aristath.
See #56513, #56034.
Built from https://develop.svn.wordpress.org/trunk@54133
git-svn-id: http://core.svn.wordpress.org/trunk@53692 1a063a9b-81f0-0310-95a4-ce76da25c4cd
* `$blog_id` global was replaced with `get_current_blog_id()` and is no longer used directly.
* `$wp_roles` global usage was previously undocumented.
Follow-up to [32637], [38457], [51943].
Props shoaibkarimali.
Fixes#56543.
Built from https://develop.svn.wordpress.org/trunk@54119
git-svn-id: http://core.svn.wordpress.org/trunk@53678 1a063a9b-81f0-0310-95a4-ce76da25c4cd
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
spacedmonkey
Sergey Biryukov
TimothyBlynJacobs
Peter Wilson
audrasjb
John Blackbourn
Pascal Birchler
Gary Pendergast
Adam Silverstein
Drew Jaynes
Boone Gorges
Scott Taylor