Add cond. return types for WP_Translations

functionMap.php

@@ -180,4 +180,6 @@
     'wp_parse_list' => ['($input_list is array ? array<scalar> : list<string>)'],
     'wp_parse_str' => [null, '@phpstan-param-out' => 'array<int|string, array|string> $result'],
     'size_format' => ["(\$bytes is not numeric ? false : (\$bytes is negative-int|'0' ? false : string))"],
+    'WP_Translations::translate' => ['($singular is null ? null : string)'],
+    'WP_Translations::translate_plural' => ['($singular is null ? null : ($plural is null ? T : string))', '@phpstan-template T' => 'of string|null', 'singular' => 'T', 'count' => 'int'],
 ];

phpcs.xml.dist

@@ -13,6 +13,9 @@
     </rule>
 
     <!-- Rules not applied to tests -->
+    <rule ref="NeutronStandard.Functions.LongFunction.LongFunction">
+        <exclude-pattern>tests/TypeInferenceTest.php</exclude-pattern>
+    </rule>
     <rule ref="PSR12NeutronRuleset.NamingConventions.MeaningfulVariableName">
         <exclude-pattern>tests/</exclude-pattern>
     </rule>

tests/TypeInferenceTest.php

@@ -48,6 +48,7 @@ public function dataFileAsserts(): iterable
         yield from $this->gatherAssertTypes(__DIR__ . '/data/wp_rest_request.php');
         yield from $this->gatherAssertTypes(__DIR__ . '/data/wp_tag_cloud.php');
         yield from $this->gatherAssertTypes(__DIR__ . '/data/wp_theme.php');
+        yield from $this->gatherAssertTypes(__DIR__ . '/data/wp_translations.php');
         yield from $this->gatherAssertTypes(__DIR__ . '/data/wpdb.php');
     }
 

tests/data/wp_translations.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpStubs\WordPress\Core\Tests;
+
+use function PHPStan\Testing\assertType;
+
+/** @var \WP_Translations */
+$translations = $_GET['translations'];
+
+$string = (string)$_GET['string'];
+$singular = $_GET['singular'] ? $string : null;
+
+// WP_Translation::translate()
+assertType('null', $translations->translate(null));
+assertType('string', $translations->translate($string));
+
+// WP_Translation::translate_plural()
+assertType('null', $translations->translate_plural(null, null));
+assertType('string', $translations->translate_plural($string, null));
+assertType('null', $translations->translate_plural(null, $string));
+assertType('string', $translations->translate_plural($string, $string));
+assertType('string|null', $translations->translate_plural($singular, $string));

wordpress-stubs.php

@@ -68875,6 +68875,10 @@ public function __get(string $name)
          * @param int|float   $count    Count. Should be an integer, but some plugins pass floats.
          * @param string|null $context  Context.
          * @return string|null Translation if it exists, or the unchanged singular string.
+         * @phpstan-template T of string|null
+         * @phpstan-param T $singular
+         * @phpstan-param int $count
+         * @phpstan-return ($singular is null ? null : ($plural is null ? T : string))
          */
         public function translate_plural($singular, $plural, $count = 1, $context = '')
         {
@@ -68887,6 +68891,7 @@ public function translate_plural($singular, $plural, $count = 1, $context = '')
          * @param string|null $singular Singular string.
          * @param string|null $context  Context.
          * @return string|null Translation if it exists, or the unchanged singular string
+         * @phpstan-return ($singular is null ? null : string)
          */
         public function translate($singular, $context = '')
         {