From ee9d8d22be5e077dd80e1e44b75315bceb31d8f6 Mon Sep 17 00:00:00 2001
From: Takuya Aramaki <takaram71@gmail.com>
Date: Sun, 23 Nov 2025 18:22:30 +0900
Subject: [PATCH] Narrow string type when `ctype_*` functions return true

---
 conf/config.neon                      |   1 +
 stubs/ctype.stub                      |  51 +++++++++
 tests/PHPStan/Analyser/nsrt/ctype.php | 151 ++++++++++++++++++++++++++
 3 files changed, 203 insertions(+)
 create mode 100644 stubs/ctype.stub
 create mode 100644 tests/PHPStan/Analyser/nsrt/ctype.php

diff --git a/conf/config.neon b/conf/config.neon
index af2a15cba5..018f87958b 100644
--- a/conf/config.neon
+++ b/conf/config.neon
@@ -144,6 +144,7 @@ parameters:
 		- ../stubs/file.stub
 		- ../stubs/stream_socket_client.stub
 		- ../stubs/stream_socket_server.stub
+		- ../stubs/ctype.stub
 	earlyTerminatingMethodCalls: []
 	earlyTerminatingFunctionCalls: []
 	resultCachePath: %tmpDir%/resultCache.php
diff --git a/stubs/ctype.stub b/stubs/ctype.stub
new file mode 100644
index 0000000000..872296b47a
--- /dev/null
+++ b/stubs/ctype.stub
@@ -0,0 +1,51 @@
+<?php
+
+/**
+ * @phpstan-assert-if-true =($text is string ? non-empty-string : int) $text
+ */
+function ctype_alnum(mixed $text): bool {}
+
+/**
+ * @phpstan-assert-if-true =($text is string ? non-falsy-string : int) $text
+ */
+function ctype_alpha(mixed $text): bool {}
+
+/**
+ * @phpstan-assert-if-true =($text is string ? non-falsy-string : int) $text
+ */
+function ctype_cntrl(mixed $text): bool {}
+
+/**
+ * @phpstan-assert-if-true =($text is string ? non-falsy-string : int) $text
+ */
+function ctype_lower(mixed $text): bool {}
+
+/**
+ * @phpstan-assert-if-true =($text is string ? non-empty-string : int) $text
+ */
+function ctype_graph(mixed $text): bool {}
+
+/**
+ * @phpstan-assert-if-true =($text is string ? non-empty-string : int) $text
+ */
+function ctype_print(mixed $text): bool {}
+
+/**
+ * @phpstan-assert-if-true =($text is string ? non-falsy-string : int) $text
+ */
+function ctype_punct(mixed $text): bool {}
+
+/**
+ * @phpstan-assert-if-true =($text is string ? non-falsy-string : int) $text
+ */
+function ctype_space(mixed $text): bool {}
+
+/**
+ * @phpstan-assert-if-true =($text is string ? non-falsy-string : int) $text
+ */
+function ctype_upper(mixed $text): bool {}
+
+/**
+ * @phpstan-assert-if-true =($text is string ? non-empty-string : int) $text
+ */
+function ctype_xdigit(mixed $text): bool {}
diff --git a/tests/PHPStan/Analyser/nsrt/ctype.php b/tests/PHPStan/Analyser/nsrt/ctype.php
new file mode 100644
index 0000000000..25f8cec12c
--- /dev/null
+++ b/tests/PHPStan/Analyser/nsrt/ctype.php
@@ -0,0 +1,151 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ctype;
+
+use function ctype_alnum;
+use function ctype_alpha;
+use function ctype_cntrl;
+use function ctype_graph;
+use function ctype_lower;
+use function ctype_print;
+use function ctype_punct;
+use function ctype_space;
+use function ctype_upper;
+use function ctype_xdigit;
+use function PHPStan\Testing\assertType;
+
+function test(string $str): void
+{
+	// functions asserting non-falsy-string
+
+	if (ctype_alpha($str)) {
+		assertType('non-falsy-string', $str);
+	} else {
+		assertType('string', $str);
+	}
+
+	if (ctype_cntrl($str)) {
+		assertType('non-falsy-string', $str);
+	} else {
+		assertType('string', $str);
+	}
+
+	if (ctype_lower($str)) {
+		assertType('non-falsy-string', $str);
+	} else {
+		assertType('string', $str);
+	}
+
+	if (ctype_upper($str)) {
+		assertType('non-falsy-string', $str);
+	} else {
+		assertType('string', $str);
+	}
+
+	if (ctype_punct($str)) {
+		assertType('non-falsy-string', $str);
+	} else {
+		assertType('string', $str);
+	}
+
+	if (ctype_space($str)) {
+		assertType('non-falsy-string', $str);
+	} else {
+		assertType('string', $str);
+	}
+
+	// functions asserting non-empty-string
+	// ctype_digit is tested in another file
+
+	if (ctype_alnum($str)) {
+		assertType('non-empty-string', $str);
+	} else {
+		assertType('string', $str);
+	}
+
+	if (ctype_graph($str)) {
+		assertType('non-empty-string', $str);
+	} else {
+		assertType('string', $str);
+	}
+
+	if (ctype_print($str)) {
+		assertType('non-empty-string', $str);
+	} else {
+		assertType('string', $str);
+	}
+
+	if (ctype_xdigit($str)) {
+		assertType('non-empty-string', $str);
+	} else {
+		assertType('string', $str);
+	}
+}
+
+function testInt(int $int): void
+{
+	if (ctype_alpha($int)) {
+		assertType('int', $int);
+	} else {
+		assertType('int', $int);
+	}
+
+	if (ctype_cntrl($int)) {
+		assertType('int', $int);
+	} else {
+		assertType('int', $int);
+	}
+
+	if (ctype_lower($int)) {
+		assertType('int', $int);
+	} else {
+		assertType('int', $int);
+	}
+
+	if (ctype_upper($int)) {
+		assertType('int', $int);
+	} else {
+		assertType('int', $int);
+	}
+
+	if (ctype_punct($int)) {
+		assertType('int', $int);
+	} else {
+		assertType('int', $int);
+	}
+
+	if (ctype_space($int)) {
+		assertType('int', $int);
+	} else {
+		assertType('int', $int);
+	}
+
+	// functions asserting non-empty-string
+	// ctype_digit is tested in another file
+
+	if (ctype_alnum($int)) {
+		assertType('int', $int);
+	} else {
+		assertType('int', $int);
+	}
+
+	if (ctype_graph($int)) {
+		assertType('int', $int);
+	} else {
+		assertType('int', $int);
+	}
+
+	if (ctype_print($int)) {
+		assertType('int', $int);
+	} else {
+		assertType('int', $int);
+	}
+
+	if (ctype_xdigit($int)) {
+		assertType('int', $int);
+	} else {
+		assertType('int', $int);
+	}
+}