Changeset 63522

Timestamp:

09/07/2026 11:14:20 PM (6 weeks ago)

Author:

westonruter

Message:

Code Quality: Improve typing for wp_parse_args().

Both the parameters and the return value have been documented as a bare array since the function entered trunk in r5234. They now describe the string-keyed arrays it is used with, and the signature gains a native array return type. Every caller treats those keys as strings, but the function cannot guarantee it, since get_object_vars() reports a numeric-string property under an integer key and parse_str() reads 0=a as one, so the @phpstan-return records what can actually come back.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/13430.
Follow-up to r5234, r47429.

See #65817, #65860.

Location:

trunk

Files:

• src/wp-includes/functions.php (modified) (1 diff)
• tests/phpstan/baselines/argument.type.neon (modified) (2 diffs)

trunk/src/wp-includes/functions.php

@@ -5022 +5022 @@
  * to be merged into another array.
  *
+ * The keys of the returned array are documented as strings, since that is what
+ * callers mean by them, but they are not promised as such to static analysis.
+ * Integer keys remain reachable through arguments that are perfectly valid:
+ * `json_decode( '{"0":"a"}' )` is an object whose properties `get_object_vars()`
+ * reports under an integer key, and `parse_str()` reads `0=a` as one as well.
+ *
  * @since 2.2.0
  * @since 2.3.0 `$args` can now also be an object.
  *
- * @param string|array|object $args     Value to merge with $defaults.
- * @param array               $defaults Optional. Array that serves as the defaults.
- *                                      Default empty array.
- * @return array Merged user defined values with defaults.
- */
-function wp_parse_args( $args, $defaults = array() ) {
+ * @param string|array<string, mixed>|object $args     Value to merge with $defaults.
+ * @param array<string, mixed>               $defaults Optional. Array that serves as the defaults.
+ *                                                     Default empty array.
+ * @return array<string, mixed> Merged user defined values with defaults.
+ * @phpstan-return array<array-key, mixed>
+ */
+function wp_parse_args( $args, $defaults = array() ): array {
         if ( is_object( $args ) ) {
                 $parsed_args = get_object_vars( $args );

trunk/tests/phpstan/baselines/argument.type.neon

@@ -1130 +1130 @@
                         path: ../../../src/wp-includes/pluggable.php
                 -
-                        message: '#^Parameter \#1 \$args of function get_pages expects array\{child_of\?\: int, sort_order\?\: string, sort_column\?\: string, hierarchical\?\: bool, exclude\?\: array\<int\>, include\?\: array\<int\>, meta_key\?\: string, meta_value\?\: string, \.\.\., \.\.\.\}\|string, non\-empty\-array given\.$#'
+                        message: '#^Parameter \#1 \$args of function get_pages expects array\{child_of\?\: int, sort_order\?\: string, sort_column\?\: string, hierarchical\?\: bool, exclude\?\: array\<int\>, include\?\: array\<int\>, meta_key\?\: string, meta_value\?\: string, \.\.\., \.\.\.\}\|string, non\-empty\-array\<mixed\> given\.$#'
                         identifier: argument.type
                         count: 1
@@ -1250 +1250 @@
                         path: ../../../src/wp-includes/rest-api/endpoints/class-wp-rest-application-passwords-controller.php
                 -
+                        message: '#^Parameter \#1 \$args of function wp_parse_args expects array\<string, mixed\>\|object\|string, list\<array\> given\.$#'
+                        identifier: argument.type
+                        count: 1
+                        path: ../../../src/wp-includes/rest-api/endpoints/class-wp-rest-block-types-controller.php
+                -
                         message: '#^Parameter \#2 \$value of method WP_HTTP_Response\:\:header\(\) expects string, int given\.$#'
                         identifier: argument.type