Add cond. return type for paginate_links() (#226)

functionMap.php

@@ -38,6 +38,7 @@
     'addslashes_gpc' => ['T', '@phpstan-template' => 'T', 'gpc' => 'T'],
     'add_submenu_page' => [null, 'callback' => "''|callable"],
     'have_posts' => [null, '@phpstan-impure' => ''],
+    'paginate_links' => ["(\$args is array{total: int<min, 1>} ? void : (\$args is array{type: 'array'} ? list<string> : string))"],
     'rawurlencode_deep' => ['T', '@phpstan-template' => 'T', 'value' => 'T'],
     'sanitize_category' => ['T', '@phpstan-template' => 'T of array|object', 'category' => 'T'],
     'sanitize_post' => ['T', '@phpstan-template' => 'T of array|object', 'post' => 'T'],

tests/TypeInferenceTest.php

@@ -38,6 +38,7 @@ public function dataFileAsserts(): iterable
         yield from $this->gatherAssertTypes(__DIR__ . '/data/has_filter.php');
         yield from $this->gatherAssertTypes(__DIR__ . '/data/is_wp_error.php');
         yield from $this->gatherAssertTypes(__DIR__ . '/data/mysql2date.php');
+        yield from $this->gatherAssertTypes(__DIR__ . '/data/paginate_links.php');
         yield from $this->gatherAssertTypes(__DIR__ . '/data/rest_ensure_response.php');
         yield from $this->gatherAssertTypes(__DIR__ . '/data/size_format.php');
         yield from $this->gatherAssertTypes(__DIR__ . '/data/term_exists.php');

tests/data/paginate_links.php

@@ -0,0 +1,35 @@
+<?php
+
+/**
+ * Note:
+ * Starting from PHPStan 1.10.49, void types, including void in unions, are
+ * transformed into null.
+ *
+ * @link https://github.com/phpstan/phpstan-src/pull/2778
+ */
+
+declare(strict_types=1);
+
+namespace PhpStubs\WordPress\Core\Tests;
+
+use function paginate_links;
+use function PHPStan\Testing\assertType;
+
+/** @var negative-int $negInt */
+$negInt = $_GET['negInt'];
+
+// Returns void
+assertType('null', paginate_links(['total' => $negInt, 'key' => 'value']));
+assertType('null', paginate_links(['total' => 0, 'key' => 'value']));
+assertType('null', paginate_links(['total' => 1, 'key' => 'value']));
+
+// Returns list
+assertType('list<string>', paginate_links(['type' => 'array', 'key' => 'value']));
+
+// Returns string
+assertType('string', paginate_links(['type' => 'plain', 'key' => 'value']));
+assertType('string', paginate_links(['type' => 'list', 'key' => 'value']));
+assertType('string', paginate_links(['type' => 'thing', 'key' => 'value']));
+
+// Returns string by default
+assertType('string', paginate_links(['key' => 'value']));

wordpress-stubs.php

@@ -112774,6 +112774,7 @@ function language_attributes($doctype = 'html')
      *   before_page_number?: string,
      *   after_page_number?: string,
      * } $args
+     * @phpstan-return ($args is array{total: int<min, 1>} ? void : ($args is array{type: 'array'} ? list<string> : string))
      */
     function paginate_links($args = '')
     {