added Explorer::table(), ActiveRow::related() and ref() return type narrowing

dg · dg · commit 3dbf21972d7f · 2026-03-28T18:33:21.000+01:00
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -85,6 +85,22 @@ Extensions for specific Nette packages use dedicated namespaces: `Nette\PHPStan\
 
 `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-nette.neon`.
 
+### TableRowTypeResolver
+
+`TableRowTypeResolver` is a shared service used by the three database extensions below. It resolves database table names to entity row class types using a configurable convention mask (e.g. `App\Entity\*Row` where `*` is replaced by PascalCase table name) and optional explicit table-to-class overrides. Checks class existence via `ReflectionProvider`. Config: `extension-nette.neon` parameters `nette.database.mapping.convention` and `nette.database.mapping.tables`.
+
+### ExplorerTableReturnTypeExtension
+
+`ExplorerTableReturnTypeExtension` (`DynamicMethodReturnTypeExtension`) narrows return type of `Explorer::table()` from `Selection<ActiveRow>` to `Selection<EntityRow>` based on table-to-entity-class mapping. When the table name argument is a constant string and the resolved entity class exists, returns `GenericObjectType('Selection', [$rowType])`. Falls back to declared return type otherwise. Config: `extension-nette.neon`.
+
+### ActiveRowRelatedReturnTypeExtension
+
+`ActiveRowRelatedReturnTypeExtension` (`DynamicMethodReturnTypeExtension`) narrows return type of `ActiveRow::related()` from `GroupedSelection` to `GroupedSelection<EntityRow>`. Handles both plain table names and `table.column` format by extracting the table portion. Config: `extension-nette.neon`.
+
+### ActiveRowRefReturnTypeExtension
+
+`ActiveRowRefReturnTypeExtension` (`DynamicMethodReturnTypeExtension`) narrows return type of `ActiveRow::ref()` from `?self` to `?EntityRow`. Handles both plain table names and `table.column` format. Uses `TypeCombinator::addNull()` to preserve nullability. Config: `extension-nette.neon`.
+
 ### Testing
 
 Tests use **Nette Tester** (not PHPUnit). Test files are `.phpt` in `tests/` with data files in `tests/data/`.
diff --git a/composer.json b/composer.json
@@ -17,6 +17,7 @@
 	},
 	"require-dev": {
 		"nette/component-model": "^3.1",
+		"nette/database": "^3.2",
 		"nette/forms": "^3.2",
 		"nette/schema": "^1.3",
 		"nette/tester": "^2.6"
diff --git a/extension-nette.neon b/extension-nette.neon
@@ -6,13 +6,47 @@ parameters:
 		- Nette\Security\SimpleIdentity
 		- Nette\Utils\Html
 
+	nette:
+		database:
+			mapping:
+				convention: ''
+				tables: []
+
+
+parametersSchema:
+	nette: structure([
+		database: structure([
+			mapping: structure([
+				convention: string()
+				tables: arrayOf(string(), string())
+			])
+		])
+	])
+
 
 services:
 	# nette/component-model
 	-
 		create: Nette\PHPStan\ComponentModel\GetComponentReturnTypeExtension
 		tags: [phpstan.broker.dynamicMethodReturnTypeExtension]
 
+	# nette/database
+	nette.database.tableRowTypeResolver:
+		create: Nette\PHPStan\Database\TableRowTypeResolver(
+			convention: %nette.database.mapping.convention%
+			tables: %nette.database.mapping.tables%
+		)
+
+	-
+		create: Nette\PHPStan\Database\ExplorerTableReturnTypeExtension
+		tags: [phpstan.broker.dynamicMethodReturnTypeExtension]
+	-
+		create: Nette\PHPStan\Database\ActiveRowRelatedReturnTypeExtension
+		tags: [phpstan.broker.dynamicMethodReturnTypeExtension]
+	-
+		create: Nette\PHPStan\Database\ActiveRowRefReturnTypeExtension
+		tags: [phpstan.broker.dynamicMethodReturnTypeExtension]
+
 	# nette/forms
 	-
 		create: Nette\PHPStan\Forms\FormContainerReturnTypeExtension(@defaultAnalysisParser)
diff --git a/readme.md b/readme.md
@@ -43,6 +43,18 @@ includes:
 
 **Precise return types** — narrows return types of `Strings::match()`, `matchAll()`, `split()`, `Helpers::falseToNull()`, `Expect::array()`, `Arrays::invoke()`, and `Arrays::invokeMethod()` based on the arguments you pass. Also narrows `Container::getComponent()` and `$container['...']` to match the corresponding `createComponent*()` factory return type. For forms, `$form['name']` returns the specific control type (e.g. `TextInput`, `SelectBox`) based on the `addText()`, `addSelect()`, etc. call in the same function.
 
+**Database row mapping** — narrows return types of `Explorer::table()`, `ActiveRow::related()`, and `ActiveRow::ref()` based on a configurable table-to-entity-class convention. For example, `$explorer->table('booking')` returns `Selection<BookingRow>` instead of `Selection<ActiveRow>`. Configure via:
+
+```neon
+parameters:
+    nette:
+        database:
+            mapping:
+                convention: App\Entity\*Row   # * = PascalCase table name
+                tables:                       # optional explicit overrides
+                    special_table: App\Entity\SpecialRow
+```
+
 **Html magic methods** — resolves `$html->getXxx()`, `setXxx()`, and `addXxx()` calls on `Nette\Utils\Html` that go through `__call()` but aren't declared via `@method` annotations.
 
 **Removes `|false` and `|null` from PHP functions** — many native functions like `getcwd`, `json_encode`, `preg_split`, `preg_replace`, and [many more](extension-php.neon) include `false` or `null` in their return type even though these error values are unrealistic on modern systems.
diff --git a/src/Database/ActiveRowRefReturnTypeExtension.php b/src/Database/ActiveRowRefReturnTypeExtension.php
@@ -0,0 +1,64 @@
+<?php declare(strict_types=1);
+
+namespace Nette\PHPStan\Database;
+
+use PhpParser\Node\Expr\MethodCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Type\DynamicMethodReturnTypeExtension;
+use PHPStan\Type\Type;
+use PHPStan\Type\TypeCombinator;
+use function count;
+
+
+/**
+ * Narrows return type of ActiveRow::ref() from ?self
+ * to ?EntityRow based on table-to-entity-class mapping.
+ */
+class ActiveRowRefReturnTypeExtension implements DynamicMethodReturnTypeExtension
+{
+	public function __construct(
+		private TableRowTypeResolver $resolver,
+	) {
+	}
+
+
+	public function getClass(): string
+	{
+		return 'Nette\Database\Table\ActiveRow';
+	}
+
+
+	public function isMethodSupported(MethodReflection $methodReflection): bool
+	{
+		return $methodReflection->getName() === 'ref';
+	}
+
+
+	public function getTypeFromMethodCall(
+		MethodReflection $methodReflection,
+		MethodCall $methodCall,
+		Scope $scope,
+	): ?Type
+	{
+		$args = $methodCall->getArgs();
+		if ($args === []) {
+			return null;
+		}
+
+		$keyType = $scope->getType($args[0]->value);
+		$constantStrings = $keyType->getConstantStrings();
+		if (count($constantStrings) !== 1) {
+			return null;
+		}
+
+		$key = $constantStrings[0]->getValue();
+		$tableName = $this->resolver->extractTableName($key);
+		$rowType = $this->resolver->resolve($tableName);
+		if ($rowType === null) {
+			return null;
+		}
+
+		return TypeCombinator::addNull($rowType);
+	}
+}
diff --git a/src/Database/ActiveRowRelatedReturnTypeExtension.php b/src/Database/ActiveRowRelatedReturnTypeExtension.php
@@ -0,0 +1,64 @@
+<?php declare(strict_types=1);
+
+namespace Nette\PHPStan\Database;
+
+use PhpParser\Node\Expr\MethodCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Type\DynamicMethodReturnTypeExtension;
+use PHPStan\Type\Generic\GenericObjectType;
+use PHPStan\Type\Type;
+use function count;
+
+
+/**
+ * Narrows return type of ActiveRow::related() from GroupedSelection<ActiveRow>
+ * to GroupedSelection<EntityRow> based on table-to-entity-class mapping.
+ */
+class ActiveRowRelatedReturnTypeExtension implements DynamicMethodReturnTypeExtension
+{
+	public function __construct(
+		private TableRowTypeResolver $resolver,
+	) {
+	}
+
+
+	public function getClass(): string
+	{
+		return 'Nette\Database\Table\ActiveRow';
+	}
+
+
+	public function isMethodSupported(MethodReflection $methodReflection): bool
+	{
+		return $methodReflection->getName() === 'related';
+	}
+
+
+	public function getTypeFromMethodCall(
+		MethodReflection $methodReflection,
+		MethodCall $methodCall,
+		Scope $scope,
+	): ?Type
+	{
+		$args = $methodCall->getArgs();
+		if ($args === []) {
+			return null;
+		}
+
+		$keyType = $scope->getType($args[0]->value);
+		$constantStrings = $keyType->getConstantStrings();
+		if (count($constantStrings) !== 1) {
+			return null;
+		}
+
+		$key = $constantStrings[0]->getValue();
+		$tableName = $this->resolver->extractTableName($key);
+		$rowType = $this->resolver->resolve($tableName);
+		if ($rowType === null) {
+			return null;
+		}
+
+		return new GenericObjectType('Nette\Database\Table\GroupedSelection', [$rowType]);
+	}
+}
diff --git a/src/Database/ExplorerTableReturnTypeExtension.php b/src/Database/ExplorerTableReturnTypeExtension.php
@@ -0,0 +1,63 @@
+<?php declare(strict_types=1);
+
+namespace Nette\PHPStan\Database;
+
+use PhpParser\Node\Expr\MethodCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Type\DynamicMethodReturnTypeExtension;
+use PHPStan\Type\Generic\GenericObjectType;
+use PHPStan\Type\Type;
+use function count;
+
+
+/**
+ * Narrows return type of Explorer::table() from Selection<ActiveRow>
+ * to Selection<EntityRow> based on table-to-entity-class mapping.
+ */
+class ExplorerTableReturnTypeExtension implements DynamicMethodReturnTypeExtension
+{
+	public function __construct(
+		private TableRowTypeResolver $resolver,
+	) {
+	}
+
+
+	public function getClass(): string
+	{
+		return 'Nette\Database\Explorer';
+	}
+
+
+	public function isMethodSupported(MethodReflection $methodReflection): bool
+	{
+		return $methodReflection->getName() === 'table';
+	}
+
+
+	public function getTypeFromMethodCall(
+		MethodReflection $methodReflection,
+		MethodCall $methodCall,
+		Scope $scope,
+	): ?Type
+	{
+		$args = $methodCall->getArgs();
+		if ($args === []) {
+			return null;
+		}
+
+		$nameType = $scope->getType($args[0]->value);
+		$constantStrings = $nameType->getConstantStrings();
+		if (count($constantStrings) !== 1) {
+			return null;
+		}
+
+		$tableName = $constantStrings[0]->getValue();
+		$rowType = $this->resolver->resolve($tableName);
+		if ($rowType === null) {
+			return null;
+		}
+
+		return new GenericObjectType('Nette\Database\Table\Selection', [$rowType]);
+	}
+}
diff --git a/src/Database/TableRowTypeResolver.php b/src/Database/TableRowTypeResolver.php
@@ -0,0 +1,67 @@
+<?php declare(strict_types=1);
+
+namespace Nette\PHPStan\Database;
+
+use PHPStan\Reflection\ReflectionProvider;
+use PHPStan\Type\ObjectType;
+
+
+/**
+ * Resolves database table names to entity row class types.
+ * Convention: table_name -> str_replace('*', PascalCase(table), mask).
+ * Explicit overrides in $tables take precedence over convention.
+ */
+class TableRowTypeResolver
+{
+	/**
+	 * @param string $convention mask like App\Entity\*Row, where * is replaced by PascalCase table name
+	 * @param array<string, string> $tables explicit table -> FQCN overrides
+	 */
+	public function __construct(
+		private ReflectionProvider $reflectionProvider,
+		private string $convention = '',
+		private array $tables = [],
+	) {
+	}
+
+
+	/**
+	 * Resolves a table name to an ObjectType for the entity row class.
+	 * Returns null if no mapping applies (class does not exist).
+	 */
+	public function resolve(string $tableName): ?ObjectType
+	{
+		if (isset($this->tables[$tableName])) {
+			$className = $this->tables[$tableName];
+			return $this->reflectionProvider->hasClass($className)
+				? new ObjectType($className)
+				: null;
+		}
+
+		if ($this->convention === '') {
+			return null;
+		}
+
+		$className = str_replace('*', $this->snakeToPascalCase($tableName), $this->convention);
+		return $this->reflectionProvider->hasClass($className)
+			? new ObjectType($className)
+			: null;
+	}
+
+
+	/**
+	 * Extracts the table name from a key parameter.
+	 * For related()/ref(), key can be 'table' or 'table.column'.
+	 */
+	public function extractTableName(string $key): string
+	{
+		$pos = strpos($key, '.');
+		return $pos !== false ? substr($key, 0, $pos) : $key;
+	}
+
+
+	private function snakeToPascalCase(string $table): string
+	{
+		return str_replace(' ', '', ucwords(strtr($table, '_', ' ')));
+	}
+}
diff --git a/tests/Database/active-row-ref-return-type.php b/tests/Database/active-row-ref-return-type.php
@@ -0,0 +1,22 @@
+<?php declare(strict_types=1);
+
+use Nette\Database\Table\ActiveRow;
+use function PHPStan\Testing\assertType;
+
+
+class RefEventRow extends ActiveRow
+{
+}
+
+
+function testRef(ActiveRow $row): void
+{
+	// Simple table name
+	assertType('RefEventRow|null', $row->ref('ref_event'));
+
+	// With throughColumn
+	assertType('RefEventRow|null', $row->ref('ref_event', 'event_id'));
+
+	// Unknown table -> falls back to declared return type
+	assertType('Nette\Database\Table\ActiveRow|null', $row->ref('unknown'));
+}
diff --git a/tests/Database/active-row-related-return-type.php b/tests/Database/active-row-related-return-type.php
diff --git a/tests/Database/database-row-mapping.neon b/tests/Database/database-row-mapping.neon
diff --git a/tests/Database/explorer-table-return-type.php b/tests/Database/explorer-table-return-type.php
diff --git a/tests/extensions.phpt b/tests/extensions.phpt
