Add conditional return type for sanitize_term_field

functionMap.php

@@ -136,6 +136,7 @@
     'sanitize_post' => ['(T is \WP_Post ? \WP_Post : (T is object ? object : (T is array ? array : T)))', '@phpstan-template T' => 'of mixed', 'post' => 'T'],
     'sanitize_sql_orderby' => ['(T is non-falsy-string ? T|false : false)', '@phpstan-template T' => 'of string', 'orderby' => 'T'],
     'sanitize_term' => ['T', '@phpstan-template' => 'T of array|object', 'term' => 'T'],
+    'sanitize_term_field' => ["(\$field is 'parent'|'term_id'|'count'|'term_group'|'term_taxonomy_id'|'object_id' ? int<0, max> : (\$context is 'raw' ? T : (\$context is 'attribute'|'edit'|'js' ? string : mixed)))", '@phpstan-template T' => 'of string', 'value' => 'T'],
     'sanitize_title_with_dashes' => ['lowercase-string', 'context' => "'display'|'save'"],
     'single_cat_title' => ['($display is true ? void : string|void)'],
     'single_month_title' => ['($display is true ? false|void : false|string)'],

tests/data/return/sanitize-term-field.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpStubs\WordPress\Core\Tests;
+
+use function sanitize_term_field;
+use function PHPStan\Testing\assertType;
+
+$termId = Faker::int();
+$taxonomy = Faker::string();
+
+// Int fields
+assertType('int<0, max>', sanitize_term_field('parent', Faker::string(), $termId, $taxonomy, 'raw'));
+assertType('int<0, max>', sanitize_term_field('term_id', Faker::string(), $termId, $taxonomy, 'raw'));
+assertType('int<0, max>', sanitize_term_field('count', Faker::string(), $termId, $taxonomy, 'raw'));
+assertType('int<0, max>', sanitize_term_field('term_group', Faker::string(), $termId, $taxonomy, 'raw'));
+assertType('int<0, max>', sanitize_term_field('term_taxonomy_id', Faker::string(), $termId, $taxonomy, 'raw'));
+assertType('int<0, max>', sanitize_term_field('object_id', Faker::string(), $termId, $taxonomy, 'raw'));
+// Also int range if constant numeric string
+assertType('int<0, max>', sanitize_term_field('parent', '123', $termId, $taxonomy, 'raw'));
+// Also int range in any other context
+assertType('int<0, max>', sanitize_term_field('parent', Faker::string(), $termId, $taxonomy, Faker::string()));
+
+// Non int fields in raw context
+assertType("'field value'", sanitize_term_field('field', 'field value', $termId, $taxonomy, 'raw'));
+assertType('string', sanitize_term_field('field', Faker::string(), $termId, $taxonomy, 'raw'));
+
+// Non int field values in edit context may be filtered to mixed, but are escaped using esc_html or esc_attr => string
+assertType('string', sanitize_term_field('field', 'field value', $termId, $taxonomy, 'edit'));
+assertType('string', sanitize_term_field('field', Faker::string(), $termId, $taxonomy, 'edit'));
+
+// Non int field values in attribute/js context are not filtered, but are escaped using esc_attr/esc_js
+// => string, but not as given in the argument
+assertType('string', sanitize_term_field('field', 'field value', $termId, $taxonomy, 'attribute'));
+assertType('string', sanitize_term_field('field', Faker::string(), $termId, $taxonomy, 'attribute'));
+assertType('string', sanitize_term_field('field', 'field value', $termId, $taxonomy, 'js'));
+assertType('string', sanitize_term_field('field', Faker::string(), $termId, $taxonomy, 'js'));
+
+// Non int fields in any other context may be filtered to mixed => mixed
+assertType('mixed', sanitize_term_field('field', 'field value', $termId, $taxonomy, 'db'));
+assertType('mixed', sanitize_term_field('field', 'field value', $termId, $taxonomy, 'display'));
+assertType('mixed', sanitize_term_field('field', 'field value', $termId, $taxonomy, 'rss'));
+assertType('mixed', sanitize_term_field('field', Faker::string(), $termId, $taxonomy, 'db'));
+assertType('mixed', sanitize_term_field('field', Faker::string(), $termId, $taxonomy, 'display'));
+assertType('mixed', sanitize_term_field('field', Faker::string(), $termId, $taxonomy, 'rss'));
+
+// Non constant field in raw context => int<0, max> (from int field) or T (from other field)
+assertType("'field value'|int<0, max>", sanitize_term_field(Faker::string(), 'field value', $termId, $taxonomy, 'raw'));
+assertType('int<0, max>|string', sanitize_term_field(Faker::string(), Faker::string(), $termId, $taxonomy, 'raw'));
+
+// Non constant field in attribute|edit|js context => int<0, max> (from int field) or string (from other field)
+assertType('int<0, max>|string', sanitize_term_field(Faker::string(), Faker::string(), $termId, $taxonomy, 'attribute'));
+assertType('int<0, max>|string', sanitize_term_field(Faker::string(), Faker::string(), $termId, $taxonomy, 'edit'));
+assertType('int<0, max>|string', sanitize_term_field(Faker::string(), Faker::string(), $termId, $taxonomy, 'js'));
+
+// Non constant field in any other context than attribute|edit|js|raw => mixed
+assertType('mixed', sanitize_term_field(Faker::string(), Faker::string(), $termId, $taxonomy, 'db'));
+assertType('mixed', sanitize_term_field(Faker::string(), Faker::string(), $termId, $taxonomy, 'display'));
+assertType('mixed', sanitize_term_field(Faker::string(), Faker::string(), $termId, $taxonomy, 'rss'));

wordpress-stubs.php

@@ -139087,6 +139087,9 @@ function sanitize_term($term, $taxonomy, $context = 'display')
      *                         'attribute', or 'js'. Default 'display'.
      * @return mixed Sanitized field.
      * @phpstan-param 'raw'|'edit'|'db'|'display'|'rss'|'attribute'|'js' $context
+     * @phpstan-template T of string
+     * @phpstan-param T $value
+     * @phpstan-return ($field is 'parent'|'term_id'|'count'|'term_group'|'term_taxonomy_id'|'object_id' ? int<0, max> : ($context is 'raw' ? T : ($context is 'attribute'|'edit'|'js' ? string : mixed)))
      */
     function sanitize_term_field($field, $value, $term_id, $taxonomy, $context)
     {