如何看懂 phpstan-doctrine 的 DQL 类型推断QueryResultTypeWalker 源码完整解析【免费下载链接】phpstan-doctrineDoctrine extensions for PHPStan项目地址: https://gitcode.com/gh_mirrors/ph/phpstan-doctrinephpstan-doctrine 是一个为 PHPStan 提供 Doctrine ORM 静态分析支持的开源扩展包它的核心能力之一就是DQL 结果类型推断当你调用EntityManager::createQuery(SELECT ...)时普通的Query::getResult()只能返回mixed[]而借助 QueryResultTypeWalker 这个类PHPStan 能精确推断出getResult()返回的实体类型、标量字段类型甚至数组形状。本文将从新手视角完整解析这套静态类型推断是如何实现的。一、它解决了什么问题在 Doctrine 项目中写 DQL 查询时结果类型长期是一个黑盒SELECT e FROM Entity e→ 返回Entity[]SELECT e.name AS n FROM Entity e→ 返回array{0 string|null}[]还是array{n ...}[]SELECT COUNT(e) AS cnt, MAX(e.price) AS max FROM Entity e→ 聚合函数在不同数据库下返回类型完全不同如果没有静态推断IDE 补全失效、类型错误无法提前发现。phpstan-doctrine 的思路非常巧妙在静态分析阶段不真正连数据库执行查询而是重放 Doctrine 官方的 DQL 解析流程把每一句 DQL 变成 PHPStan 能理解的具体类型。二、五步流水线整体架构一览 ⚙️整个推断流程由 5 个核心类协作完成全部位于src/Type/Doctrine/目录下步骤核心类文件路径职责1️⃣CreateQueryDynamicReturnTypeExtensionsrc/Type/Doctrine/CreateQueryDynamicReturnTypeExtension.php拦截createQuery(DQL)调用触发分析2️⃣QueryResultTypeWalkersrc/Type/Doctrine/Query/QueryResultTypeWalker.php遍历 DQL 语法树AST推断每个表达式类型3️⃣QueryResultTypeBuildersrc/Type/Doctrine/Query/QueryResultTypeBuilder.php汇总实体、标量、NEW 对象组装最终结果类型4️⃣QueryTypesrc/Type/Doctrine/Query/QueryType.php把推断结果封装进QueryTKey, TResult泛型5️⃣QueryResultDynamicReturnTypeExtensionHydrationModeReturnTypeResolversrc/Type/Doctrine/Query/QueryResultDynamicReturnTypeExtension.php让getResult()、getSingleResult()等方法返回具体类型流程示意文字版createQuery(DQL) │ ① 拦截调用 ▼ QueryResultTypeWalker::walk() ← ② 遍历 DQL 语法树 │ ③ 沿途把类型记账 ▼ QueryResultTypeBuilder.getResultType() │ ④ 封装 ▼ QueryTKey, TResult │ ⑤ 后续方法调用 ▼ getResult() → Entity[] / array{...}[]三、QueryResultTypeWalker推断引擎的核心QueryResultTypeWalker继承自 Doctrine ORM 的SqlWalker——这并非偶然。Doctrine 的语法树节点dispatch()方法只接受SqlWalker类型所以伪装成官方 Walker 是复用整棵 AST 遍历机制的关键。3.1 为什么依赖要通过 Hints 传递这是源码中最反直觉的设计。在 walk() 静态方法 中$query-setHint(self::HINT_TYPE_MAPPING, $typeBuilder); $query-setHint(self::HINT_DESCRIPTOR_REGISTRY, $descriptorRegistry); $parser new Parser($query); $parser-parse();原因是Parser内部会new QueryResultTypeWalker(...)外部无法通过构造函数注入依赖。于是作者利用 Doctrine 的 Query Hints 机制HINT_TYPE_MAPPING、HINT_DESCRIPTOR_REGISTRY等常量定义在 第 81–87 行把类型构建器、描述符注册表、PHP 版本、驱动检测器夹带进查询对象再在构造器中取出。这个技巧也是阅读 Doctrine 扩展源码时值得学习的设计模式。3.2 如何逐个节点推断类型Walker 为每种 AST 节点实现了walkXxx()方法核心逻辑有三类walkSelectStatement()标记这是一个 SELECT 查询并先处理FROM子句记录 LEFT JOIN 产生的可空别名walkPathExpression()处理e.name这类字段访问——查实体元数据得到 Doctrine 类型名如string、datetime再经DescriptorRegistry映射为 PHPStan 类型如string、DateTimeInterfacewalkSelectExpression()SELECT 子句的分拣口判断选出的是整实体addEntity、标量字段addScalar还是NEW Dto(...)addNewObject。3.3 聚合函数最体现精细的地方walkFunction()方法第 415 行起覆盖了AVG、SUM、MIN、MAX、ABS、SQRT、COUNT、CONCAT、MOD等几乎所有 DQL 函数。有趣的是它对同一函数的推断结果随数据库驱动而变。例如SUM(int列)驱动SUM 返回AVG 返回MySQL / mysqlinumeric-stringnumeric-stringSQLiteintfloatPostgreSQLint或numeric-stringnumeric-string源码里用大段注释矩阵记录了不同驱动的实测行为可打开inferSumFunction()查看。这就是 DriverDetector 的用途——根据 EntityManager 的真实连接探测驱动类型让推断结果贴近运行时事实而不是拍脑袋猜。四、QueryResultTypeBuilder结果的记账本Walker 每推断出一个类型就向QueryResultTypeBuilder记一笔。这个类刻意模仿了 Doctrine 的ResultSetMapping但只服务于静态类型。它维护四本账entities—— 选出的实体别名 → 实体类型scalars—— 选出的标量字段别名 → 标量类型newObjects——NEW Dto(...)投影对象indexedBy——INDEX BY子句产生的键类型最终 getResultType() 按一套清晰的规则组装结果源码注释写得非常清楚可归纳为只选一个实体、无别名→ 结果就是实体类型本身配合getResult()得Entity[]一个 NEW 对象→ 直接是 DTO 类型忽略其他项标量 / NEW 对象 / 带别名实体→ 组装为数组形状array{...}别名即键名无名标量用 1 起始的序号多个任意 JOIN 的实体→ 实体类型联合Entity1|Entity2这套规则与 Doctrine 运行时水合器Hydrator的真实行为严格对齐保证静态推断 运行时实际返回。五、可空性推断LEFT JOIN 与聚合的隐藏细节两个容易出 bug 的细节Walker 都处理了LEFT JOIN 可空性walkJoin()记录LEFT JOIN产生的别名随后该别名下的实体或字段类型都会自动附加null无 GROUP BY 的聚合COUNT(e)永远是int0, max但MAX(e.price)在整表为空时返回null所以聚合且无 GROUP BY 时标量类型自动变为可空。这些细节正是getOneOrNullResult()能精确返回Entity|null的基础——HydrationModeReturnTypeResolver会依据水合模式HYDRATE_OBJECT/HYDRATE_SIMPLEOBJECT和方法名做最后调整第 23–90 行getSingleResult()返回单个结果、toIterable()返回iterable、其余返回数组INDEX BY则决定数组的键类型。六、实际效果与相关源码地图 ✅启用扩展后项目根目录 extension.neon 已注册全部服务createQuery的返回类型变为QueryTKey, TResultIDE 与 PHPStan 即可对结果做精确补全和错误检查。相关测试用例可参考 QueryResultTypeWalkerTest其中覆盖了 LEFT JOIN 可空性、聚合、枚举、复合主键、DBAL 4.2 等多种场景。快速定位源码的导航表想理解……去看推断入口拦截 createQuerysrc/Type/Doctrine/CreateQueryDynamicReturnTypeExtension.phpAST 遍历与逐表达式推断src/Type/Doctrine/Query/QueryResultTypeWalker.php结果类型组装规则src/Type/Doctrine/Query/QueryResultTypeBuilder.php泛型 Query 类型src/Type/Doctrine/Query/QueryType.phpgetResult 等方法返回类型src/Type/Doctrine/HydrationModeReturnTypeResolver.php驱动探测MySQL/SQLite/PGsrc/Doctrine/Driver/DriverDetector.php一句话总结QueryResultTypeWalker 的精髓是用 Hints 完成依赖注入、重放官方 DQL 解析器遍历语法树把每个表达式映射为 PHPStan 类型后交给 Builder 记账最终让getResult()的类型推断与 Doctrine 运行时行为完全一致——这就是 phpstan-doctrine 类型推断能力的核心。【免费下载链接】phpstan-doctrineDoctrine extensions for PHPStan项目地址: https://gitcode.com/gh_mirrors/ph/phpstan-doctrine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
如何看懂 phpstan-doctrine 的 DQL 类型推断？QueryResultTypeWalker 源码完整解析
如何看懂 phpstan-doctrine 的 DQL 类型推断QueryResultTypeWalker 源码完整解析【免费下载链接】phpstan-doctrineDoctrine extensions for PHPStan项目地址: https://gitcode.com/gh_mirrors/ph/phpstan-doctrinephpstan-doctrine 是一个为 PHPStan 提供 Doctrine ORM 静态分析支持的开源扩展包它的核心能力之一就是DQL 结果类型推断当你调用EntityManager::createQuery(SELECT ...)时普通的Query::getResult()只能返回mixed[]而借助 QueryResultTypeWalker 这个类PHPStan 能精确推断出getResult()返回的实体类型、标量字段类型甚至数组形状。本文将从新手视角完整解析这套静态类型推断是如何实现的。一、它解决了什么问题在 Doctrine 项目中写 DQL 查询时结果类型长期是一个黑盒SELECT e FROM Entity e→ 返回Entity[]SELECT e.name AS n FROM Entity e→ 返回array{0 string|null}[]还是array{n ...}[]SELECT COUNT(e) AS cnt, MAX(e.price) AS max FROM Entity e→ 聚合函数在不同数据库下返回类型完全不同如果没有静态推断IDE 补全失效、类型错误无法提前发现。phpstan-doctrine 的思路非常巧妙在静态分析阶段不真正连数据库执行查询而是重放 Doctrine 官方的 DQL 解析流程把每一句 DQL 变成 PHPStan 能理解的具体类型。二、五步流水线整体架构一览 ⚙️整个推断流程由 5 个核心类协作完成全部位于src/Type/Doctrine/目录下步骤核心类文件路径职责1️⃣CreateQueryDynamicReturnTypeExtensionsrc/Type/Doctrine/CreateQueryDynamicReturnTypeExtension.php拦截createQuery(DQL)调用触发分析2️⃣QueryResultTypeWalkersrc/Type/Doctrine/Query/QueryResultTypeWalker.php遍历 DQL 语法树AST推断每个表达式类型3️⃣QueryResultTypeBuildersrc/Type/Doctrine/Query/QueryResultTypeBuilder.php汇总实体、标量、NEW 对象组装最终结果类型4️⃣QueryTypesrc/Type/Doctrine/Query/QueryType.php把推断结果封装进QueryTKey, TResult泛型5️⃣QueryResultDynamicReturnTypeExtensionHydrationModeReturnTypeResolversrc/Type/Doctrine/Query/QueryResultDynamicReturnTypeExtension.php让getResult()、getSingleResult()等方法返回具体类型流程示意文字版createQuery(DQL) │ ① 拦截调用 ▼ QueryResultTypeWalker::walk() ← ② 遍历 DQL 语法树 │ ③ 沿途把类型记账 ▼ QueryResultTypeBuilder.getResultType() │ ④ 封装 ▼ QueryTKey, TResult │ ⑤ 后续方法调用 ▼ getResult() → Entity[] / array{...}[]三、QueryResultTypeWalker推断引擎的核心QueryResultTypeWalker继承自 Doctrine ORM 的SqlWalker——这并非偶然。Doctrine 的语法树节点dispatch()方法只接受SqlWalker类型所以伪装成官方 Walker 是复用整棵 AST 遍历机制的关键。3.1 为什么依赖要通过 Hints 传递这是源码中最反直觉的设计。在 walk() 静态方法 中$query-setHint(self::HINT_TYPE_MAPPING, $typeBuilder); $query-setHint(self::HINT_DESCRIPTOR_REGISTRY, $descriptorRegistry); $parser new Parser($query); $parser-parse();原因是Parser内部会new QueryResultTypeWalker(...)外部无法通过构造函数注入依赖。于是作者利用 Doctrine 的 Query Hints 机制HINT_TYPE_MAPPING、HINT_DESCRIPTOR_REGISTRY等常量定义在 第 81–87 行把类型构建器、描述符注册表、PHP 版本、驱动检测器夹带进查询对象再在构造器中取出。这个技巧也是阅读 Doctrine 扩展源码时值得学习的设计模式。3.2 如何逐个节点推断类型Walker 为每种 AST 节点实现了walkXxx()方法核心逻辑有三类walkSelectStatement()标记这是一个 SELECT 查询并先处理FROM子句记录 LEFT JOIN 产生的可空别名walkPathExpression()处理e.name这类字段访问——查实体元数据得到 Doctrine 类型名如string、datetime再经DescriptorRegistry映射为 PHPStan 类型如string、DateTimeInterfacewalkSelectExpression()SELECT 子句的分拣口判断选出的是整实体addEntity、标量字段addScalar还是NEW Dto(...)addNewObject。3.3 聚合函数最体现精细的地方walkFunction()方法第 415 行起覆盖了AVG、SUM、MIN、MAX、ABS、SQRT、COUNT、CONCAT、MOD等几乎所有 DQL 函数。有趣的是它对同一函数的推断结果随数据库驱动而变。例如SUM(int列)驱动SUM 返回AVG 返回MySQL / mysqlinumeric-stringnumeric-stringSQLiteintfloatPostgreSQLint或numeric-stringnumeric-string源码里用大段注释矩阵记录了不同驱动的实测行为可打开inferSumFunction()查看。这就是 DriverDetector 的用途——根据 EntityManager 的真实连接探测驱动类型让推断结果贴近运行时事实而不是拍脑袋猜。四、QueryResultTypeBuilder结果的记账本Walker 每推断出一个类型就向QueryResultTypeBuilder记一笔。这个类刻意模仿了 Doctrine 的ResultSetMapping但只服务于静态类型。它维护四本账entities—— 选出的实体别名 → 实体类型scalars—— 选出的标量字段别名 → 标量类型newObjects——NEW Dto(...)投影对象indexedBy——INDEX BY子句产生的键类型最终 getResultType() 按一套清晰的规则组装结果源码注释写得非常清楚可归纳为只选一个实体、无别名→ 结果就是实体类型本身配合getResult()得Entity[]一个 NEW 对象→ 直接是 DTO 类型忽略其他项标量 / NEW 对象 / 带别名实体→ 组装为数组形状array{...}别名即键名无名标量用 1 起始的序号多个任意 JOIN 的实体→ 实体类型联合Entity1|Entity2这套规则与 Doctrine 运行时水合器Hydrator的真实行为严格对齐保证静态推断 运行时实际返回。五、可空性推断LEFT JOIN 与聚合的隐藏细节两个容易出 bug 的细节Walker 都处理了LEFT JOIN 可空性walkJoin()记录LEFT JOIN产生的别名随后该别名下的实体或字段类型都会自动附加null无 GROUP BY 的聚合COUNT(e)永远是int0, max但MAX(e.price)在整表为空时返回null所以聚合且无 GROUP BY 时标量类型自动变为可空。这些细节正是getOneOrNullResult()能精确返回Entity|null的基础——HydrationModeReturnTypeResolver会依据水合模式HYDRATE_OBJECT/HYDRATE_SIMPLEOBJECT和方法名做最后调整第 23–90 行getSingleResult()返回单个结果、toIterable()返回iterable、其余返回数组INDEX BY则决定数组的键类型。六、实际效果与相关源码地图 ✅启用扩展后项目根目录 extension.neon 已注册全部服务createQuery的返回类型变为QueryTKey, TResultIDE 与 PHPStan 即可对结果做精确补全和错误检查。相关测试用例可参考 QueryResultTypeWalkerTest其中覆盖了 LEFT JOIN 可空性、聚合、枚举、复合主键、DBAL 4.2 等多种场景。快速定位源码的导航表想理解……去看推断入口拦截 createQuerysrc/Type/Doctrine/CreateQueryDynamicReturnTypeExtension.phpAST 遍历与逐表达式推断src/Type/Doctrine/Query/QueryResultTypeWalker.php结果类型组装规则src/Type/Doctrine/Query/QueryResultTypeBuilder.php泛型 Query 类型src/Type/Doctrine/Query/QueryType.phpgetResult 等方法返回类型src/Type/Doctrine/HydrationModeReturnTypeResolver.php驱动探测MySQL/SQLite/PGsrc/Doctrine/Driver/DriverDetector.php一句话总结QueryResultTypeWalker 的精髓是用 Hints 完成依赖注入、重放官方 DQL 解析器遍历语法树把每个表达式映射为 PHPStan 类型后交给 Builder 记账最终让getResult()的类型推断与 Doctrine 运行时行为完全一致——这就是 phpstan-doctrine 类型推断能力的核心。【免费下载链接】phpstan-doctrineDoctrine extensions for PHPStan项目地址: https://gitcode.com/gh_mirrors/ph/phpstan-doctrine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
![[光学原理与应用-521]：对光的错误理解与纠偏](http://pic.xiahunao.cn/yaotu/[光学原理与应用-521]：对光的错误理解与纠偏)
