Add dynamic return type for the get_term_by function (#105)

- 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 = 'OBJECT'`.

https://developer.wordpress.org/reference/functions/get_term_by/#parameters

Author: lipemat

functionMap.php

@@ -89,6 +89,7 @@
     'get_post_stati' => ["(\$output is 'names' ? array<string, string> : array<string, \stdClass>)"],
     '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_term_by' => ["(\$output is 'ARRAY_A' ? array<string, string|int>|\WP_Error|false : (\$output is 'ARRAY_N' ? list<string|int>|\WP_Error|false : \WP_Term|\WP_Error|false))"],
     '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)'],

tests/TypeInferenceTest.php

@@ -19,6 +19,7 @@ public function dataFileAsserts(): iterable
         yield from $this->gatherAssertTypes(__DIR__ . '/data/get_post_types.php');
         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_term_by.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');

tests/data/get_term_by.php

@@ -0,0 +1,13 @@
+<?php
+
+declare( strict_types=1 );
+
+namespace PhpStubs\WordPress\Core\Tests;
+
+use function get_term_by;
+use function PHPStan\Testing\assertType;
+
+assertType( 'WP_Error|WP_Term|false', get_term_by( 'term_id', 2, '', OBJECT ) );
+assertType( 'WP_Error|WP_Term|false', get_term_by( 'slug', 'test' ) );
+assertType( 'array<string, int|string>|WP_Error|false', get_term_by( 'term_id', 2, '', ARRAY_A ) );
+assertType( 'array<int, int|string>|WP_Error|false', get_term_by( 'term_id', 2, '', ARRAY_N ) );

wordpress-stubs.php

@@ -129509,6 +129509,7 @@ function get_term($term, $taxonomy = '', $output = \OBJECT, $filter = 'raw')
      * @param string     $filter   Optional. How to sanitize term fields. Default 'raw'.
      * @return WP_Term|array|false WP_Term instance (or array) on success, depending on the `$output` value.
      *                             False if `$taxonomy` does not exist or `$term` was not found.
+     * @phpstan-return ($output is 'ARRAY_A' ? array<string, string|int>|\WP_Error|false : ($output is 'ARRAY_N' ? list<string|int>|\WP_Error|false : \WP_Term|\WP_Error|false))
      */
     function get_term_by($field, $value, $taxonomy = '', $output = \OBJECT, $filter = 'raw')
     {