added FalseToNullReturnTypeExtension

Author: dg

CLAUDE.md

@@ -38,7 +38,7 @@ Each extension class is registered as a service in NEON with the appropriate tag
 
 ### Namespace conventions
 
-Extensions for specific Nette packages use dedicated namespaces: `Nette\PHPStan\Schema\` for nette/schema, future packages follow the same pattern (`Nette\PHPStan\Forms\`, `Nette\PHPStan\Application\`, etc.). Generic PHP-level extensions use `Nette\PHPStan\Php\`.
+Extensions for specific Nette packages use dedicated namespaces: `Nette\PHPStan\Schema\` for nette/schema, `Nette\PHPStan\Utils\` for nette/utils, future packages follow the same pattern (`Nette\PHPStan\Forms\`, `Nette\PHPStan\Application\`, etc.). Generic PHP-level extensions use `Nette\PHPStan\Php\`.
 
 ### ExpectArrayReturnTypeExtension
 
@@ -56,6 +56,10 @@ Extensions for specific Nette packages use dedicated namespaces: `Nette\PHPStan\
 
 `RemoveFalseReturnTypeExtension` (`ExpressionTypeResolverExtension`) removes `|false` from return types of native PHP functions and methods where false 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. 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-utils.neon`.
+
 ### AssertTypeNarrowingExtension
 
 `AssertTypeNarrowingExtension` (`StaticMethodTypeSpecifyingExtension` + `TypeSpecifierAwareExtension`) narrows variable types after `Tester\Assert` assertion calls. Each assertion method is mapped to an equivalent PHP expression that PHPStan already understands, then delegated to `TypeSpecifier::specifyTypesInCondition()`. Supported methods: `null`, `notNull`, `true`, `false`, `truthy`, `falsey`, `same`, `notSame`, and `type` (with built-in type strings like `'string'`, `'int'`, etc. and class/interface names). Config: `extension-tester.neon`.

extension-utils.neon

@@ -0,0 +1,4 @@
+services:
+	-
+		class: Nette\PHPStan\Utils\FalseToNullReturnTypeExtension
+		tags: [phpstan.broker.dynamicStaticMethodReturnTypeExtension]

extension.neon

@@ -17,3 +17,4 @@ includes:
 	- extension-php.neon
 	- extension-schema.neon
 	- extension-tester.neon
+	- extension-utils.neon

readme.md

@@ -84,6 +84,7 @@ Assert::type('int', $value);
 
 ### Other
 
+- Narrows the return type of `Helpers::falseToNull()` — e.g. `string|false` → `string|null`
 - Narrows the return type of `Expect::array()` from `Structure|Type` to `Structure` or `Type` based on the argument
 
  <!---->

src/Utils/FalseToNullReturnTypeExtension.php

@@ -0,0 +1,62 @@
+<?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/FalseToNullReturnTypeTest.phpt

@@ -0,0 +1,11 @@
+<?php declare(strict_types=1);
+
+/**
+ * Test: Helpers::falseToNull() return type narrowing.
+ */
+
+require __DIR__ . '/../bootstrap.php';
+
+use Nette\PHPStan\Tester\TypeAssert;
+
+TypeAssert::assertTypes(__DIR__ . '/../data/utils/false-to-null-return-type.php', [__DIR__ . '/../../extension.neon']);

tests/data/utils/false-to-null-return-type.php

@@ -0,0 +1,44 @@
+<?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));
+}