 自动返回精确实体类型的完整指南)
phpstan-doctrine 类型推断getResult() 自动返回精确实体类型的完整指南【免费下载链接】phpstan-doctrineDoctrine extensions for PHPStan项目地址: https://gitcode.com/gh_mirrors/ph/phpstan-doctrine如果你写过 Symfony 或 Laravel 风格的 Doctrine 查询一定遇到过这样的尴尬$query-getResult()的返回值类型是mixedIDE 和 PHPStan 完全无法帮你检查结果数组里的字段拼写、类型错误只能等到运行时才爆雷。phpstan-doctrine 类型推断功能正是为了解决这个问题而生——它让 PHPStan 在静态分析阶段就能算出getResult()返回的精确实体类型比如listApp\Entity\User把大量隐患消灭在代码提交之前。本指南将带你完整了解这套类型推断机制的原理、支持的方法、配置步骤与实战技巧。为什么需要 getResult() 的精确类型推断没有 phpstan-doctrine 时的痛苦 先看一个最常见的场景使用 Doctrine ORM 的原生 DQL 查询。$query $em-createQuery(SELECT u FROM App\Entity\User u); $users $query-getResult(); foreach ($users as $user) { echo $user-getNmae(); // 手滑拼错了IDE 无提示运行才报错 }在未安装 phpstan-doctrine 时getResult()的返回值是mixed意味着字段名拼写错误、方法名笔误PHPStan 完全无法察觉不确定$users到底是实体列表、标量数组还是数组嵌套类型系统处于失明状态重构实体字段后所有使用处静默失联只能靠测试兜底有了 phpstan-doctrine 之后 安装扩展后同样的代码会得到精确到实体类的类型$query $em-createQuery(SELECT u FROM App\Entity\User u); $users $query-getResult(); // PHPStan 推断: listApp\Entity\User foreach ($users as $user) { echo $user-getName(); // 拼错立即报错 }$user-getNmae()这类低级错误在保存文件的那一刻就会被 PHPStan 高亮出来这就是Doctrine 实体类型推断带来的最直接价值。phpstan-doctrine 类型推断的核心原理整套机制可以分为三层每一层都有对应的源码模块第一层createQuery() 解析 DQL产出 Query 泛型当你调用$em-createQuery(SELECT ...)时CreateQueryDynamicReturnTypeExtension位于src/Type/Doctrine/CreateQueryDynamicReturnTypeExtension.php会接管返回类型它用QueryResultTypeWalker真正解析一遍 DQL 语法树把结果类型填充进Doctrine\ORM\QueryTKey, TResult这个泛型参数里。 也就是说查询语句在静态分析阶段就被执行了一次——只不过执行的是语法解析而不是数据库查询。第二层QueryResultTypeWalker 逐句分析 SELECT 表达式QueryResultTypeWalker位于src/Type/Doctrine/Query/QueryResultTypeWalker.php是一个基于 Doctrine AST 的 TreeWalker它会分析SELECT 了哪些实体别名、哪些标量字段是否存在 JOIN、聚合函数SUM、AVG 等是否使用了NEW对象表达式是否使用INDEX BY指定键名分析结果被写入QueryResultTypeBuildersrc/Type/Doctrine/Query/QueryResultTypeBuilder.php最终组装出完整的返回类型例如DQL 写法推断出的结果类型SELECT u FROM ... User ulistUserSELECT u.name, u.age FROM ...listarray{name: string, age: int}SELECT NEW App\Dto\UserDto(u.name) FROM ...listUserDtoSELECT u FROM ... User u INDEX BY u.idarrayint, UserUPDATE / DELETE 语句int0, max受影响行数第三层getResult() 按水合模式换算返回类型最终决定getResult()返回值的是QueryResultDynamicReturnTypeExtension位于src/Type/Doctrine/Query/QueryResultDynamicReturnTypeExtension.php和HydrationModeReturnTypeResolversrc/Type/Doctrine/HydrationModeReturnTypeResolver.php。扩展会读取你调用时传入的水合模式参数HYDRATE_OBJECT、HYDRATE_ARRAY等再结合 Query 的泛型参数算出最终返回类型。哪些方法支持类型推断一张表看懂phpstan-doctrine 为Doctrine\ORM\AbstractQuery的以下方法提供了动态返回类型方法默认推断结果说明getResult()list实体/数组形状最常用默认 HYDRATE_OBJECTgetSingleResult()实体/数组形状单条结果getOneOrNullResult()实体/数组形状 \| null可能为空toIterable()iterableint, 实体适合大数据量流式处理execute()list实体显式传 HYDRATE_OBJECT 时可推断executeIgnoreQueryCache()同上ORM 2.x 可用executeUsingQueryCache()同上ORM 2.x 可用关键细节水合模式决定推断成败HYDRATE_OBJECT默认可推断返回实体对象列表 ✅HYDRATE_SIMPLEOBJECT仅当结果全是对象时可推断 ✅HYDRATE_ARRAY对象被转成数组类型不确定回退为mixed⚠️动态传入的水合模式非常量无法推断回退为方法声明的返回类型 ⚠️在测试文件tests/Type/Doctrine/data/QueryResult/queryResult.php中你能看到上述每种情况的完整断言用例非常适合作为学习参考。三步开启 getResult 类型推断第一步安装扩展使用 Composer 安装并推荐同时安装phpstan/extension-installer实现自动注册composer require --dev phpstan/phpstan-doctrine composer require --dev phpstan/extension-installer如果你不想用 extension-installer也可以在 PHPStan 配置中手动引入includes: - vendor/phpstan/phpstan-doctrine/extension.neon第二步配置 objectManagerLoader关键一步要让 PHPStan 真正读懂你的实体映射需要提供一个对象管理器加载器即一段返回EntityManagerInterface实例的引导脚本。这是完整类型推断的前提因为 DQL 解析需要真实的实体元数据。以 Symfony 项目为例创建tests/object-manager.php?php use App\Kernel; require __DIR__ . /../config/bootstrap.php; $kernel new Kernel($_SERVER[APP_ENV], (bool) $_SERVER[APP_DEBUG]); $kernel-boot(); return $kernel-getContainer()-get(doctrine)-getManager();然后在phpstan.neon中声明parameters: doctrine: objectManagerLoader: tests/object-manager.php第三步运行静态分析vendor/bin/phpstan analyse src此时再对getResult()的结果调用不存在的方法或访问不存在的字段PHPStan 会立刻报错。进阶技巧QueryBuilder 链式调用同样支持推断除了原生 DQLQueryBuilder的链式调用同样被完整跟踪。QueryBuilderGetQueryDynamicReturnTypeExtensionsrc/Type/Doctrine/QueryBuilder/QueryBuilderGetQueryDynamicReturnTypeExtension.php会记录每一次select、join、where、setMaxResults等调用在调用getQuery()时重建 DQL 并走同一套类型分析管线$query $em-createQueryBuilder() -select(u) -from(User::class, u) -where(u.active :active) -setParameter(active, true) -getQuery(); $users $query-getResult(); // PHPStan 推断: listUser 已知的推断边界where、orderBy、groupBy等条件类方法不影响结果类型属于安全方法参数值setParameter在静态分析时无法完全模拟会做保守处理动态拼接、字符串变量传入的 DQL 无法被解析会回退为原始返回类型实战收益总结为什么值得用消灭字段拼写噩梦实体属性、方法名的错误在 CI 之前就被拦截重构更安全改动实体字段后所有查询使用点自动暴露代码即文档listUser这样的类型让协作的同事一眼看懂查询意图与 PHPStan 生态无缝衔接精确类型可以继续参与var断言、死代码检测等后续分析常见问题速查 ❓Q安装了扩展但 getResult() 还是 mixedA最常见原因是没配置objectManagerLoader或加载器脚本没有正确返回 EntityManager 实例。Q标量查询能推断吗A能。SELECT u.name, u.age FROM ...会被推断为listarray{name: string, age: int}这种数组形状array shape字段和类型都精确。QUPDATE/DELETE 语句返回什么A推断为int0, max即受影响行数和运行时行为一致。Q项目同时支持哪些 Doctrine 版本A支持 ORM 2.x/3.x、DBAL 3.x/4.x、ODM 2.4兼容层位于compatibility/目录适配逻辑分散在stubs/PHPStan 桩文件与extension.neon服务注册中。phpstan-doctrine 的类型推断把运行时才知道的查询结果类型提前到了静态分析阶段是任何使用 Doctrine ORM 的 PHP 项目都值得安装的开发利器。安装、配置、享受精确类型三步就能让你的代码质量上一个台阶。【免费下载链接】phpstan-doctrineDoctrine extensions for PHPStan项目地址: https://gitcode.com/gh_mirrors/ph/phpstan-doctrine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 phpstan-doctrine 类型推断：getResult() 自动返回精确实体类型的完整指南
phpstan-doctrine 类型推断getResult() 自动返回精确实体类型的完整指南【免费下载链接】phpstan-doctrineDoctrine extensions for PHPStan项目地址: https://gitcode.com/gh_mirrors/ph/phpstan-doctrine如果你写过 Symfony 或 Laravel 风格的 Doctrine 查询一定遇到过这样的尴尬$query-getResult()的返回值类型是mixedIDE 和 PHPStan 完全无法帮你检查结果数组里的字段拼写、类型错误只能等到运行时才爆雷。phpstan-doctrine 类型推断功能正是为了解决这个问题而生——它让 PHPStan 在静态分析阶段就能算出getResult()返回的精确实体类型比如listApp\Entity\User把大量隐患消灭在代码提交之前。本指南将带你完整了解这套类型推断机制的原理、支持的方法、配置步骤与实战技巧。为什么需要 getResult() 的精确类型推断没有 phpstan-doctrine 时的痛苦 先看一个最常见的场景使用 Doctrine ORM 的原生 DQL 查询。$query $em-createQuery(SELECT u FROM App\Entity\User u); $users $query-getResult(); foreach ($users as $user) { echo $user-getNmae(); // 手滑拼错了IDE 无提示运行才报错 }在未安装 phpstan-doctrine 时getResult()的返回值是mixed意味着字段名拼写错误、方法名笔误PHPStan 完全无法察觉不确定$users到底是实体列表、标量数组还是数组嵌套类型系统处于失明状态重构实体字段后所有使用处静默失联只能靠测试兜底有了 phpstan-doctrine 之后 安装扩展后同样的代码会得到精确到实体类的类型$query $em-createQuery(SELECT u FROM App\Entity\User u); $users $query-getResult(); // PHPStan 推断: listApp\Entity\User foreach ($users as $user) { echo $user-getName(); // 拼错立即报错 }$user-getNmae()这类低级错误在保存文件的那一刻就会被 PHPStan 高亮出来这就是Doctrine 实体类型推断带来的最直接价值。phpstan-doctrine 类型推断的核心原理整套机制可以分为三层每一层都有对应的源码模块第一层createQuery() 解析 DQL产出 Query 泛型当你调用$em-createQuery(SELECT ...)时CreateQueryDynamicReturnTypeExtension位于src/Type/Doctrine/CreateQueryDynamicReturnTypeExtension.php会接管返回类型它用QueryResultTypeWalker真正解析一遍 DQL 语法树把结果类型填充进Doctrine\ORM\QueryTKey, TResult这个泛型参数里。 也就是说查询语句在静态分析阶段就被执行了一次——只不过执行的是语法解析而不是数据库查询。第二层QueryResultTypeWalker 逐句分析 SELECT 表达式QueryResultTypeWalker位于src/Type/Doctrine/Query/QueryResultTypeWalker.php是一个基于 Doctrine AST 的 TreeWalker它会分析SELECT 了哪些实体别名、哪些标量字段是否存在 JOIN、聚合函数SUM、AVG 等是否使用了NEW对象表达式是否使用INDEX BY指定键名分析结果被写入QueryResultTypeBuildersrc/Type/Doctrine/Query/QueryResultTypeBuilder.php最终组装出完整的返回类型例如DQL 写法推断出的结果类型SELECT u FROM ... User ulistUserSELECT u.name, u.age FROM ...listarray{name: string, age: int}SELECT NEW App\Dto\UserDto(u.name) FROM ...listUserDtoSELECT u FROM ... User u INDEX BY u.idarrayint, UserUPDATE / DELETE 语句int0, max受影响行数第三层getResult() 按水合模式换算返回类型最终决定getResult()返回值的是QueryResultDynamicReturnTypeExtension位于src/Type/Doctrine/Query/QueryResultDynamicReturnTypeExtension.php和HydrationModeReturnTypeResolversrc/Type/Doctrine/HydrationModeReturnTypeResolver.php。扩展会读取你调用时传入的水合模式参数HYDRATE_OBJECT、HYDRATE_ARRAY等再结合 Query 的泛型参数算出最终返回类型。哪些方法支持类型推断一张表看懂phpstan-doctrine 为Doctrine\ORM\AbstractQuery的以下方法提供了动态返回类型方法默认推断结果说明getResult()list实体/数组形状最常用默认 HYDRATE_OBJECTgetSingleResult()实体/数组形状单条结果getOneOrNullResult()实体/数组形状 \| null可能为空toIterable()iterableint, 实体适合大数据量流式处理execute()list实体显式传 HYDRATE_OBJECT 时可推断executeIgnoreQueryCache()同上ORM 2.x 可用executeUsingQueryCache()同上ORM 2.x 可用关键细节水合模式决定推断成败HYDRATE_OBJECT默认可推断返回实体对象列表 ✅HYDRATE_SIMPLEOBJECT仅当结果全是对象时可推断 ✅HYDRATE_ARRAY对象被转成数组类型不确定回退为mixed⚠️动态传入的水合模式非常量无法推断回退为方法声明的返回类型 ⚠️在测试文件tests/Type/Doctrine/data/QueryResult/queryResult.php中你能看到上述每种情况的完整断言用例非常适合作为学习参考。三步开启 getResult 类型推断第一步安装扩展使用 Composer 安装并推荐同时安装phpstan/extension-installer实现自动注册composer require --dev phpstan/phpstan-doctrine composer require --dev phpstan/extension-installer如果你不想用 extension-installer也可以在 PHPStan 配置中手动引入includes: - vendor/phpstan/phpstan-doctrine/extension.neon第二步配置 objectManagerLoader关键一步要让 PHPStan 真正读懂你的实体映射需要提供一个对象管理器加载器即一段返回EntityManagerInterface实例的引导脚本。这是完整类型推断的前提因为 DQL 解析需要真实的实体元数据。以 Symfony 项目为例创建tests/object-manager.php?php use App\Kernel; require __DIR__ . /../config/bootstrap.php; $kernel new Kernel($_SERVER[APP_ENV], (bool) $_SERVER[APP_DEBUG]); $kernel-boot(); return $kernel-getContainer()-get(doctrine)-getManager();然后在phpstan.neon中声明parameters: doctrine: objectManagerLoader: tests/object-manager.php第三步运行静态分析vendor/bin/phpstan analyse src此时再对getResult()的结果调用不存在的方法或访问不存在的字段PHPStan 会立刻报错。进阶技巧QueryBuilder 链式调用同样支持推断除了原生 DQLQueryBuilder的链式调用同样被完整跟踪。QueryBuilderGetQueryDynamicReturnTypeExtensionsrc/Type/Doctrine/QueryBuilder/QueryBuilderGetQueryDynamicReturnTypeExtension.php会记录每一次select、join、where、setMaxResults等调用在调用getQuery()时重建 DQL 并走同一套类型分析管线$query $em-createQueryBuilder() -select(u) -from(User::class, u) -where(u.active :active) -setParameter(active, true) -getQuery(); $users $query-getResult(); // PHPStan 推断: listUser 已知的推断边界where、orderBy、groupBy等条件类方法不影响结果类型属于安全方法参数值setParameter在静态分析时无法完全模拟会做保守处理动态拼接、字符串变量传入的 DQL 无法被解析会回退为原始返回类型实战收益总结为什么值得用消灭字段拼写噩梦实体属性、方法名的错误在 CI 之前就被拦截重构更安全改动实体字段后所有查询使用点自动暴露代码即文档listUser这样的类型让协作的同事一眼看懂查询意图与 PHPStan 生态无缝衔接精确类型可以继续参与var断言、死代码检测等后续分析常见问题速查 ❓Q安装了扩展但 getResult() 还是 mixedA最常见原因是没配置objectManagerLoader或加载器脚本没有正确返回 EntityManager 实例。Q标量查询能推断吗A能。SELECT u.name, u.age FROM ...会被推断为listarray{name: string, age: int}这种数组形状array shape字段和类型都精确。QUPDATE/DELETE 语句返回什么A推断为int0, max即受影响行数和运行时行为一致。Q项目同时支持哪些 Doctrine 版本A支持 ORM 2.x/3.x、DBAL 3.x/4.x、ODM 2.4兼容层位于compatibility/目录适配逻辑分散在stubs/PHPStan 桩文件与extension.neon服务注册中。phpstan-doctrine 的类型推断把运行时才知道的查询结果类型提前到了静态分析阶段是任何使用 Doctrine ORM 的 PHP 项目都值得安装的开发利器。安装、配置、享受精确类型三步就能让你的代码质量上一个台阶。【免费下载链接】phpstan-doctrineDoctrine extensions for PHPStan项目地址: https://gitcode.com/gh_mirrors/ph/phpstan-doctrine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考