Commit 7ef7c9f3a3 for wordpress.org

commit 7ef7c9f3a3b1ac481666fee765f855fcab62e150
Author: westonruter <westonruter@git.wordpress.org>
Date:   Tue Sep 8 18:36:50 2026 +0000

    Code Quality: Narrow the `esc_sql()` parameter and return types.

    Narrow the documented types of `esc_sql()` and `wpdb::_escape()` from `string|array` to `string|string[]`, since neither function is meant to operate on anything other than strings and flat arrays of strings.

    Add `@phpstan-` prefixed annotations with a key template and a conditional return type, so static analysis knows that a `string` yields a `string` and that an array yields an array of strings with its keys preserved.

    Developed in https://github.com/WordPress/wordpress-develop/pull/12975.
    Follow-up to r24986, r62672.

    Props johnbillion, westonruter, irozum.
    See #65817.

    Built from https://develop.svn.wordpress.org/trunk@63540


    git-svn-id: http://core.svn.wordpress.org/trunk@62716 1a063a9b-81f0-0310-95a4-ce76da25c4cd

diff --git a/wp-includes/class-wpdb.php b/wp-includes/class-wpdb.php
index 5cf9508f8f..869111efd0 100644
--- a/wp-includes/class-wpdb.php
+++ b/wp-includes/class-wpdb.php
@@ -1291,12 +1291,23 @@ class wpdb {
 	/**
 	 * Escapes data. Works on arrays.
 	 *
+	 * The `$data is string` case must come first in the conditional return type below. PHPStan
+	 * does not treat the documented types as certain, so it still analyzes the nested
+	 * `is_array()` check even though `$v` is a `string`, narrowing `$v` to `never` there. A
+	 * `never` argument satisfies whichever case is tested first, so testing for `string` first
+	 * makes the recursive call resolve to `string`. Testing for the array case first would
+	 * instead resolve it to an array, widening `$data` and contradicting the return type.
+	 *
 	 * @since 2.8.0
 	 *
 	 * @uses wpdb::_real_escape()
 	 *
-	 * @param string|array $data Data to escape.
-	 * @return string|array Escaped data, in the same type as supplied.
+	 * @param string|string[] $data Data to escape.
+	 * @return string|string[] Escaped data, in the same type as supplied.
+	 *
+	 * @phpstan-template TKey of array-key
+	 * @phpstan-param string|array<TKey, string> $data
+	 * @phpstan-return ( $data is string ? string : array<TKey, string> )
 	 */
 	public function _escape( $data ) {
 		if ( is_array( $data ) ) {
diff --git a/wp-includes/formatting.php b/wp-includes/formatting.php
index b9d551d59d..abbf18c3b7 100644
--- a/wp-includes/formatting.php
+++ b/wp-includes/formatting.php
@@ -4521,8 +4521,12 @@ function _deep_replace( $search, $subject ) {
  *
  * @global wpdb $wpdb WordPress database abstraction object.
  *
- * @param string|array $data Unescaped data.
- * @return string|array Escaped data, in the same type as supplied.
+ * @param string|string[] $data Unescaped data.
+ * @return string|string[] Escaped data, in the same type as supplied.
+ *
+ * @phpstan-template TKey of array-key
+ * @phpstan-param string|array<TKey, string> $data
+ * @phpstan-return ( $data is string ? string : array<TKey, string> )
  */
 function esc_sql( $data ) {
 	global $wpdb;
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 7702764165..a7e360b33c 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '7.2-alpha-63539';
+$wp_version = '7.2-alpha-63540';

 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.