Add dynamic return type extension for wp_tag_cloud()

extension.neon

@@ -15,6 +15,10 @@ services:
         class: SzepeViktor\PHPStan\WordPress\EchoKeyDynamicFunctionReturnTypeExtension
         tags:
             - phpstan.broker.dynamicFunctionReturnTypeExtension
+    -
+        class: SzepeViktor\PHPStan\WordPress\WpTagCloudDynamicFunctionReturnTypeExtension
+        tags:
+            - phpstan.broker.dynamicFunctionReturnTypeExtension
     -
         class: SzepeViktor\PHPStan\WordPress\GetPermalinkDynamicFunctionReturnTypeExtension
         tags:

src/WpTagCloudDynamicFunctionReturnTypeExtension.php

@@ -0,0 +1,138 @@
+<?php
+
+/**
+ * Set return type of various functions that support an `$echo` or `$display` parameter.
+ */
+
+declare(strict_types=1);
+
+namespace SzepeViktor\PHPStan\WordPress;
+
+use PhpParser\Node\Expr\FuncCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\FunctionReflection;
+use PHPStan\Type\ArrayType;
+use PHPStan\Type\Constant\ConstantStringType;
+use PHPStan\Type\IntegerType;
+use PHPStan\Type\StringType;
+use PHPStan\Type\Type;
+use PHPStan\Type\TypeCombinator;
+use PHPStan\Type\VoidType;
+
+class WpTagCloudDynamicFunctionReturnTypeExtension implements \PHPStan\Type\DynamicFunctionReturnTypeExtension
+{
+    /** @var \PHPStan\Type\Type */
+    private $argType;
+
+    /** @var bool $isEchoTrue */
+    private $isEchoTrue;
+
+    public function isFunctionSupported(FunctionReflection $functionReflection): bool
+    {
+        return $functionReflection->getName() === 'wp_tag_cloud';
+    }
+
+    /**
+     * @see https://developer.wordpress.org/reference/functions/wp_tag_cloud/
+     *
+     * @phpcsSuppress SlevomatCodingStandard.Functions.UnusedParameter.UnusedParameter
+     */
+    public function getTypeFromFunctionCall(FunctionReflection $functionReflection, FuncCall $functionCall, Scope $scope): ?Type
+    {
+        $args = $functionCall->getArgs();
+        if (count($args) === 0) {
+            return new VoidType();
+        }
+
+        $this->argType = $scope->getType($args[0]->value);
+
+        if (!$this->hasAnyConstantStringsArrays()) {
+            return $this->getReturnType('indetermined');
+        }
+
+        // We don't check strings, but if it's empty strings only, default values apply.
+        if (count($this->argType->getConstantStrings()) !== 0) {
+            return !$this->argType->isNonEmptyString()->no()
+                ? new VoidType()
+                : $this->getReturnType('indetermined');
+        }
+
+        // Now constants arrays are left.
+
+        $this->setIsEchoTrue();
+
+        $formatStr = new ConstantStringType('format');
+        if ($this->argType->hasOffsetValueType($formatStr)->no()) {
+            return $this->isEchoTrue
+                ? new VoidType()
+                : $this->getReturnType('formatFlat');
+        }
+
+        if ($this->argType->hasOffsetValueType($formatStr)->maybe()) {
+            return $this->isEchoTrue
+                ? $this->getReturnType('formatArray')
+                : $this->getReturnType('indetermined');
+        }
+
+        $formats = $this->argType->getOffsetValueType($formatStr)->getConstantStrings();
+        if (count($formats) === 0) {
+            return $this->isEchoTrue
+                ? $this->getReturnType('formatArray')
+                : $this->getReturnType('indetermined');
+        }
+
+        $returnTypes = [];
+        foreach ($formats as $format) {
+            if ($format->getValue() === 'array') {
+                $returnTypes[] = $this->getReturnType('formatArray');
+                continue;
+            }
+            if (!$this->isEchoTrue) {
+                $returnTypes[] = $this->getReturnType('formatFlat');
+            }
+            $returnTypes[] = new VoidType();
+        }
+        return TypeCombinator::union(...$returnTypes);
+    }
+
+    private function setIsEchoTrue(): void
+    {
+        $echo = new ConstantStringType('echo');
+        if ($this->argType->hasOffsetValueType($echo)->no()) {
+            $this->isEchoTrue = true;
+            return;
+        }
+        $this->isEchoTrue = $this->argType->getOffsetValueType($echo)->isTrue()->yes();
+    }
+
+    private function hasAnyConstantStringsArrays(): bool
+    {
+        if (count($this->argType->getConstantStrings()) !== 0) {
+            return true;
+        }
+        return count($this->argType->getConstantArrays()) !== 0;
+    }
+
+    /**
+     * @param 'formatFlat'|'formatArray'|'indetermined' $type
+     */
+    private function getReturnType(string $type): Type
+    {
+        switch ($type) {
+            case 'formatFlat':
+                return TypeCombinator::union(new StringType(), new VoidType());
+            case 'formatArray':
+                return TypeCombinator::union(
+                    new ArrayType(new IntegerType(), new StringType()),
+                    new VoidType()
+                );
+            case 'indetermined':
+                return TypeCombinator::union(
+                    $this->getReturnType('formatArray'),
+                    $this->getReturnType('formatFlat')
+                );
+            default:
+                throw new \PHPStan\ShouldNotHappenException();
+        }
+    }
+}

