Support returning an array or a string in count_chars()

conf/config.neon

@@ -1262,13 +1262,18 @@ services:
 			- phpstan.broker.dynamicFunctionReturnTypeExtension
 
 	-
-	    class: PHPStan\Type\Php\ConstantHelper
+		class: PHPStan\Type\Php\ConstantHelper
 
 	-
 		class: PHPStan\Type\Php\CountFunctionReturnTypeExtension
 		tags:
 			- phpstan.broker.dynamicFunctionReturnTypeExtension
 
+	-
+		class: PHPStan\Type\Php\CountCharsFunctionDynamicReturnTypeExtension
+		tags:
+			- phpstan.broker.dynamicFunctionReturnTypeExtension
+
 	-
 		class: PHPStan\Type\Php\CountFunctionTypeSpecifyingExtension
 		tags:

src/Type/Php/CountCharsFunctionDynamicReturnTypeExtension.php

@@ -0,0 +1,59 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Type\Php;
+
+use PhpParser\Node\Expr\FuncCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Php\PhpVersion;
+use PHPStan\Reflection\FunctionReflection;
+use PHPStan\Type\ArrayType;
+use PHPStan\Type\Constant\ConstantBooleanType;
+use PHPStan\Type\DynamicFunctionReturnTypeExtension;
+use PHPStan\Type\IntegerRangeType;
+use PHPStan\Type\IntegerType;
+use PHPStan\Type\StringType;
+use PHPStan\Type\Type;
+use PHPStan\Type\TypeUtils;
+use PHPStan\Type\UnionType;
+use function count;
+
+final class CountCharsFunctionDynamicReturnTypeExtension implements DynamicFunctionReturnTypeExtension
+{
+
+	public function __construct(private PhpVersion $phpVersion)
+	{
+	}
+
+	public function isFunctionSupported(FunctionReflection $functionReflection): bool
+	{
+		return $functionReflection->getName() === 'count_chars';
+	}
+
+	public function getTypeFromFunctionCall(
+		FunctionReflection $functionReflection,
+		FuncCall $functionCall,
+		Scope $scope,
+	): ?Type
+	{
+		if (count($functionCall->getArgs()) < 1) {
+			return null;
+		}
+
+		$modeType = $scope->getType($functionCall->getArgs()[1]->value);
+
+		if (IntegerRangeType::fromInterval(0, 2)->isSuperTypeOf($modeType)->yes()) {
+			$arrayType = new ArrayType(new IntegerType(), new IntegerType());
+
+			return $this->phpVersion->throwsValueErrorForInternalFunctions()
+				? $arrayType
+				: TypeUtils::toBenevolentUnion(new UnionType([$arrayType, new ConstantBooleanType(false)]));
+		}
+
+		$stringType = new StringType();
+
+		return $this->phpVersion->throwsValueErrorForInternalFunctions()
+			? $stringType
+			: TypeUtils::toBenevolentUnion(new UnionType([$stringType, new ConstantBooleanType(false)]));
+	}
+
+}

tests/PHPStan/Analyser/nsrt/count-chars-7.4.php

@@ -0,0 +1,21 @@
+<?php // lint <= 7.4
+
+namespace CountChars;
+
+use function PHPStan\Testing\assertType;
+
+class X {
+	const ABC = 'abcdef';
+
+	function doFoo(): void {
+		assertType('array<int, int>|false', count_chars(self::ABC, 0));
+		assertType('array<int, int>|false', count_chars(self::ABC, 1));
+		assertType('array<int, int>|false', count_chars(self::ABC, 2));
+
+		assertType('string|false', count_chars(self::ABC, 3));
+		assertType('string|false', count_chars(self::ABC, 4));
+
+		assertType('string|false', count_chars(self::ABC, -1));
+		assertType('string|false', count_chars(self::ABC, 5));
+	}
+}

tests/PHPStan/Analyser/nsrt/count-chars-8.0.php

@@ -0,0 +1,21 @@
+<?php // lint >= 8.0
+
+namespace CountChars;
+
+use function PHPStan\Testing\assertType;
+
+class Y {
+	const ABC = 'abcdef';
+
+	function doFoo(): void {
+		assertType('array<int, int>', count_chars(self::ABC, 0));
+		assertType('array<int, int>', count_chars(self::ABC, 1));
+		assertType('array<int, int>', count_chars(self::ABC, 2));
+
+		assertType('string', count_chars(self::ABC, 3));
+		assertType('string', count_chars(self::ABC, 4));
+
+		assertType('string', count_chars(self::ABC, -1));
+		assertType('string', count_chars(self::ABC, 5));
+	}
+}