Replaces `trigger_error()` with `wp_trigger_error()` in each of the `WP_User_Query` magic methods.
[56353] added the dynamic properties deprecation messages to the `__get()`, `__set()`, `__isset()`, `__unset()` magic methods. Since that commit, `wp_trigger_error()` was introduced (see [56530]) as a wrapper for `trigger_error()`.
Follow-up to [56353], [56530].
See #58897, #57686.
git-svn-id: https://develop.svn.wordpress.org/trunk@56543 602fd350-edb4-49c9-b593-d223f7449a82
If `$blog_id` equals `0`, it should be treated as the current site ID, and there is no need to switch to a different site.
This commit prevents an unnecessary call to `switch_to_blog()` on single site to avoid a fatal error when using `'orderby' => 'post_count'` and the deprecated `'who' => 'authors'` parameter:
{{{
Uncaught Error: Call to undefined function switch_to_blog() in wp-includes/class-wp-user-query.php:1077
}}}
Follow-up to [55657].
Props dd32, austinginder, RavanH, mukesh27.
Fixes#59011.
git-svn-id: https://develop.svn.wordpress.org/trunk@56381 602fd350-edb4-49c9-b593-d223f7449a82
The unknown use of unknown dynamic property within the `WP_User_Query` property magic methods is now deprecated. A descriptive deprecation notice is provided to alert developers to declare the property on the child class extending `WP_User_Query`.
Changes in this commit:
* Adds a deprecation notice to the `__get()`, `__set()`, `__isset()`, `__unset()` magic methods, i.e. to alert and inform developers when attempting to get/set/isset/unset a dynamic property.
* Fixes `__get()` to explicitly returns `null` when attempting to get a dynamic property.
* Fixes `__set()` by removing the value return after setting a declared property, as (a) unnecessary and (b) `__set()` should return `void` [https://www.php.net/manual/en/language.oop5.overloading.php#object.set per the PHP handbook].
* Fixes `__isset()` to return `false` if not in the `$compat_fields`, as `isset()` and `__isset()` should always return `bool`:
* [https://www.php.net/manual/en/language.oop5.overloading.php#object.isset `__isset()` in the PHP manual]
* [https://www.php.net/manual/en/function.isset.php `isset()` in the PHP manual]
* Adds unit tests for happy and unhappy paths.
For backward compatibility, no changes are made to the internal declared properties listed in `$compat_fields` and accessed through the magic methods.
For example:
A child class uses a property named `$data` that is not declared as a property on the child class. When getting its value, e.g. `$user_query->data`, the `WP_User_Query::__get()` magic method is invoked, the following deprecation notice thrown, and `null` returned:
>The property `data` is not declared. Setting a dynamic property is deprecated since version 6.4.0! Instead, declare the property on the class.
=== Why not remove the magic methods, remove the `$compat_fields` property, and restore the properties `public`?
tl;dr Backward compatibility.
If a plugin adds a property to `$compat_fields` array, then sites using that plugin would experience (a) an `Undefined property` `Warning` (PHP 8) | `Notice` (PHP 7) and (b) a possible change in behavior.
=== Why not limit the deprecation for PHP versions >= 8.2?
tl;dr original design intent and inform
The magic methods and `$compat_fields` property were added for one purpose: to continue providing external access to internal properties declared on `WP_User_Query`. They were not intended to be used for dynamic properties.
Deprecating that unintended usage both alerts developers a change is needed in their child class and informs them what to change.
References:
* Dynamic (non-explicitly declared) properties are deprecated as of PHP 8.2 and are expected to become a fatal error in PHP 9.0.
* A [https://www.youtube.com/live/vDZWepDQQVE?feature=share&t=10097 live open public working session] where these changes were discussed and agreed to.
* [https://wiki.php.net/rfc/deprecate_dynamic_properties PHP RFC: Deprecate dynamic properties.]
Related to #14579, #27881, #30891.
Follow-up to [15491], [28528], [31144].
Props antonvlasenko, rajinsharwar, jrf, markjaquith, hellofromTonya, SergeyBiryukov, desrosj, peterwilsoncc, audrasjb, costdev, oglekler, jeffpaul.
Fixes#58897.
See #56034.
git-svn-id: https://develop.svn.wordpress.org/trunk@56353 602fd350-edb4-49c9-b593-d223f7449a82
`str_contains()` was introduced in PHP 8.0 to perform a case-sensitive check indicating if the string to search in (haystack) contains the given substring (needle).
WordPress core includes a polyfill for `str_contains()` on PHP < 8.0 as of WordPress 5.9.
This commit replaces `false !== strpos( ... )` with `str_contains()` in core files, making the code more readable and consistent, as well as better aligned with modern development practices.
Follow-up to [52039], [52040], [52326], [55703], [55710], [55987].
Props Soean, spacedmonkey, costdev, dingo_d, azaozz, mikeschroder, flixos90, peterwilsoncc, SergeyBiryukov.
Fixes#58206.
git-svn-id: https://develop.svn.wordpress.org/trunk@55988 602fd350-edb4-49c9-b593-d223f7449a82
This corrects the placement of double quotes around the query and makes sure the alignment is consistent.
Props umeshmcakadi, mukesh27, krupalpanchal, dhrumilk, SergeyBiryukov.
Fixes#58372.
git-svn-id: https://develop.svn.wordpress.org/trunk@55857 602fd350-edb4-49c9-b593-d223f7449a82
The cache group `users-queries` was added in [55657]. This global cache group, was named to be inline with cache groups added in [55526]. However, the naming of the group does not match, as other cache groups, do not end with s at the end. This change fix this naming.
Props spacedmonkey, SergeyBiryukov, peterwilsoncc.
See #40613.
git-svn-id: https://develop.svn.wordpress.org/trunk@55680 602fd350-edb4-49c9-b593-d223f7449a82
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.
git-svn-id: https://develop.svn.wordpress.org/trunk@55657 602fd350-edb4-49c9-b593-d223f7449a82
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.
git-svn-id: https://develop.svn.wordpress.org/trunk@54766 602fd350-edb4-49c9-b593-d223f7449a82
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.
git-svn-id: https://develop.svn.wordpress.org/trunk@54133 602fd350-edb4-49c9-b593-d223f7449a82
* `$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.
git-svn-id: https://develop.svn.wordpress.org/trunk@54119 602fd350-edb4-49c9-b593-d223f7449a82
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.
git-svn-id: https://develop.svn.wordpress.org/trunk@53655 602fd350-edb4-49c9-b593-d223f7449a82
This ensures that the methods are recognized by the WordPress Code Reference parser.
Follow-up to [7994], [25567], [27156], [28887], [49672], [52226].
Props dd32, audrasjb.
Fixes#55928.
git-svn-id: https://develop.svn.wordpress.org/trunk@53469 602fd350-edb4-49c9-b593-d223f7449a82
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.
git-svn-id: https://develop.svn.wordpress.org/trunk@53362 602fd350-edb4-49c9-b593-d223f7449a82
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.
git-svn-id: https://develop.svn.wordpress.org/trunk@53327 602fd350-edb4-49c9-b593-d223f7449a82
Includes renaming the `$cols` parameter to `$columns` for consistency across the classes.
Follow-up to [42876], [53272-53276].
See #54729.
git-svn-id: https://develop.svn.wordpress.org/trunk@53280 602fd350-edb4-49c9-b593-d223f7449a82
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.
git-svn-id: https://develop.svn.wordpress.org/trunk@53276 602fd350-edb4-49c9-b593-d223f7449a82
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.
git-svn-id: https://develop.svn.wordpress.org/trunk@53255 602fd350-edb4-49c9-b593-d223f7449a82
This further improves the readability by replacing `implode()` calls with string interpolation.
Follow-up to [52973].
Props jrf.
See #54728.
git-svn-id: https://develop.svn.wordpress.org/trunk@52977 602fd350-edb4-49c9-b593-d223f7449a82
This aims to improve readability by fitting the values on a single screen to avoid horizontal scrolling.
See #54728.
git-svn-id: https://develop.svn.wordpress.org/trunk@52973 602fd350-edb4-49c9-b593-d223f7449a82
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.
git-svn-id: https://develop.svn.wordpress.org/trunk@51943 602fd350-edb4-49c9-b593-d223f7449a82
While many of these parameters also technically accept an array of numerical strings, they are all ultimately cast to an array of integers. Documenting them as such assists developers in understanding the expected types.
See #51800, #41756
git-svn-id: https://develop.svn.wordpress.org/trunk@49672 602fd350-edb4-49c9-b593-d223f7449a82
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.
git-svn-id: https://develop.svn.wordpress.org/trunk@49637 602fd350-edb4-49c9-b593-d223f7449a82
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.
git-svn-id: https://develop.svn.wordpress.org/trunk@49193 602fd350-edb4-49c9-b593-d223f7449a82
This reduces the number of `WordPress.PHP.StrictComparisons.LooseComparison` issues in half, from 1897 to 890.
Includes minor code layout fixes for better readability.
See #49542.
git-svn-id: https://develop.svn.wordpress.org/trunk@47808 602fd350-edb4-49c9-b593-d223f7449a82
This reduces the number of `WordPress.PHP.StrictInArray.MissingTrueStrict` issues from 486 to 50.
Includes minor code layout fixes for better readability.
See #49542.
git-svn-id: https://develop.svn.wordpress.org/trunk@47550 602fd350-edb4-49c9-b593-d223f7449a82
The callback in these functions is always checked against a limited list of valid callbacks that can be safely changed to dynamic function calls.
Props jrf.
See #47678.
git-svn-id: https://develop.svn.wordpress.org/trunk@46144 602fd350-edb4-49c9-b593-d223f7449a82
Revert unintended change to the `@since` tag for the `WP_User_Query` instance added to `found_users_query` filter in [43660].
See #44169, #43679.
git-svn-id: https://develop.svn.wordpress.org/trunk@44410 602fd350-edb4-49c9-b593-d223f7449a82
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.
git-svn-id: https://develop.svn.wordpress.org/trunk@44373 602fd350-edb4-49c9-b593-d223f7449a82
WordPress' code just... wasn't.
This is now dealt with.
Props jrf, pento, netweb, GaryJ, jdgrimes, westonruter, Greg Sherwood from PHPCS, and everyone who's ever contributed to WPCS and PHPCS.
Fixes#41057.
git-svn-id: https://develop.svn.wordpress.org/trunk@42343 602fd350-edb4-49c9-b593-d223f7449a82
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.
git-svn-id: https://develop.svn.wordpress.org/trunk@41162 602fd350-edb4-49c9-b593-d223f7449a82