tests/DynamicReturnTypeExtensionTest.php

@@ -32,6 +32,7 @@ public function dataFileAsserts(): iterable
         yield from self::gatherAssertTypes(__DIR__ . '/data/wp_error_parameter.php');
         yield from self::gatherAssertTypes(__DIR__ . '/data/wp_parse_url.php');
         yield from self::gatherAssertTypes(__DIR__ . '/data/wp_die.php');
+        yield from self::gatherAssertTypes(__DIR__ . '/data/wp_tag_cloud.php');
         yield from self::gatherAssertTypes(__DIR__ . '/data/wp_theme_get.php');
     }
 

tests/data/wp_tag_cloud.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SzepeViktor\PHPStan\WordPress\Tests;
+
+use function wp_tag_cloud;
+use function PHPStan\Testing\assertType;
+
+// Default
+assertType('void', wp_tag_cloud());
+
+// Unknown
+assertType('array<int, string>|string|void', wp_tag_cloud($_GET['foo']));
+
+// Vary $args['echo'] with default $args['format']
+assertType('void', wp_tag_cloud(['echo' => true]));
+assertType('string|void', wp_tag_cloud(['echo' => false]));
+assertType('string|void', wp_tag_cloud(['echo' => $_GET['foo']]));
+
+// Vary $args['format'] with default $args['echo']
+assertType('array<int, string>|void', wp_tag_cloud(['format' => 'array']));
+assertType('void', wp_tag_cloud(['format' => 'flat']));
+assertType('array<int, string>|void', wp_tag_cloud(['format' => $_GET['foo']]));
+
+// Vary $args['format'] with $args['echo'] = true
+assertType('array<int, string>|void', wp_tag_cloud(['echo' => true, 'format' => 'array']));
+assertType('void', wp_tag_cloud(['echo' => true, 'format' => 'flat']));
+assertType('array<int, string>|void', wp_tag_cloud(['echo' => true, 'format' => $_GET['foo']]));
+
+// Vary $args['format'] with $args['echo'] = false
+assertType('array<int, string>|void', wp_tag_cloud(['echo' => false, 'format' => 'array']));
+assertType('string|void', wp_tag_cloud(['echo' => false, 'format' => 'flat']));
+assertType('array<int, string>|string|void', wp_tag_cloud(['echo' => false, 'format' => $_GET['foo']]));
+
+// Vary $args['format'] with unknown $args['echo']
+assertType('array<int, string>|void', wp_tag_cloud(['echo' => $_GET['foo'], 'format' => 'array']));
+assertType('string|void', wp_tag_cloud(['echo' => $_GET['foo'], 'format' => 'flat']));
+assertType('array<int, string>|string|void', wp_tag_cloud(['echo' => $_GET['foo'], 'format' => $_GET['baz']]));