开发工具后端【免费下载链接】environmentProvides functionality that helps writing PHP code that has runtime-specific execution paths项目地址https://gitcode.com/gh_mirrors/en/environment点击查看免费下载PHPStan 2.0 是 PHP 静态分析工具的一次大版本跃迁它把过去只在 Bleeding Edge 模式下启用的新规则、新行为全面铺开并移除了大量旧配置项与旧 API。本文以 PHPStan 官方仓库中的 UPGRADING.md 为核心骨架逐条拆解最终用户与扩展开发者需要面对的迁移点并结合本仓库sebastian/environment一个探测 PHP/HHVM 运行时环境的开源组件中真实的 phpstan.neon 与tools/.phpstan/vendor/phpstan/依赖布局演示 2.0 配置在实践中长什么样。读完本文你将掌握升级前的准备步骤、被移除配置项的官方替代写法、ignoreErrors标识符与excludePaths的新语法以及扩展开发所需的所有破坏性 API 变更清单。一、PHP 版本要求PHPStan 2.0 的最低门槛根据 UPGRADING.md 的明确说明PHPStan 2.0 自身运行要求PHP 7.4 或更新版本。这意味着即使你被分析的代码面向的是更老的 PHP 版本运行 PHPStan 2.0 的这台机器或 CI 环境也必须至少具备 PHP 7.4。注意这是运行 PHPStan的要求与被分析项目的运行时 PHP 版本无关——后者由 PHPStan 的phpVersion参数控制。二、最终用户升级指南三步走到 2.02.1 第一步先升到最新 PHPStan 1.12 并开启 Bleeding Edge官方升级指南 给出的核心策略是不要直接跳到 2.0而是先升到最新的 PHPStan 1.12 release并开启Bleeding Edge。Bleeding Edge 是 PHPStan 的预览通道2.0 会对所有用户强制开启的新规则和新行为在 1.12 中可以通过该开关提前启用从而让你在 1.x 时代就把未来要面对的报错全部暴露出来。在本仓库中这一机制有直接对应物根目录的 phpstan.neon 末尾以includes形式引用了phar://phpstan.phar/conf/bleedingEdge.neon。也就是说本项目已经以 Bleeding Edge 方式运行 PHPStan这正是 UPGRADING.md 推荐的升级前姿态。同时项目通过 tools/phpstan 这个 Composer 生成的代理脚本调用phpstan.phar并额外安装了phpstan-strict-rules等扩展见tools/.phpstan/vendor/phpstan/目录与官方建议的在最新 1.12.x 上把构建跑到全绿的工作流一致。2.2 第二步安装并启用 deprecation-rules升级前还必须安装并启用phpstan/phpstan-deprecation-rules文档原文。这个扩展会把你代码中所有即将在 2.0 失效的旧 API 用法标记为弃用错误是提前扫雷的关键工具。2.3 第三步升级 composer.json 并更新依赖当你基于最新 PHPStan 1.12.x Bleeding Edge 无任何弃用警告拿到全绿构建后就可以在composer.json中把相关依赖统一抬到 2.0。官方给出的完整require-dev模板如下原文档原文require-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让 Composer 允许同时升级依赖链中的相关包避免新旧版本混装。官方特别强调任何处于 PHPStan 1.12 的项目都应该能够升级到 2.0。至于升级后新冒出来的报错你可以逐条消化也可以干脆全部丢进 baseline基线文件两者都被官方认可。三、代码分析行为的四大显著变化升级到 2.0 后即使配置不变分析结果也会因为引擎行为变化而产生差异。官方在 Noteworthy changes to code analysis 中列出了四项按引用传递参数的处理增强function foo($bar)这类场景下的类型推导与检查逻辑被重做分析更精确。内联 PHPDocvar标签类型会被校验/** var string */ $x ...;中标注的类型如果与实际推导类型矛盾2.0 会报错不再盲目采信。List 类型被强制listT索引连续、从 0 开始语义在类型系统中被更严格地贯彻数组类型的推导会区分list与普通数组。恒为true的条件始终报告之前只有开启phpstan-strict-rules才会报告的条件恒真问题2.0 中默认一律报告。四、被移除的配置项与官方替代写法这一节是最终用户迁移的重头戏。多个旧参数被删除官方给出的替代方案全部是把旧行为收窄到ignoreErrors的错误标识符identifier。4.1checkMissingIterableValueType→missingType.iterableValue旧参数checkMissingIterableValueType被移除。官方强烈建议为数组补齐元素类型标注typehint。如果你暂时想继续忽略数组缺元素类型的报错就在ignoreErrors中按错误标识符屏蔽原文档示例parameters: ignoreErrors: - identifier: missingType.iterableValue4.2checkGenericClassInNonGenericObjectType→missingType.generics同理旧参数checkGenericClassInNonGenericObjectType被移除官方强烈建议为泛型类补齐类型参数。想继续忽略时使用原文档示例parameters: ignoreErrors: - identifier: missingType.generics注意这里与 4.1 的语法一致identifier精确匹配错误标识符只有该标识符对应的错误被屏蔽其余错误不受影响——这正是 2.0 推荐用标识符取代整条错误消息正则的原因。4.3checkAlwaysTrue*系列行为被固化以下四个选项被整体移除因为 2.0 中它们的语义恒等于true原文档列表checkAlwaysTrueCheckTypeFunctionCallcheckAlwaysTrueInstanceofcheckAlwaysTrueStrictComparisoncheckAlwaysTrueLooseComparison也就是说instanceof恒真严格比较恒真等场景现在是默认检查项配置里不需要也再无法显式开启。4.4excludes_analyse→excludePaths旧参数excludes_analyse被删除统一由excludePaths承担原文档说明。如果你的配置还在写excludes_analyse迁移时直接改名为excludePaths即可语义等价。4.5excludePaths/ignoreErrors的路径规则收紧这是最容易踩坑的破坏性变更excludePaths和ignoreErrors中的路径必须是一个真实存在的文件路径或一个 fnmatch 通配模式原文档说明。如果你的排除路径当前可能不存在、但希望保留在配置里就给该条目追加(?)后缀parameters: excludePaths: - tests/*/data/* - src/broken - node_modules (?) # optional path, might not exist(?)意为可选路径可能不存在PHPStan 不会因为该路径缺失而报未匹配警告。ignoreErrors中的情况则不同不支持(?)后缀。如果你要在ignoreErrors里忽略某个可能不存在的路径下的错误请改用全局开关reportUnmatchedIgnoredErrors: falseparameters: reportUnmatchedIgnoredErrors: false五、第一方扩展的配置变更如果你使用了 PHPStan 官方生态的扩展2.0 一并收紧了它们的配置参数原文档列表phpstan-doctrine移除searchOtherMethodsForQueryBuilderBeginning扩展现在恒等于该值被设为true的行为移除queryBuilderFastAlgorithm扩展现在恒等于该值被设为false的行为。phpstan-symfony移除所有带下划线的旧选项名统一改为驼峰式container_xml_path→containerXmlPathconstant_hassers→constantHassersconsole_application_loader→consoleApplicationLoader六、最终用户视角的次要向后不兼容变更以下配置参数在 2.0 中被清理原文档清单迁移时如果配置里还在使用需要逐一处理被移除/变更项处理方式cache.nodesByFileCountMax删除从未生效的未用参数memoryLimitFile删除未用参数disableRuntimeReflectionProvider功能开关删除未用staticReflectionClassNamePatterns删除未用参数fixerTmpDir改用pro.tmpDirtempResultCachePath改用resultCachePathadditionalConfigFiles必须是 list数组类型七、扩展开发者升级指南如果你维护 PHPStan 扩展自定义规则、动态返回类型扩展、类型扩展等请先接受官方的一条强烈建议原文档 NOTE在扩展的下一个主版本中切换到 PHPStan 2.0不要试图用同一份扩展代码同时兼容 1.x 与 2.x。比较现实的做法是先在现有主版本内用PHPStan phpstan-deprecation-rules Bleeding Edge分析你自己的扩展代码解决所有弃用告警尽量逼近 2.0 兼容最终一步在composer.json中改为phpstan/phpstan: ^2.0并发布新的主版本。7.1 底层依赖双升级php-parser v5 与 phpdoc-parser v2PHPStan 2.0 将 AST 解析器升级为nikic/php-parser v5。最值得注意的表示变化是throw语句原文档说明旧版独立语句throw $e;用Stmt\Throw_节点表示表达式内如$x ?? throw $e用Expr\Throw_。新版Stmt\Throw_类被删除throw $e;现在是一个包含Expr\Throw_的Stmt\Expression。如果你的自定义规则通过遍历 AST 识别 throw 语句必须按新结构重写 visitor 逻辑。同时 PHPDoc 解析层升级为phpstan/phpdoc-parser v2凡是直接依赖 PHPDoc AST 的扩展都要重新编译/适配。7.2 自定义规则字符串错误不再被支持必须用 RuleErrorBuilder2.0 中自定义规则直接返回纯字符串数组作为错误的写法被移除且错误必须携带identifier原文档说明。之前不再支持return [My error];之后推荐return [ RuleErrorBuilder::message(My error) -identifier(my.error) -build(), ];标识符命名空间惯例是厂商名.错误名如上例my.error它让用户能够像第 4 节那样通过ignoreErrors.identifier精确屏蔽错误也能让错误被 PHPStan 更好地聚合与解释。7.3 弃用instanceof *Type改用Type接口方法官方明确反对在自定义扩展中通过$type instanceof XxxType判断类型理由是这无法处理UnionType等复合类型。2.0 中这种写法被正式弃用应改用Type接口上的方法如Type::getArrays()、Type::isConstantValue()、Type::isCallable()等这些方法内部已经处理了联合类型展开。7.4ParametersAcceptorSelector::selectSingle()被移除动态返回类型扩展中常用的selectSingle()被删除应改用selectFromArgs()它能结合调用点的实参和$scope选出更精确的变体原文档示例$defaultReturnType ParametersAcceptorSelector::selectFromArgs( $scope, $functionCall-getArgs(), $functionReflection-getVariants() )-getReturnType();而如果你正在分析函数/方法体本身不要再用selectFromArgs()而是直接从反射对象上取getParameters()和getReturnType()。适用于以下节点类型InClassMethodNode::getMethodReflection()InFunctionNode::getFunctionReflection()FunctionReturnStatementsNode::getFunctionReflection()MethodReturnStatementsNode::getMethodReflection()Scope::getFunction()之前$function $node-getFunctionReflection(); $returnType ParametersAcceptorSelector::selectSingle($function-getVariants())-getReturnType();之后$returnType $node-getFunctionReflection()-getReturnType();7.5TypeSpecifier::create()与SpecifiedTypes构造参数变更TypeSpecifier::create()现在只接受四个必填参数原文档说明Expr $exprType $typeTypeSpecifierContext $contextScope $scope之前通过create()设置的$overwrite与$rootExpr改为在返回的SpecifiedTypes对象上调用setAlwaysOverwriteTypes()与setRootExpr()。注意SpecifiedTypes是不可变对象这两个 setter 返回的是新实例。SpecifiedTypes构造函数同样收紧现在只接受array $sureTypesarray $sureNotTypes7.6ConstantArrayType不再继承ArrayType类型层级发生了结构性变化ConstantArrayType不再是ArrayType的子类原文档说明。Type::getArrays()现在返回listArrayType|ConstantArrayType。由于instanceof ArrayType本身已被弃用见 7.3这一变更的实际冲击有限——正确做法是改用Type::getArrays()后逐个区分。7.7TypeSpecifier::specifyTypesInCondition()移除$rootExpr该方法不再接受Expr $rootExpr参数。需要修改根表达式时对返回的SpecifiedTypes调用setRootExpr()同样返回新对象。7.8 AST 节点属性parent/previous/next被移除2.0 中AST 节点上的parent、previous、next三个属性不再可用。如果你的自定义规则依赖它们回溯 AST 结构需要改用 PHPStan 提供的替代机制预处理后的节点包装。7.9 移除scopeClass配置参数自定义 Scope 类的方式被废弃。官方替代方案是实现PHPStan\Type\ExpressionTypeResolverExtension接口并注册为服务在扩展中为表达式提供类型解析逻辑。7.10 移除PHPStan\Broker\Broker老牌入口Broker被移除统一使用PHPStan\Reflection\ReflectionProvider原文档说明BrokerAwareExtension一并删除——在扩展构造函数中直接请求ReflectionProvider测试侧PHPStanTestCase::createBroker()改为PHPStanTestCase::createReflectionProvider()。7.11 List 类型对所有人启用AccessoryArrayListType的以下静态方法被移除原文档说明isListTypeEnabled()setListTypeEnabled()intersectWith()原来的AccessoryArrayListType::intersectWith($type)写法改为TypeCombinator::intersect($type, new AccessoryArrayListType())7.12 其他扩展开发相关的破坏性变更清单以下是 UPGRADING.md 中剩余的全部次要 BC 破坏按主题归纳类与接口层级原标记final的类在 2.0 中真正变成final。ConstantType接口被移除改用Type::isConstantValue()。类常量反射重构ClassConstantReflection更名为RealClassConstantReflectionConstantReflection接口更名/新设为ClassConstantReflectionGlobalConstantReflection更名为ConstantReflection。*WithPhpDocs系列接口全面更名为Extended*ParametersAcceptorWithPhpDocs→ExtendedParametersAcceptor、ParameterReflectionWithPhpDocs→ExtendedParameterReflection、FunctionVariantWithPhpDocs→ExtendedFunctionVariant。PHPStan\Node\ClassMethod不再是 AST 节点需调用getNode()取回原始 AST 节点。PHPStan\Node\Printer\Printer不再自动注入为PhpParser\PrettyPrinter\Standard类型提示中必须使用PHPStan\Node\Printer\Printer。方法签名与必填参数MutatingScope::enterAnonymousFunction()与enterArrowFunction()的参数$callableParameters变为必填。NodeScopeResolver::processStmtNodes()的参数StatementContext $context变为必填。TypehintHelper::decideTypeFromReflection()的$selfClass不再接受string。ClassPropertyNode::getNativeType()返回类型从 AST 节点改为Type|null。Type::getProperty()现在返回ExtendedPropertyReflection。FunctionReflection::isFinal()被移除。类型系统方法迁移大小比较类方法要求显式传入PhpVersionType::getSmallerType()、getSmallerOrEqualType()、getGreaterType()、getGreaterOrEqualType()、isSmallerThan()、isSmallerThanOrEqual()CompoundType::isGreaterThan()、isGreaterThanOrEqual()同理。Type::isClassStringType()更名为Type::isClassString()。ConstantArrayType构造参数收紧$isList只能传TrinaryLogic不再接受bool$nextAutoIndexes只能传non-empty-listint不再接受int。ArrayType移除generalizeKeys()、count()改用Type::getArraySize()、castToArrayKeyType()改用Type::toArrayKey()。ConstantArrayType移除isEmpty()改用isIterableAtLeastOnce()-no()、getNextAutoIndex()、generalizeToArray()、removeLast()/removeFirst()/reverse()/chunk()/slice()分别改用Type::popArray()、shiftArray()、reverseArray()、chunkArray()、sliceArray()、findTypeAndMethodName()改用findTypeAndMethodNames()。Type::accepts()与CompoundType::isAcceptedBy()返回类型从TrinaryLogic改为AcceptsResultType::isSuperTypeOf()、CompoundType::isSubTypeOf()、TemplateType::isValidVariance()返回IsSuperTypeOfResult。RuleLevelHelper::accepts()返回类型从bool改为RuleLevelHelperAcceptsResult。Scope::isSpecified()移除改用hasExpressionType()Scope::doNotTreatPhpDocTypesAsCertain()移除改用getNativeType()。UnionType::pickTypes()移除改用pickFromTypes()。GenericTypeVariableResolver移除改用Type::getTemplateType()。ReflectionProvider::supportsAnonymousClasses()移除所有反射提供器都支持匿名类。acceptsNamedArguments()在FunctionReflection、ExtendedMethodReflection、CallableParametersAcceptor中返回TrinaryLogic而非bool。不应被缓存序列化的对象上移除__set_state()。TypeUtils 瘦身TypeUtils的大量静态方法被移除全部迁移到Type接口方法移除的 TypeUtils 方法替代方法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()反射相关方法迁移ClassReflection::getFileNameWithPhpDocs()→getFileName()。AnalysisResult::getInternalErrors()→getInternalErrorObjects()。ConstantReflection::getValue()→getValueExpr()从Expr取Type用Scope::getType()或InitializerExprTypeResolver::getType()。PropertyTag::getType()→getReadableType()/getWritableType()。RegexArrayShapeMatcher::matchType()→matchExpr()。PHPStanTestCase::$useStaticReflectionProvider移除getReflectors()改为getReflector()。LevelsTestCase::dataTopics()数据提供者改为 static。八、结合本仓库2.0 时代配置的实战场最后看看 phpstan.neon 这份真实存在于本仓库的配置它是 2.0 风格配置的活样本parameters: level: 10 paths: - src - tests checkTooWideReturnTypesInProtectedAndPublicMethods: true reportAlwaysTrueInLastCondition: true reportPossiblyNonexistentConstantArrayOffset: true reportPossiblyNonexistentGeneralArrayOffset: true treatPhpDocTypesAsCertain: false strictRules: allRules: false booleansInConditions: true closureUsesThis: true disallowedBacktick: true disallowedEmpty: true disallowedImplicitArrayCreation: true disallowedLooseComparison: true disallowedShortTernary: true illegalConstructorMethodCall: true matchingInheritedMethodNames: true noVariableVariables: true numericOperandsInArithmeticOperators: true overwriteVariablesWithLoop: true requireParentConstructorCall: true strictArrayFilter: true strictFunctionCalls: true switchConditionsMatchingType: true uselessCast: true ergebnis: allRules: false final: enabled: true classesNotRequiredToBeAbstractOrFinal: privateInFinalClass: enabled: true includes: - phar://phpstan.phar/conf/bleedingEdge.neon几点值得注意reportAlwaysTrueInLastCondition等选项的存在正对应第 3 节恒真条件在 2.0 中被固化为默认行为的方向——这类配置在 2.0 中会被并入默认检查。includes直接加载bleedingEdge.neon与本仓库 vendor 目录下同时安装的phpstan-strict-rules见tools/.phpstan/vendor/phpstan/phpstan-strict-rules/共同构成高严格度检查链。treatPhpDocTypesAsCertain: false与 2.0内联var标签类型将被校验的新行为相呼应PHPDoc 不再是说什么信什么必须与实际推导一致。被分析对象src/与tests/如 src/Runtime.php、src/Console.php、tests/RuntimeTest.php本身就是大量使用运行时探测 API 的代码其 CI 中运行 PHPStan level 10从实践侧验证了升级路径的可行性。升级到 2.0 的总体心法可以概括为先在 1.12 Bleeding Edge 下把所有新行为剧透一遍并处理干净再切换依赖版本配置层面把旧参数翻译成ignoreErrors标识符与新命名扩展层面按本文 7.12 的清单逐项改 API 并发布新主版本。遵循这条路径从 1.x 到 2.0 的迁移是可控、可回退、可逐步验证的。赞分享开发工具后端【免费下载链接】environmentProvides functionality that helps writing PHP code that has runtime-specific execution paths项目地址https://gitcode.com/gh_mirrors/en/environment点击查看免费下载相关推荐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 平滑迁移到新主版本附配置与扩展开发完整变更清单 本篇指南以仓库根目录 UPGRADING.md https开发工具代码质量静态分析Base UI 开源项目教程Base UI 开源项目教程 1. 项目介绍 Base UI 是一个由 Radix、Floating UI 和 Material UI 的创造者们开发的未样式化开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考