开发工具【免费下载链接】object-enumeratorTraverses array structures and object graphs to enumerate all referenced objects项目地址https://gitcode.com/gh_mirrors/ob/object-enumerator点击查看免费下载本篇指南以 PHPStan 官方升级文档位于本仓库 tools/.phpstan/vendor/phpstan/phpstan/UPGRADING.md为骨架系统梳理从 PHPStan 1.x 升级到 2.0 的全部要点终端用户侧的配置项移除与替代方案、官方扩展的参数变更以及扩展开发者必须面对的 API 破坏性变更。文章同时以本仓库 object-enumerator一个遍历数组结构与对象图、枚举所有被引用对象的 PHP 组件作为真实实践样本——该仓库已运行于 PHPStan 2.3.1 之上读完本文你将能够独立完成自己项目的 PHPStan 2.0 升级并掌握自定义规则与扩展的适配方法。一、升级前的环境要求PHPStan 2.0 对运行环境提出了新的最低要求PHPStan 现在要求 PHP 7.4 或更高版本才能运行见 tools/.phpstan/vendor/phpstan/phpstan/composer.json 中php: ^7.4|^8.0的声明。如果你的项目还在使用 PHP 7.3 及以下版本需要先升级运行环境再考虑 PHPStan 2.0 迁移。二、面向终端用户的升级路径官方推荐的升级路线非常明确不要直接一步跳到 2.0而是先做好准备再平滑切换。整个过程分为三个阶段。阶段一升级到最新 1.12 并开启 Bleeding Edge升级到 2.0 的最佳准备方式是先把项目更新到最新的 PHPStan 1.12 版本并开启Bleeding Edge。Bleeding Edge 是一组在 2.0 中面向所有用户默认开启的新规则与行为在 1.12 上提前启用可以让你在升级前就暴露并修复绝大多数问题。同时务必安装并启用phpstan/phpstan-deprecation-rules。这条规则会报告代码中对已废弃 API 的使用是后续平滑升级的关键前置条件。阶段二在最新 1.12.x 上达到零弃用告警当你开启 Bleeding Edge 后在最新的 PHPStan 1.12.x 上跑出全绿构建green build且不再显示任何废弃告警时就可以在composer.json中将所有相关 PHPStan 依赖统一更新到 2.0require-dev: { phpstan/phpstan: ^2.0, phpstan/phpstan-deprecation-rules: ^2.0, phpstan/phpstan-doctrine: ^2.0, phpstan/phpstan-nette: ^2.0, phpstan/phpstan-phpunit: ^2.0, phpstan/phpstan-strict-rules: ^2.0, phpstan/phpstan-symfony: ^2.0, phpstan/phpstan-webmozart-assert: ^2.0, ... }注意别忘了同步更新所有 第三方 PHPStan 扩展它们的 2.0 兼容版本同样需要一起升级。修改composer.json之后运行如下命令完成依赖更新composer update phpstan/* -W-W即--with-all-dependencies会连同间接依赖一起更新确保所有 PHPStan 相关包处于一致的 2.x 版本线上。阶段三处理新报告的错误或直接纳入 baseline更新完成后面对新版本报告出来的错误你有两种处理方式可以按团队节奏选择逐条修复逐个审查 2.0 新报告的错误并修复代码纳入 baseline把全部新错误一次性写入 baseline之后再逐步清理。官方文档的结论是所有处于 PHPStan 1.12 的项目都应该能够顺利升级到 PHPStan 2.0。代码分析行为的重要变化升级到 2.0 后即使你的配置一字未改以下分析行为也会发生变化需要提前知晓增强对引用传递参数parameters passed by reference的处理对$param这类按引用传递参数的推断更加精细校验内联 PHPDocvar标签的类型代码中的/** var Foo $x */内联注解现在会被真正校验标注与实际类型不符会直接报错强制启用 List 类型list语义在 2.0 中面向所有用户默认开启详见下文List 类型对所有人启用一节true条件始终上报恒为true的条件表达式如if (1 1)此前仅在开启 phpstan-strict-rules 时才报告现在始终报告不再依赖 strict-rules 开关。三、已移除的配置项与替代方案终端用户必看PHPStan 2.0 移除了一批旧配置项。下面按官方文档逐项说明其去向并给出可直接复制使用的替代配置。3.1 移除checkMissingIterableValueType该选项用于控制是否检查数组缺失的元素值类型标注2.0 中已被移除。官方强烈建议为数组补充缺失的类型标注如param arrayint, Foo。如果暂时想继续忽略数组缺失类型标注的问题需要在ignoreErrors中加入对应的错误标识符missingType.iterableValueparameters: ignoreErrors: - identifier: missingType.iterableValue3.2 移除checkGenericClassInNonGenericObjectType该选项控制是否检查在非泛型对象类型中使用泛型类的问题2.0 中已移除。官方同样强烈建议补齐缺失的泛型类型标注。若想继续忽略则加入标识符missingType.genericsparameters: ignoreErrors: - identifier: missingType.generics3.3 移除checkAlwaysTrue*系列选项以下四个选项在 2.0 中被整体移除因为 PHPStan 现在始终表现得如同它们被设置为truecheckAlwaysTrueCheckTypeFunctionCallcheckAlwaysTrueInstanceofcheckAlwaysTrueStrictComparisoncheckAlwaysTrueLooseComparison也就是说包含is_*函数调用、instanceof、严格比较与宽松比较的恒真条件现在一律上报相关配置项直接删除即可。3.4 移除excludes_analyseexcludes_analyse已被excludePaths取代。注意两个选项的语义差异excludes_analyse排除的是分析路径不分析这些文件而excludePaths既包含分析排除analyse键也包含结果排除analyseAndScan、scan键。迁移时请对照官方ignoring errors文档重新组织配置。3.5excludePaths与ignoreErrors的路径规则变化2.0 中excludePaths和ignoreErrors里的路径必须是有效的文件路径或 fnmatch 模式。这是最容易踩坑的变化如果某个要排除的路径当前可能不存在例如生成目录、CI 才创建的目录需要在路径后追加(?)标记为可选路径parameters: excludePaths: - tests/*/data/* - src/broken - node_modules (?) # optional path, might not exist如果在ignoreErrors中也有类似需求忽略某个可能不存在的路径上的错误不能使用(?)后缀ignoreErrors不支持该写法而是设置reportUnmatchedIgnoredErrors: falseparameters: reportUnmatchedIgnoredErrors: false3.6 其他已移除的未使用配置参数以下参数与开关在 2.0 中被直接删除官方确认它们此前已无实际用途已移除项类型说明cache.nodesByFileCountMax配置参数已无实际用途直接删除memoryLimitFile配置参数已无实际用途直接删除disableRuntimeReflectionProvider功能开关已无实际用途直接删除staticReflectionClassNamePatterns配置参数已无实际用途直接删除fixerTmpDir配置参数改用pro.tmpDirtempResultCachePath配置参数改用resultCachePathadditionalConfigFiles配置参数必须改为列表list形式其中additionalConfigFiles的变化尤其需要注意1.x 时代可以传单个字符串2.0 起强制要求传入列表。四、第一方扩展的配置变更如果你使用了 PHPStan 官方第一方扩展以下参数迁移必须同步处理。phpstan-doctrine移除配置参数searchOtherMethodsForQueryBuilderBeginning扩展现在始终表现得如同该参数被设置为true直接删除即可移除配置参数queryBuilderFastAlgorithm扩展现在始终表现得如同该参数被设置为false直接删除即可。phpstan-symfony移除所有名称中带下划线_的旧式选项统一改为驼峰命名container_xml_path→ 使用containerXmlPathconstant_hassers→ 使用constantHassersconsole_application_loader→ 使用consoleApplicationLoader五、面向扩展开发者的迁移指南如果你维护的是 PHPStan 扩展、自定义规则或相关工具2.0 的迁移工作量大得多。官方文档给出的总体策略是请在新的大版本major version中切换到 PHPStan 2.0。试图用同一份扩展代码同时支持 PHPStan 1.x 和 2.x 并不可行。你可以在不提升大版本号的前提下通过用 PHPStan phpstan-deprecation-rules Bleeding Edge 分析自己的扩展代码、解决报告的废弃与问题来逼近对 2.0 的支持但最终的跨越——解决向后兼容问题——必须通过在composer.json中要求phpstan/phpstan: ^2.0并发布新的大版本来完成。5.1 PHPStan 现在使用 nikic/php-parser v5PHPStan 2.0 底层 AST 解析器升级到 nikic/php-parser v5。最显著的变化是throw语句的 AST 表示方式此前throw $e;这样的语句用Stmt\Throw_类表示而出现在其他表达式内部如$x ?? throw $e的 throw 用Expr\Throw_类表示现在throw $e;被表示为一个包含Expr\Throw_的Stmt\ExpressionStmt\Throw_类已被删除。任何遍历或改写 AST 的自定义规则都必须适配这一变化。完整迁移细节可参考 PHP-Parser 官方 5.0 升级指南。5.2 PHPStan 现在使用 phpstan/phpdoc-parser v2PHPDoc 解析器同样升级到 v2 大版本。如果你直接依赖了 PHPDoc 解析产物例如解析var、param注解的结构需要对照 phpstan/phpdoc-parser 的 2.0 升级指南检查 API 变化。5.3 返回纯字符串作为错误不再受支持必须使用 RuleErrorBuilder自定义规则中返回[My error]这种纯字符串数组的写法在 2.0 中被移除错误标识符identifier也成为强制要求。标识符不仅用于错误归类还直接服务于ignoreErrors按identifier精确忽略参见上文 3.1、3.2 两节。升级前Beforereturn [My error];升级后Afterreturn [ RuleErrorBuilder::message(My error) -identifier(my.error) -build(), ];5.4 废弃各种instanceof *Type改用Type接口上的新方法在 2.0 中通过$type instanceof ArrayType这类方式判断类型对象的具体类正在被废弃。官方推荐在Type接口上直接调用语义化方法如Type::isConstantValue()、Type::getArrays()、Type::getObjectClassNames()等而不是用instanceof探测具体实现类。这也与下文ConstantArrayType不再继承ArrayType的变化相互呼应。5.5 移除已废弃的ParametersAcceptorSelector::selectSingle()selectSingle()已被移除应改用ParametersAcceptorSelector::selectFromArgs()。它应该在绝大多数此前使用selectSingle()的场景如动态返回类型扩展中替代前者。升级前Before$defaultReturnType ParametersAcceptorSelector::selectSingle($functionReflection-getVariants())-getReturnType();升级后After$defaultReturnType ParametersAcceptorSelector::selectFromArgs( $scope, $functionCall-getArgs(), $functionReflection-getVariants() )-getReturnType();另外如果你是在分析函数或方法体本身并且此前通过以下节点/作用域对象调用selectSingle()现在可以直接在反射对象上调用getParameters()与getReturnType()InClassMethodNode::getMethodReflection()InFunctionNode::getFunctionReflection()FunctionReturnStatementsNode::getFunctionReflection()MethodReturnStatementsNode::getMethodReflection()Scope::getFunction()升级前Before$function $node-getFunctionReflection(); $returnType ParametersAcceptorSelector::selectSingle($function-getVariants())-getReturnType();升级后After$returnType $node-getFunctionReflection()-getReturnType();5.6TypeSpecifier::create()与SpecifiedTypes构造参数变化PHPStan\Analyser\TypeSpecifier::create()现在只接受四个全部必填的参数Expr $exprType $typeTypeSpecifierContext $contextScope $scope此前的$overwrite与$rootExpr参数不再由create()接收。如果仍需设置它们请在create()返回的SpecifiedTypes对象上调用setAlwaysOverwriteTypes()和setRootExpr()——这两个方法返回新对象SpecifiedTypes是不可变的。SpecifiedTypes的构造函数同样收紧了签名现在只接受array $sureTypesarray $sureNotTypes如需设置$overwrite或$rootExpr同样调用setAlwaysOverwriteTypes()与setRootExpr()且注意每次调用都返回新的不可变对象。此外TypeSpecifier::specifyTypesInCondition()不再接受Expr $rootExpr参数需要时同样在返回的SpecifiedTypes上调用setRootExpr()。5.7ConstantArrayType不再继承ArrayType这是一个影响面较广的类型层级变化Type::getArrays()现在的返回类型是listArrayType|ConstantArrayType。由于instanceof ArrayType本身已在被废弃之列见 5.4这一变化对绝大多数扩展的实际影响有限但在类型判断逻辑中需要注意不要假设ConstantArrayType一定是ArrayType的实例。5.8 Node 属性parent、previous、next不再可用PHPStan 2.0 不再提供 AST 节点的parent、previous、next属性。此前依赖这些属性在 AST 中回溯或前/后查找的规则需要重构官方博客有专门文章讲解新的 AST 预处理方式。5.9 移除配置参数scopeClass自定义Scope类的入口被移除。替代方案是实现PHPStan\Type\ExpressionTypeResolverExtension接口并将其注册为服务以此参与表达式类型的解析。5.10 移除PHPStan\Broker\BrokerBroker类及其相关 API 在 2.0 中全部移除统一改用PHPStan\Reflection\ReflectionProviderBroker→ 使用ReflectionProviderBrokerAwareExtension同样被移除在扩展构造函数中直接请求注入ReflectionProvider即可测试基类中PHPStanTestCase::createBroker()→ 调用PHPStanTestCase::createReflectionProvider()。5.11 List 类型对所有人启用2.0 中 list 类型连续整数键、从 0 开始的数组类型面向所有用户默认启用。AccessoryArrayListType类的以下静态方法被移除isListTypeEnabled()setListTypeEnabled()intersectWith()原来的AccessoryArrayListType::intersectWith($type)需要改写为TypeCombinator::intersect($type, new AccessoryArrayListType())5.12 扩展开发者的其他向后兼容性破坏汇总以下变更不逐一展开代码示例但升级时务必逐条对照类与接口变更此前标记为final的类在 2.0 中真正变为finalPHPStan\Node\ClassMethod从ClassMethodsNode访问不再是 AST 节点需要调用PHPStan\Node\ClassMethod::getNode()获取原始 AST 节点ConstantReflection系列改名类ClassConstantReflection更名为RealClassConstantReflection接口ConstantReflection更名为ClassConstantReflection接口GlobalConstantReflection更名为ConstantReflection*WithPhpDocs系列改名ParametersAcceptorWithPhpDocs→ExtendedParametersAcceptorParameterReflectionWithPhpDocs→ExtendedParameterReflectionFunctionVariantWithPhpDocs→ExtendedFunctionVariant移除ConstantType接口改用Type::isConstantValue()ClassPropertyNode::getNativeType()返回类型从 AST 节点改为Type|nullType::getProperty()现在返回ExtendedPropertyReflection。签名与返回类型变化MutatingScope::enterAnonymousFunction()与enterArrowFunction()的参数$callableParameters变为必填NodeScopeResolver::processStmtNodes()的参数StatementContext $context变为必填ClassPropertiesNode::getUninitializedProperties()移除$extensions参数Type::getSmallerType()等四个比较方法以及CompoundType::isGreaterThan()、isGreaterThanOrEqual()现在要求传入PhpVersion参数ConstantArrayType构造函数的$isList参数只能是TrinaryLogic不再接受bool$nextAutoIndexes参数只能是non-empty-listint不再接受intFunctionReflection、ExtendedMethodReflection、CallableParametersAcceptor的acceptsNamedArguments()返回TrinaryLogic而非boolType::accepts()/isSuperTypeOf()等方法的返回类型从TrinaryLogic改为结果对象AcceptsResult、IsSuperTypeOfResultRuleLevelHelper::accepts()返回类型从bool改为RuleLevelHelperAcceptsResult移除了Type::acceptsWithReason()、CompoundType::isAcceptedWithReasonBy()、Type::isSuperTypeOfWithReason()等带WithReason的方法。方法移除与重命名移除ReflectionProvider::supportsAnonymousClasses()所有反射提供器现在都支持匿名类ArrayType移除generalizeKeys()count()改用Type::getArraySize()castToArrayKeyType()改用Type::toArrayKey()UnionType::pickTypes()改用pickFromTypes()RegexArrayShapeMatcher::matchType()改用matchExpr()PHPStanTestCase移除$useStaticReflectionProvider属性与getReflectors()改用getReflector()ClassReflection::getFileNameWithPhpDocs()改用getFileName()AnalysisResult::getInternalErrors()改用getInternalErrorObjects()ConstantReflection::getValue()改用getValueExpr()需要Type时用Scope::getType()或InitializerExprTypeResolver::getType()PropertyTag::getType()改用getReadableType()/getWritableType()移除GenericTypeVariableResolver改用Type::getTemplateType()Type::isClassStringType()改名为Type::isClassString()Scope::isSpecified()改用hasExpressionType()ConstantArrayType移除isEmpty()改用isIterableAtLeastOnce()-no()、getNextAutoIndex()、generalizeToArray()、findTypeAndMethodName()改用findTypeAndMethodNames()、removeLast()改用Type::popArray()、removeFirst()改用Type::shiftArray()、reverse()改用Type::reverseArray()、chunk()改用Type::chunkArray()、slice()改用Type::sliceArray()、getFirst*Type/getLast*Type改用getFirstIterable*Type/getLastIterable*Type移除Scope::doNotTreatPhpDocTypesAsCertain()改用getNativeType()移除FunctionReflection::isFinal()移除TypehintHelper::decideTypeFromReflection()的string类型的$selfClass参数LevelsTestCase::dataTopics()数据提供器改为 staticPHPStan\Node\Printer\Printer不再以PhpParser\PrettyPrinter\Standard别名自动装配类型提示中请直接使用PHPStan\Node\Printer\Printer移除本不应被序列化进缓存的对象的__set_state()。TypeUtils瘦身TypeUtils中大量便捷方法被移除统一迁移到Type接口getArrays()/getAnyArrays()→Type::getArrays()getConstantArrays()/getOldConstantArrays()→Type::getConstantArrays()getConstantStrings()→Type::getConstantStrings()getConstantTypes()/getAnyConstantTypes()→Type::isConstantValue()或Type::generalize()generalizeType()→Type::generalize()getDirectClassNames()→Type::getObjectClassNames()getConstantScalars()→Type::isConstantScalarValue()或Type::getConstantScalarTypes()getEnumCaseObjects()→Type::getEnumCases()containsCallable()→Type::isCallable()六、仓库实践object-enumerator 的 PHPStan 2.x 配置全览作为本指南的落地案例object-enumerator 仓库本身就是一次完整的 PHPStan 2.x 实践可以直接对照学习。6.1 依赖版本仓库在 tools/.phpstan/composer.json 中声明了开发期静态分析依赖{ require-dev: { phpstan/phpstan: ^2.3.1, phpstan/extension-installer: ^1.4.3, phpstan/phpstan-strict-rules: ^2.1.0, ergebnis/phpstan-rules: ^2.14.0 }, config: { allow-plugins: { phpstan/extension-installer: true } } }注意这里正是升级文档建议的2.0 全家桶形态phpstan/phpstan主包与phpstan/phpstan-strict-rules均为^2.x同时通过phpstan/extension-installer自动注册第三方扩展规则对应文档中别忘了更新第三方扩展的建议。实际锁定的 PHPStan 版本为 2.3.1。6.2 配置文件中的 2.0 特性印证仓库根目录的 phpstan.neon 展示了多个 2.0 时代的典型用法parameters: level: 10 paths: - src - tests/unit checkTooWideReturnTypesInProtectedAndPublicMethods: true reportAlwaysTrueInLastCondition: true reportPossiblyNonexistentConstantArrayOffset: true treatPhpDocTypesAsCertain: false strictRules: allRules: false booleansInConditions: true ... includes: - phar://phpstan.phar/conf/bleedingEdge.neonBleeding Edge 常态化includes中直接引入了phar://phpstan.phar/conf/bleedingEdge.neon对应仓库内 tools/.phpstan/vendor/phpstan/phpstan/conf/bleedingEdge.neon。在 1.x 时代这只是升级前的预备开关而在 2.x 中它已成为项目常态配置——这正是文档所述2.0 将 Bleeding Edge 的规则与行为对所有人开启的体现strict-rules 细分控制strictRules块以allRules: false起步、逐条开启如disallowedLooseComparison: true、disallowedShortTernary: true印证了 2.0 中扩展规则可被细粒度配置的能力ergebnis 规则接入ergebnis块开启了final与privateInFinalClass规则对应 vendor 中 ergebnis/phpstan-rules 的实现属于典型的第三方扩展在 2.x 生态中协同工作的例子reportAlwaysTrueInLastCondition等 2.0 风格参数与文档中恒真条件始终上报的变化方向一致。6.3 静态分析守护的核心实现被 PHPStan 分析的核心代码位于 src/Enumerator.phpEnumerator::enumerate()接收array|object借助sebastian/recursion-context的Context记录已处理对象递归遍历数组与对象图返回listobject。配套的单测 tests/unit/EnumeratorTest.php 覆盖了循环引用、数组自引用、私有/受保护/继承属性、PHP 8.4 属性钩子hooked property、惰性对象lazy ghost/proxy见 tests/_fixture/ClassWithLazyObject.php 系列 fixture等边界场景。整个src与tests/unit都被纳入paths接受 level 10 的最高强度检查——这也是值得照搬的核心实现 测试代码同标准分析实践。七、升级检查清单最后把全文要点浓缩为一份可直接对照执行的清单确认运行环境 PHP ≥ 7.4升级到最新 PHPStan 1.12.x开启 Bleeding Edge安装phpstan/phpstan-deprecation-rules在 1.12.x 上修到零废弃告警的全绿构建将composer.json中所有phpstan/*依赖改为^2.0运行composer update phpstan/* -W删除已移除的配置项checkMissingIterableValueType、checkGenericClassInNonGenericObjectType、checkAlwaysTrue*、excludes_analyse、cache.nodesByFileCountMax、memoryLimitFile、fixerTmpDir、tempResultCachePath等按上文对应替代方案迁移检查excludePaths/ignoreErrors路径写法必要时追加(?)或设置reportUnmatchedIgnoredErrors: false如使用官方扩展按第四节迁移 doctrine/symfony 参数扩展开发者按第五节逐条适配php-parser v5、phpdoc-parser v2、RuleErrorBuilder identifier、selectFromArgs()、Type接口方法、ReflectionProvider、SpecifiedTypes不可变 API 等处理新报告的错误或整体写入 baseline 后逐步清理。赞分享开发工具【免费下载链接】object-enumeratorTraverses array structures and object graphs to enumerate all referenced objects项目地址https://gitcode.com/gh_mirrors/ob/object-enumerator点击查看免费下载相关推荐PHPStan 1.x 升级到 2.0 完整迁移指南配置变更、API 重构与扩展开发适配PHPStan 1.x 升级到 2.0 完整迁移指南配置变更、API 重构与扩展开发适配 本文以 PHPStan 2.2.16 自带的 UPGRADING.m测试代码质量PHPStan 2.0 升级全指南从 1.x 平滑迁移的配置变更与扩展开发适配PHPStan 2.0 升级全指南从 1.x 平滑迁移的配置变更与扩展开发适配 PHPStan 2.0 是 PHP 静态分析工具的一次大版本跃迁它把过去只在开发工具后端PHPStan 2.0 升级全指南从 1.x 平滑迁移的配置修改与扩展开发适配PHPStan 2.0 升级全指南从 1.x 平滑迁移的配置修改与扩展开发适配 本文以仓库内 tools/.phpstan/vendor/phpstan/ph开发工具测试上一篇如何优化ESP-IDF中APSTA模式下的WiFi连接状态日志分析下一篇Marlin Configurations版本管理详解从2.0到2.1.x的升级路径创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考