Changeset 62672 for trunk/src/wp-includes/formatting.php

Timestamp:

07/09/2026 05:56:05 AM (7 weeks ago)

Author:

westonruter

Message:

Code Quality: Add PHPStan conditional return types to the slashing functions.

Adds @phpstan- prefixed generics and conditional return types to map_deep(), stripslashes_from_strings_only(), stripslashes_deep(), wp_slash(), wp_unslash(), and add_magic_quotes(). Static analysis now knows that a string passed to the slashing functions yields a string, and an array yields an array; this is something the plain @return tags could not express, and which caused wp_unslash() to widen its callers' types to array|string even after an is_array() guard.

The returns are conditional rather than a bare T for two reasons: map_deep()'s callback may change the type of every leaf, and the slashing functions rewrite string contents, so a literal-string type cannot survive.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/12455.

See #64898.

File:

• trunk/src/wp-includes/formatting.php (modified) (5 diffs)

trunk/src/wp-includes/formatting.php

@@ -2849 +2849 @@
  * @param mixed $value The value to be stripped.
  * @return mixed Stripped value.
+ *
+ * @phpstan-template T
+ * @phpstan-param T $value
+ * @phpstan-return (
+ *     T is string ? string : (
+ *         T is array ? array<key-of<T>, ( value-of<T> is string ? string : value-of<T> )> : T
+ *     )
+ * )
  */
 function stripslashes_deep( $value ) {
@@ -2861 +2869 @@
  * @param mixed $value The array or string to be stripped.
  * @return mixed The stripped value.
+ *
+ * @phpstan-template T
+ * @phpstan-param T $value
+ * @phpstan-return (T is string ? string : T)
  */
 function stripslashes_from_strings_only( $value ) {
@@ -5171 +5183 @@
  * @param callable $callback The function to map onto $value.
  * @return mixed The value with the callback applied to all non-arrays and non-objects inside it.
+ *
+ * @phpstan-template T
+ * @phpstan-param T $value
+ * @phpstan-return (T is array ? array<key-of<T>, mixed> : (T is object ? T : mixed))
  */
 function map_deep( $value, $callback ) {
@@ -5812 +5828 @@
  * @param string|array $value String or array of data to slash.
  * @return string|array Slashed `$value`, in the same type as supplied.
+ *
+ * @phpstan-template T
+ * @phpstan-param T $value
+ * @phpstan-return (
+ *     T is string ? string : (
+ *         T is array ? array<key-of<T>, ( value-of<T> is string ? string : value-of<T> )> : T
+ *     )
+ * )
  */
 function wp_slash( $value ) {
@@ -5835 +5859 @@
  * @param string|array $value String or array of data to unslash.
  * @return string|array Unslashed `$value`, in the same type as supplied.
+ *
+ * @phpstan-template T
+ * @phpstan-param T $value
+ * @phpstan-return (
+ *     T is string ? string : (
+ *         T is array ? array<key-of<T>, ( value-of<T> is string ? string : value-of<T> )> : T
+ *     )
+ * )
  */
 function wp_unslash( $value ) {