added Helpers::falseToNull() return type narrowing (string|false → string|null)

Author: dg

CLAUDE.md

@@ -57,6 +57,10 @@ Extensions for specific Nette packages use dedicated namespaces: `Nette\PHPStan\
 
 `RemoveFailingReturnTypeExtension` (`ExpressionTypeResolverExtension`) removes `|false` or `|null` from return types of native PHP functions and methods where the error return value is trivial or outdated. It handles `FuncCall`, `MethodCall`, and `StaticCall` in a single class. Configuration uses a flat list in NEON — plain names for functions (`json_encode`), `Class::method` notation for methods (`Normalizer::normalize`). It runs before all `DynamicReturnTypeExtension` implementations, delegates to them via `DynamicReturnTypeExtensionRegistry`, and strips `|false` from the result. For `preg_replace`, `preg_replace_callback`, `preg_replace_callback_array`, and `preg_filter` it strips `|null` instead (these return null on PCRE error). For `preg_replace_callback_array` pattern validation checks array keys. Config: `extension-php.neon`.
 
+### FalseToNullReturnTypeExtension
+
+`FalseToNullReturnTypeExtension` (`DynamicStaticMethodReturnTypeExtension`) narrows the return type of `Helpers::falseToNull()` from `mixed`. It removes `false` from the argument type and adds `null` — e.g. `string|false` → `string|null`, `false` → `null`, types without `false` pass through unchanged. Config: `extension-nette.neon`.
+
 ### StringsReturnTypeExtension
 
 `StringsReturnTypeExtension` (`DynamicStaticMethodReturnTypeExtension`) narrows return types of `Strings::match()`, `matchAll()` and `split()` based on boolean arguments. It resolves `captureOffset`, `unmatchedAsNull`, `patternOrder`, and `lazy` to constant booleans and constructs the precise return type — e.g. `match()` with `captureOffset: true` returns `array<array{string, int<0, max>}>|null` instead of `?array`. When a boolean argument is not a constant, falls back to the declared return type. Config: `extension-nette.neon`.

extension-nette.neon

@@ -22,6 +22,9 @@ services:
 		tags: [phpstan.typeSpecifier.staticMethodTypeSpecifyingExtension]
 
 	# nette/utils
+	-
+		create: Nette\PHPStan\Utils\FalseToNullReturnTypeExtension
+		tags: [phpstan.broker.dynamicStaticMethodReturnTypeExtension]
 	-
 		create: Nette\PHPStan\Utils\StringsReturnTypeExtension
 		tags: [phpstan.broker.dynamicStaticMethodReturnTypeExtension]

src/Utils/FalseToNullReturnTypeExtension.php

@@ -0,0 +1,60 @@
+<?php declare(strict_types=1);
+
+namespace Nette\PHPStan\Utils;
+
+use Nette\Utils\Helpers;
+use PhpParser\Node\Expr\StaticCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Type\Constant\ConstantBooleanType;
+use PHPStan\Type\DynamicStaticMethodReturnTypeExtension;
+use PHPStan\Type\NeverType;
+use PHPStan\Type\NullType;
+use PHPStan\Type\Type;
+use PHPStan\Type\TypeCombinator;
+
+
+/**
+ * Narrows the return type of Helpers::falseToNull() from mixed.
+ * Removes false from the argument type and adds null instead.
+ */
+class FalseToNullReturnTypeExtension implements DynamicStaticMethodReturnTypeExtension
+{
+	public function getClass(): string
+	{
+		return Helpers::class;
+	}
+
+
+	public function isStaticMethodSupported(MethodReflection $methodReflection): bool
+	{
+		return $methodReflection->getName() === 'falseToNull';
+	}
+
+
+	public function getTypeFromStaticMethodCall(
+		MethodReflection $methodReflection,
+		StaticCall $methodCall,
+		Scope $scope,
+	): ?Type
+	{
+		$args = $methodCall->getArgs();
+		if ($args === []) {
+			return null;
+		}
+
+		$argType = $scope->getType($args[0]->value);
+		$falseType = new ConstantBooleanType(false);
+
+		if ($falseType->isSuperTypeOf($argType)->no()) {
+			return $argType;
+		}
+
+		$withoutFalse = TypeCombinator::remove($argType, $falseType);
+		if ($withoutFalse instanceof NeverType) {
+			return new NullType;
+		}
+
+		return TypeCombinator::addNull($withoutFalse);
+	}
+}

tests/Utils/false-to-null-return-type.php

@@ -0,0 +1,42 @@
+<?php declare(strict_types=1);
+
+use Nette\Utils\Helpers;
+use function PHPStan\Testing\assertType;
+
+
+// false → null
+assertType('null', Helpers::falseToNull(false));
+
+// no false in type → unchanged
+assertType("'hello'", Helpers::falseToNull('hello'));
+assertType('123', Helpers::falseToNull(123));
+
+
+function testStringFalse(string|false $value): void
+{
+	assertType('string|null', Helpers::falseToNull($value));
+}
+
+
+function testIntFalse(int|false $value): void
+{
+	assertType('int|null', Helpers::falseToNull($value));
+}
+
+
+function testStringFalseNull(string|false|null $value): void
+{
+	assertType('string|null', Helpers::falseToNull($value));
+}
+
+
+function testBool(bool $value): void
+{
+	assertType('true|null', Helpers::falseToNull($value));
+}
+
+
+function testNoFalse(int $value): void
+{
+	assertType('int', Helpers::falseToNull($value));
+}

tests/extensions.phpt

@@ -18,4 +18,5 @@ TypeAssert::assertTypes(__DIR__ . '/Tester/assert-in-function.php');
 TypeAssert::assertTypes(__DIR__ . '/Tester/assert-type-with-custom-class.php');
 
 // Utils
+TypeAssert::assertTypes(__DIR__ . '/Utils/false-to-null-return-type.php');
 TypeAssert::assertTypes(__DIR__ . '/Utils/strings-return-type.php');