From 620c8b2e4992737191fad09d6fc266cc63d0981a Mon Sep 17 00:00:00 2001
From: Jack Worman <jworman@healthcall.com>
Date: Wed, 4 Dec 2024 20:26:32 -0500
Subject: [PATCH] Fix-GH-12021

---
 ...mptyStringFunctionsReturnTypeExtension.php | 30 +++++++++++++++++++
 .../Analyser/nsrt/non-empty-string.php        |  9 ++++++
 .../Analyser/nsrt/non-falsy-string.php        |  5 ++++
 3 files changed, 44 insertions(+)

diff --git a/src/Type/Php/NonEmptyStringFunctionsReturnTypeExtension.php b/src/Type/Php/NonEmptyStringFunctionsReturnTypeExtension.php
index 083914085a..893627aae2 100644
--- a/src/Type/Php/NonEmptyStringFunctionsReturnTypeExtension.php
+++ b/src/Type/Php/NonEmptyStringFunctionsReturnTypeExtension.php
@@ -2,17 +2,20 @@
 
 namespace PHPStan\Type\Php;
 
+use PhpParser\Node\Arg;
 use PhpParser\Node\Expr\FuncCall;
 use PHPStan\Analyser\Scope;
 use PHPStan\Reflection\FunctionReflection;
 use PHPStan\Type\Accessory\AccessoryNonEmptyStringType;
 use PHPStan\Type\Accessory\AccessoryNonFalsyStringType;
+use PHPStan\Type\Constant\ConstantIntegerType;
 use PHPStan\Type\DynamicFunctionReturnTypeExtension;
 use PHPStan\Type\IntersectionType;
 use PHPStan\Type\StringType;
 use PHPStan\Type\Type;
 use function count;
 use function in_array;
+use const ENT_SUBSTITUTE;
 
 final class NonEmptyStringFunctionsReturnTypeExtension implements DynamicFunctionReturnTypeExtension
 {
@@ -45,6 +48,15 @@ public function getTypeFromFunctionCall(
 			return null;
 		}
 
+		if (in_array($functionReflection->getName(), [
+			'htmlspecialchars',
+			'htmlentities',
+		], true)) {
+			if (!$this->isSubstituteFlagSet($args, $scope)) {
+				return new StringType();
+			}
+		}
+
 		$argType = $scope->getType($args[0]->value);
 		if ($argType->isNonFalsyString()->yes()) {
 			return new IntersectionType([
@@ -62,4 +74,22 @@ public function getTypeFromFunctionCall(
 		return new StringType();
 	}
 
+	/**
+	 * @param Arg[] $args
+	 */
+	private function isSubstituteFlagSet(
+		array $args,
+		Scope $scope,
+	): bool
+	{
+		if (!isset($args[1])) {
+			return true;
+		}
+		$flagsType = $scope->getType($args[1]->value);
+		if (!$flagsType instanceof ConstantIntegerType) {
+			return false;
+		}
+		return (bool) ($flagsType->getValue() & ENT_SUBSTITUTE);
+	}
+
 }
diff --git a/tests/PHPStan/Analyser/nsrt/non-empty-string.php b/tests/PHPStan/Analyser/nsrt/non-empty-string.php
index cd831db4d8..59d1af3931 100644
--- a/tests/PHPStan/Analyser/nsrt/non-empty-string.php
+++ b/tests/PHPStan/Analyser/nsrt/non-empty-string.php
@@ -8,6 +8,7 @@
 use function strtolower;
 use function strtoupper;
 use function ucfirst;
+use const ENT_SUBSTITUTE;
 
 class Foo
 {
@@ -333,9 +334,17 @@ public function doFoo(string $s, string $nonEmpty, string $nonFalsy, int $i, boo
 		assertType('string', ucwords($s));
 		assertType('non-empty-string', ucwords($nonEmpty));
 		assertType('string', htmlspecialchars($s));
+		assertType('string', htmlspecialchars($s, ENT_SUBSTITUTE));
+		assertType('string', htmlspecialchars($s, 0));
 		assertType('non-empty-string', htmlspecialchars($nonEmpty));
+		assertType('non-empty-string', htmlspecialchars($nonEmpty, ENT_SUBSTITUTE));
+		assertType('string', htmlspecialchars($nonEmpty, 0));
 		assertType('string', htmlentities($s));
+		assertType('string', htmlentities($s, ENT_SUBSTITUTE));
+		assertType('string', htmlentities($s, 0));
 		assertType('non-empty-string', htmlentities($nonEmpty));
+		assertType('non-empty-string', htmlentities($nonEmpty, ENT_SUBSTITUTE));
+		assertType('string', htmlentities($nonEmpty, 0));
 
 		assertType('string', urlencode($s));
 		assertType('non-empty-string', urlencode($nonEmpty));
diff --git a/tests/PHPStan/Analyser/nsrt/non-falsy-string.php b/tests/PHPStan/Analyser/nsrt/non-falsy-string.php
index c5fd9fc1d8..744bdaf3b5 100644
--- a/tests/PHPStan/Analyser/nsrt/non-falsy-string.php
+++ b/tests/PHPStan/Analyser/nsrt/non-falsy-string.php
@@ -3,6 +3,7 @@
 namespace NonFalseyString;
 
 use function PHPStan\Testing\assertType;
+use const ENT_SUBSTITUTE;
 
 class Foo {
 	/**
@@ -95,7 +96,11 @@ function stringFunctions(string $s, $nonFalsey, $arrayOfNonFalsey, $nonEmptyArra
 		assertType('non-falsy-string', ucfirst($nonFalsey));
 		assertType('non-falsy-string', ucwords($nonFalsey));
 		assertType('non-falsy-string', htmlspecialchars($nonFalsey));
+		assertType('non-falsy-string', htmlspecialchars($nonFalsey, ENT_SUBSTITUTE));
+		assertType('string', htmlspecialchars($nonFalsey, 0));
 		assertType('non-falsy-string', htmlentities($nonFalsey));
+		assertType('non-falsy-string', htmlentities($nonFalsey, ENT_SUBSTITUTE));
+		assertType('string', htmlentities($nonFalsey, 0));
 
 		assertType('non-falsy-string', urlencode($nonFalsey));
 		assertType('non-falsy-string', urldecode($nonFalsey));