Do not parenthesize a benevolent union that describes as a single type

The members of a benevolent union can describe the same at a verbosity
level, like decimal-int-string and non-empty-string&uppercase-string as
string at the type-only level. The union then described as "(string)", for
example in "Parameter #1 $num of function ceil expects float|int, (string)
given." for a string cast of a benevolent (float|int).

The parentheses now only wrap a description that has a "|".

Amp-Thread-ID: https://ampcode.com/threads/T-01a19770-5331-74b2-963f-e324ae0f7635

Author: ondrejmirtes

src/Type/BenevolentUnionType.php

@@ -6,6 +6,7 @@
 use PHPStan\Turbo\ShadowedByTurboExtension;
 use PHPStan\Type\Generic\TemplateTypeMap;
 use function count;
+use function str_contains;
 
 /** @api */
 #[ShadowedByTurboExtension(implementation: __DIR__ . '/../../turbo-ext/src/BenevolentUnionType.cpp')]
@@ -43,7 +44,14 @@ public function tryRemove(Type $typeToRemove): ?Type
 
 	public function describe(VerbosityLevel $level): string
 	{
-		return '(' . parent::describe($level) . ')';
+		$description = parent::describe($level);
+
+		// the members can describe the same at this level, like decimal-int-string|non-empty-string as string
+		if (!str_contains($description, '|')) {
+			return $description;
+		}
+
+		return '(' . $description . ')';
 	}
 
 	protected function unionTypes(callable $getType): Type

tests/PHPStan/Rules/Functions/CallToFunctionParametersRuleTest.php

@@ -186,7 +186,7 @@ public function testCallToFunctionWithDynamicIterableParameters(): void
 		$this->analyse([__DIR__ . '/data/function-with-variadic-parameters-7.1.php'], [
 			[
 				'Parameter #2 ...$foo of function FunctionWithVariadicParameters\foo expects int, string given.',
-				16,
+				18,
 			],
 		]);
 	}
@@ -1989,7 +1989,7 @@ public function testBug10626(): void
 		$this->analyse([__DIR__ . '/data/bug-10626.php'], [
 			[
 				'Parameter #1 $value of function Bug10626\intByValue expects int, string given.',
-				16,
+				18,
 			],
 			[
 				'Parameter #1 $value of function Bug10626\intByReference expects int, string given.',
@@ -3450,4 +3450,19 @@ public function testFloatRangeArgument(): void
 		]);
 	}
 
+	#[RequiresPhp('>= 8.0.0')]
+	public function testBenevolentUnionDescription(): void
+	{
+		$this->analyse([__DIR__ . '/data/benevolent-union-description.php'], [
+			[
+				'Parameter #1 $num of function BenevolentUnionDescription\\takesNumber expects float|int, string given.',
+				18,
+			],
+			[
+				'Parameter #1 $s of function BenevolentUnionDescription\\takesString expects string, (float|int) given.',
+				19,
+			],
+		]);
+	}
+
 }

tests/PHPStan/Rules/Functions/data/benevolent-union-description.php

@@ -0,0 +1,20 @@
+<?php // lint >= 8.0
+
+declare(strict_types = 1);
+
+namespace BenevolentUnionDescription;
+
+function takesNumber(float|int $num): void
+{
+}
+
+function takesString(string $s): void
+{
+}
+
+function doFoo(int|float $number, int $scale): void
+{
+	$coefficient = 10 ** $scale;
+	takesNumber((string) ($number * $coefficient));
+	takesString($coefficient);
+}

turbo-ext/src/BenevolentUnionType.cpp

@@ -108,14 +108,17 @@ class BenevolentUnionType
 		return toBenevolent(result.raw());
 	}
 
-	/* '(' . parent::describe($level) . ')' */
+	/* '(' . parent::describe($level) . ')', unwrapped when it has no '|'
+	 * because the members describe the same at this level */
 	zv::Val describe(zval *level) const
 	{
 		zv::Val inner = pt_union_type_describe(self, level);
 		if (UNEXPECTED(inner.isUndef())) return zv::Val();
+		zend_string *innerString = zv::Ref(inner.raw()).asString();
+		if (memchr(ZSTR_VAL(innerString), '|', ZSTR_LEN(innerString)) == NULL) return inner;
 		smart_str description = {NULL, 0};
 		smart_str_appendc(&description, '(');
-		smart_str_append(&description, zv::Ref(inner.raw()).asString());
+		smart_str_append(&description, innerString);
 		smart_str_appendc(&description, ')');
 		smart_str_0(&description);
 		return zv::Val::adoptString(description.s);

turbo-ext/tests/type-family.php

@@ -3645,6 +3645,8 @@ public function getValuesArray(): \PHPStan\Type\Constant\ConstantArrayType
 		'benevolentArrays' => new $benevolentClass([new \PHPStan\Type\ArrayType(new \PHPStan\Type\IntegerType(), new \PHPStan\Type\StringType()), $compoundConstShape(['a' => new \PHPStan\Type\IntegerType()])]),
 		'benevolentConsts' => new $benevolentClass([new \PHPStan\Type\Constant\ConstantIntegerType(1), new \PHPStan\Type\Constant\ConstantStringType('a')]),
 		'benevolentObjects' => new $benevolentClass([new \PHPStan\Type\ObjectType(\stdClass::class), new \PHPStan\Type\StringType()]),
+		// both members describe as string at the type-only level
+		'benevolentStrings' => new $benevolentClass([new $intersectionClass([new \PHPStan\Type\StringType(), new \PHPStan\Type\Accessory\AccessoryDecimalIntegerStringType()]), new $intersectionClass([new \PHPStan\Type\StringType(), new \PHPStan\Type\Accessory\AccessoryNonEmptyStringType(), new \PHPStan\Type\Accessory\AccessoryUppercaseStringType()])]),
 		'templateUnion' => \PHPStan\Type\Generic\TemplateTypeFactory::create($compoundScope, 'U', new $unionClass([new \PHPStan\Type\IntegerType(), new \PHPStan\Type\StringType()]), \PHPStan\Type\Generic\TemplateTypeVariance::createInvariant()),
 		'templateBenevolentUnion' => \PHPStan\Type\Generic\TemplateTypeFactory::create($compoundScope, 'B', new $benevolentClass([new \PHPStan\Type\IntegerType(), new \PHPStan\Type\StringType()]), \PHPStan\Type\Generic\TemplateTypeVariance::createInvariant()),
 		'nonEmptyString' => new $intersectionClass([new \PHPStan\Type\StringType(), new \PHPStan\Type\Accessory\AccessoryNonEmptyStringType()]),