From 794ff8aa26303d3811f24e1da3e4a155eb03b48b Mon Sep 17 00:00:00 2001
From: IanDelMar <42134098+IanDelMar@users.noreply.github.com>
Date: Sat, 24 Aug 2024 08:30:00 +0200
Subject: [PATCH] Add cond. return type for wp_list_categories() (#201)

---
 functionMap.php                   |  1 +
 tests/TypeInferenceTest.php       |  1 +
 tests/data/wp_list_categories.php | 31 +++++++++++++++++++++++++++++++
 wordpress-stubs.php               |  1 +
 4 files changed, 34 insertions(+)
 create mode 100644 tests/data/wp_list_categories.php

diff --git a/functionMap.php b/functionMap.php
index 947e96d..12dd5b4 100644
--- a/functionMap.php
+++ b/functionMap.php
@@ -52,6 +52,7 @@
     'WP_Http::post' => [$httpReturnType],
     'WP_Http::request' => [$httpReturnType],
     'wp_list_bookmarks' => ['($args is array{echo: false|0} ? string : void)'],
+    'wp_list_categories' => ['($args is array{echo: false|0} ? string|false : false|void)'],
     'WP_List_Table::set_pagination_args' => ['void', 'args' => 'array{total_items?: int, total_pages?: int, per_page?: int}'],
     'wp_next_scheduled' => [null, 'args' => $cronArgsType],
     'WP_Query::have_posts' => [null, '@phpstan-impure' => ''],
diff --git a/tests/TypeInferenceTest.php b/tests/TypeInferenceTest.php
index f4fb39c..1f192ca 100644
--- a/tests/TypeInferenceTest.php
+++ b/tests/TypeInferenceTest.php
@@ -36,6 +36,7 @@ public function dataFileAsserts(): iterable
         yield from $this->gatherAssertTypes(__DIR__ . '/data/wp_error_parameter.php');
         yield from $this->gatherAssertTypes(__DIR__ . '/data/wp_get_archives.php');
         yield from $this->gatherAssertTypes(__DIR__ . '/data/wp_list_bookmarks.php');
+        yield from $this->gatherAssertTypes(__DIR__ . '/data/wp_list_categories.php');
         yield from $this->gatherAssertTypes(__DIR__ . '/data/wp_rest_request.php');
         yield from $this->gatherAssertTypes(__DIR__ . '/data/wp_theme.php');
         yield from $this->gatherAssertTypes(__DIR__ . '/data/wpdb.php');
diff --git a/tests/data/wp_list_categories.php b/tests/data/wp_list_categories.php
new file mode 100644
index 0000000..1e88675
--- /dev/null
+++ b/tests/data/wp_list_categories.php
@@ -0,0 +1,31 @@
+<?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 wp_list_categories;
+use function PHPStan\Testing\assertType;
+
+// Default value of 1
+assertType('false|null', wp_list_categories());
+
+// Explicit value of true|1
+assertType('false|null', wp_list_categories(['echo' => true, 'key' => 'value']));
+assertType('false|null', wp_list_categories(['echo' => 1, 'key' => 'value']));
+
+// Explicit value of false|0
+assertType('string|false', wp_list_categories(['echo' => false, 'key' => 'value']));
+assertType('string|false', wp_list_categories(['echo' => 0, 'key' => 'value']));
+
+// Unknown value
+assertType('string|false|null', wp_list_categories(['echo' => (bool)$GET['echo'], 'key' => 'value']));
+assertType('string|false|null', wp_list_categories(['echo' => (int)$GET['echo'], 'key' => 'value']));
diff --git a/wordpress-stubs.php b/wordpress-stubs.php
index 7fcb85d..1ec5de4 100644
--- a/wordpress-stubs.php
+++ b/wordpress-stubs.php
@@ -102127,6 +102127,7 @@ function wp_dropdown_categories($args = '')
      *   walker?: Walker,
      *   taxonomy?: string,
      * } $args
+     * @phpstan-return ($args is array{echo: false|0} ? string|false : false|void)
      */
     function wp_list_categories($args = '')
     {