Commit e4a444b6c9 for wordpress.org
commit e4a444b6c943921187c78d8c9ea4498e92b2c19b
Author: westonruter <westonruter@git.wordpress.org>
Date: Thu Oct 29 17:59:03 2026 +0000
Docs: Clarify `$operator` values for object list filters.
The `$operator` default for `wp_filter_object_list()` was documented as `'AND'` even though the signature declares `'and'`, and the functions that pass `$operator` through to `WP_List_Util::filter()` disagreed with each other on the casing and on whether `'not'` is accepted. Since the value is uppercased before it is validated, each of these functions now documents that it is case-insensitive and that `'and'`, `'or'`, and `'not'` are all accepted, and declares a PHPStan type for the parameter so that unsupported values can be flagged. The type lists only the lowercase and uppercase forms, as enumerating every mixed-case variant is impractical.
For consistency, the documentation now uses lowercase throughout, and the `'AND'` default of `wp_list_filter()` and `WP_List_Util::filter()` is changed to `'and'` to match the other functions. Because of the uppercasing, this does not change behavior.
Developed in https://github.com/WordPress/wordpress-develop/pull/13245.
Follow-up to r17251, r36090, r36091, r38928.
Props khokansardar, westonruter, marian1.
See #65817, #65860.
Fixes #65933.
Built from https://develop.svn.wordpress.org/trunk@65021
git-svn-id: http://core.svn.wordpress.org/trunk@64171 1a063a9b-81f0-0310-95a4-ce76da25c4cd
diff --git a/wp-includes/class-wp-list-util.php b/wp-includes/class-wp-list-util.php
index 6560355291..da12a2d1a5 100644
--- a/wp-includes/class-wp-list-util.php
+++ b/wp-includes/class-wp-list-util.php
@@ -82,20 +82,22 @@ class WP_List_Util {
* Key represents property name, and value represents property value.
*
* If an object has more properties than those specified in arguments,
- * that will not disqualify it. When using the 'AND' operator,
+ * that will not disqualify it. When using the 'and' operator,
* any missing properties will disqualify it.
*
* @since 4.7.0
*
* @param array $args Optional. An array of key => value arguments to match
* against each object. Default empty array.
- * @param string $operator Optional. The logical operation to perform. 'AND' means
- * all elements from the array must match. 'OR' means only
- * one element needs to match. 'NOT' means no elements may
- * match. Default 'AND'.
+ * @param string $operator Optional. The logical operation to perform. 'and' means
+ * all elements from the array must match. 'or' means only
+ * one element needs to match. 'not' means no elements may
+ * match. The value is case-insensitive. Default 'and'.
* @return array Array of found values.
+ *
+ * @phpstan-param 'and'|'AND'|'or'|'OR'|'not'|'NOT' $operator
*/
- public function filter( $args = array(), $operator = 'AND' ) {
+ public function filter( $args = array(), $operator = 'and' ) {
if ( empty( $args ) ) {
return $this->output;
}
diff --git a/wp-includes/functions.php b/wp-includes/functions.php
index 03e9bdc8eb..5307e33eed 100644
--- a/wp-includes/functions.php
+++ b/wp-includes/functions.php
@@ -5461,7 +5461,7 @@ function wp_is_numeric_array( $data ): bool {
* Key represents property name, and value represents property value.
*
* If an object has more properties than those specified in arguments,
- * that will not disqualify it. When using the 'AND' operator,
+ * that will not disqualify it. When using the 'and' operator,
* any missing properties will disqualify it.
*
* When using the `$field` argument, this function can also retrieve
@@ -5474,13 +5474,15 @@ function wp_is_numeric_array( $data ): bool {
* @param array $input_list An array of objects to filter.
* @param array $args Optional. An array of key => value arguments to match
* against each object. Default empty array.
- * @param string $operator Optional. The logical operation to perform. 'AND' means
- * all elements from the array must match. 'OR' means only
- * one element needs to match. 'NOT' means no elements may
- * match. Default 'AND'.
+ * @param string $operator Optional. The logical operation to perform. 'and' means
+ * all elements from the array must match. 'or' means only
+ * one element needs to match. 'not' means no elements may
+ * match. The value is case-insensitive. Default 'and'.
* @param bool|string $field Optional. A field from the object to place instead
* of the entire object. Default false.
* @return array A list of objects or object fields.
+ *
+ * @phpstan-param 'and'|'AND'|'or'|'OR'|'not'|'NOT' $operator
*/
function wp_filter_object_list( $input_list, $args = array(), $operator = 'and', $field = false ) {
if ( ! is_array( $input_list ) ) {
@@ -5505,7 +5507,7 @@ function wp_filter_object_list( $input_list, $args = array(), $operator = 'and',
* Key represents property name, and value represents property value.
*
* If an object has more properties than those specified in arguments,
- * that will not disqualify it. When using the 'AND' operator,
+ * that will not disqualify it. When using the 'and' operator,
* any missing properties will disqualify it.
*
* If you want to retrieve a particular field from all matching objects,
@@ -5518,13 +5520,15 @@ function wp_filter_object_list( $input_list, $args = array(), $operator = 'and',
* @param array $input_list An array of objects to filter.
* @param array $args Optional. An array of key => value arguments to match
* against each object. Default empty array.
- * @param string $operator Optional. The logical operation to perform. 'AND' means
- * all elements from the array must match. 'OR' means only
- * one element needs to match. 'NOT' means no elements may
- * match. Default 'AND'.
+ * @param string $operator Optional. The logical operation to perform. 'and' means
+ * all elements from the array must match. 'or' means only
+ * one element needs to match. 'not' means no elements may
+ * match. The value is case-insensitive. Default 'and'.
* @return array Array of found values.
+ *
+ * @phpstan-param 'and'|'AND'|'or'|'OR'|'not'|'NOT' $operator
*/
-function wp_list_filter( $input_list, $args = array(), $operator = 'AND' ) {
+function wp_list_filter( $input_list, $args = array(), $operator = 'and' ) {
return wp_filter_object_list( $input_list, $args, $operator );
}
diff --git a/wp-includes/post.php b/wp-includes/post.php
index 78fa26a1b0..4cb9e69f5f 100644
--- a/wp-includes/post.php
+++ b/wp-includes/post.php
@@ -1556,9 +1556,12 @@ function get_post_status_object( $post_status ) {
* properties of the global `$wp_post_statuses objects`. Default empty array.
* @param string $output Optional. The type of output to return, either 'names' or 'objects'. Default 'names'.
* @param string $operator Optional. The logical operation to perform. 'or' means only one element
- * from the array needs to match; 'and' means all elements must match.
+ * from the array needs to match; 'and' means all elements must match;
+ * 'not' means no elements may match. The value is case-insensitive.
* Default 'and'.
* @return string[]|stdClass[] A list of post status names or objects.
+ *
+ * @phpstan-param 'and'|'AND'|'or'|'OR'|'not'|'NOT' $operator
* @phpstan-return ( $output is 'names' ? array<non-falsy-string, non-falsy-string> : array<non-falsy-string, stdClass> )
*/
function get_post_stati( $args = array(), $output = 'names', $operator = 'and' ) {
@@ -1663,8 +1666,11 @@ function get_post_type_object( $post_type ) {
* or 'objects'. Default 'names'.
* @param string $operator Optional. The logical operation to perform. 'or' means only one
* element from the array needs to match; 'and' means all elements
- * must match; 'not' means no elements may match. Default 'and'.
+ * must match; 'not' means no elements may match. The value is
+ * case-insensitive. Default 'and'.
* @return string[]|WP_Post_Type[] An array of post type names or objects.
+ *
+ * @phpstan-param 'and'|'AND'|'or'|'OR'|'not'|'NOT' $operator
* @phpstan-return ( $output is 'names' ? string[] : WP_Post_Type[] )
*/
function get_post_types( $args = array(), $output = 'names', $operator = 'and' ) {
@@ -2435,8 +2441,10 @@ function post_type_supports( $post_type, $feature ) {
* @param string $operator Optional. The logical operation to perform. 'or' means
* only one element from the array needs to match; 'and'
* means all elements must match; 'not' means no elements may
- * match. Default 'and'.
+ * match. The value is case-insensitive. Default 'and'.
* @return string[] A list of post type names.
+ *
+ * @phpstan-param 'and'|'AND'|'or'|'OR'|'not'|'NOT' $operator
*/
function get_post_types_by_support( $feature, $operator = 'and' ) {
global $_wp_post_type_features;
diff --git a/wp-includes/taxonomy.php b/wp-includes/taxonomy.php
index e0f3c4ed8f..6656a2f8e3 100644
--- a/wp-includes/taxonomy.php
+++ b/wp-includes/taxonomy.php
@@ -274,10 +274,13 @@ function create_initial_taxonomies() {
* Default empty array.
* @param string $output Optional. The type of output to return in the array. Either 'names'
* or 'objects'. Default 'names'.
- * @param string $operator Optional. The logical operation to perform. Accepts 'and' or 'or'. 'or' means only
- * one element from the array needs to match; 'and' means all elements must match.
+ * @param string $operator Optional. The logical operation to perform. Accepts 'and', 'or', or 'not'. 'or'
+ * means only one element from the array needs to match; 'and' means all elements
+ * must match; 'not' means no elements may match. The value is case-insensitive.
* Default 'and'.
* @return string[]|WP_Taxonomy[] An array of taxonomy names or objects.
+ *
+ * @phpstan-param 'and'|'AND'|'or'|'OR'|'not'|'NOT' $operator
* @phpstan-return ( $output is 'names' ? array<non-falsy-string, non-falsy-string> : array<non-falsy-string, WP_Taxonomy> )
*/
function get_taxonomies( $args = array(), $output = 'names', $operator = 'and' ) {
diff --git a/wp-includes/version.php b/wp-includes/version.php
index ffa9434e89..b85e02cf49 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
*
* @global string $wp_version
*/
-$wp_version = '7.2-beta3-65020';
+$wp_version = '7.2-beta3-65021';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.