From 4f52f7e88148e6977b7fd0ae69883f002bf52657 Mon Sep 17 00:00:00 2001
From: Mat Lipe <mat@matlipe.com>
Date: Tue, 19 Sep 2023 16:33:14 +0000
Subject: [PATCH] Add dynamic return type for the get_term functionMap

- Return `array<int|string>` if `$output = 'ARRAY_N`.
- Return `array<string, int|string>` if default or `$output = 'ARRAY_A`.
- Return `WP_Term` if default or `$output` is 'OBJECT';

@link https://developer.wordpress.org/reference/functions/get_term/#parameters
---
 functionMap.php             |  1 +
 tests/TypeInferenceTest.php |  1 +
 tests/data/get_term.php     | 17 +++++++++++++++++
 wordpress-stubs.php         |  1 +
 4 files changed, 20 insertions(+)
 create mode 100644 tests/data/get_term.php

diff --git a/functionMap.php b/functionMap.php
index 1a890b6b..abbba4a6 100644
--- a/functionMap.php
+++ b/functionMap.php
@@ -90,6 +90,7 @@
     'get_comment' => ["(\$output is 'ARRAY_A' ? array<string, mixed>|null : (\$output is 'ARRAY_N' ? array<int, mixed>|null : \WP_Comment|null))"],
     'get_post' => ["(\$output is 'ARRAY_A' ? array<string, mixed>|null : (\$output is 'ARRAY_N' ? array<int, mixed>|null : \WP_Post|null))"],
     'get_page_by_path' => ["(\$output is 'ARRAY_A' ? array<string, mixed>|null : (\$output is 'ARRAY_N' ? array<int, mixed>|null : \WP_Post|null))"],
+    'get_term' => ["(\$output is 'ARRAY_A' ? array<string, string|int>|\WP_Error|null : (\$output is 'ARRAY_N' ? list<string|int>|\WP_Error|null : \WP_Term|\WP_Error|null))"],
     'has_action' => ['($callback is false ? bool : false|int)'],
     'has_filter' => ['($callback is false ? bool : false|int)'],
     'get_permalink' => ['($post is \WP_Post ? string : string|false)'],
diff --git a/tests/TypeInferenceTest.php b/tests/TypeInferenceTest.php
index 92b9dc79..d327173f 100644
--- a/tests/TypeInferenceTest.php
+++ b/tests/TypeInferenceTest.php
@@ -20,6 +20,7 @@ public function dataFileAsserts(): iterable
         yield from $this->gatherAssertTypes(__DIR__ . '/data/get_page_by_path.php');
         yield from $this->gatherAssertTypes(__DIR__ . '/data/get_permalink.php');
         yield from $this->gatherAssertTypes(__DIR__ . '/data/get_taxonomies.php');
+        yield from $this->gatherAssertTypes(__DIR__ . '/data/get_term.php');
         yield from $this->gatherAssertTypes(__DIR__ . '/data/get_taxonomies_for_attachments.php');
         yield from $this->gatherAssertTypes(__DIR__ . '/data/has_filter.php');
         yield from $this->gatherAssertTypes(__DIR__ . '/data/is_wp_error.php');
diff --git a/tests/data/get_term.php b/tests/data/get_term.php
new file mode 100644
index 00000000..fcb209b5
--- /dev/null
+++ b/tests/data/get_term.php
@@ -0,0 +1,17 @@
+<?php
+
+declare( strict_types=1 );
+
+namespace PhpStubs\WordPress\Core\Tests;
+
+use function get_term;
+use function PHPStan\Testing\assertType;
+
+assertType( 'WP_Error|WP_Term|null', get_term( 2, '', OBJECT ) );
+assertType( 'WP_Error|WP_Term|null', get_term( 2, 'category', OBJECT ) );
+assertType( 'WP_Error|WP_Term|null', get_term( 2 ) );
+
+assertType( 'array<string, int|string>|WP_Error|null', get_term( 2, '', ARRAY_A ) );
+assertType( 'array<string, int|string>|WP_Error|null', get_term( 2, 'category', ARRAY_A ) );
+assertType( 'array<int, int|string>|WP_Error|null', get_term( 2, '', ARRAY_N ) );
+assertType( 'array<int, int|string>|WP_Error|null', get_term( 2, 'category', ARRAY_N ) );
\ No newline at end of file
diff --git a/wordpress-stubs.php b/wordpress-stubs.php
index f01cb465..5be39d77 100644
--- a/wordpress-stubs.php
+++ b/wordpress-stubs.php
@@ -129467,6 +129467,7 @@ function get_tax_sql($tax_query, $primary_table, $primary_id_column)
      * @param string             $filter   Optional. How to sanitize term fields. Default 'raw'.
      * @return WP_Term|array|WP_Error|null WP_Term instance (or array) on success, depending on the `$output` value.
      *                                     WP_Error if `$taxonomy` does not exist. Null for miscellaneous failure.
+     * @phpstan-return ($output is 'ARRAY_A' ? array<string, string|int>|\WP_Error|null : ($output is 'ARRAY_N' ? list<string|int>|\WP_Error|null : \WP_Term|\WP_Error|null))
      */
     function get_term($term, $taxonomy = '', $output = \OBJECT, $filter = 'raw')
     {