PHPStan Strict Rules 之 if.condNotBoolean：强制 if 条件必须是布尔值-平芜编程栈

开发工具
代码质量
静态分析

【免费下载链接】phpstan

PHP Static Analysis Tool - discover bugs in your code without running it!

项目地址：https://gitcode.com/gh_mirrors/ph/phpstan

导读

if.condNotBoolean是 PHPStan 严格规则（phpstan/phpstan-strict-rules）家族中用于守护条件表达式的一个错误标识符：当if语句的条件不是布尔类型、而是依赖 PHP 隐式 truthy/falsy 强制转换时，PHPStan 会报告该错误。本文基于仓库中 if.condNotBoolean.md 的官方错误标识符文档展开，结合仓库内错误标识符映射、e2e 配置等源码证据，完整讲解其触发场景、背后原理、修复方法与实际启用方式。读完本文，你将能准确理解并修复这类"隐式布尔转换"问题，写出意图更明确的静态分析友好代码。

什么是 if.condNotBoolean

if.condNotBoolean是 PHPStan 报告的一类错误标识符，shortDescription（简短描述）为："Non-boolean type is used in an if condition instead of an explicit comparison."（在if条件中使用了非布尔类型，而非显式比较表达式）。

从仓库中的错误标识符注册表 website/src/errorsIdentifiers.json 可以看到，该标识符由PHPStan\Rules\BooleansInConditions\BooleanInIfConditionRule规则产出，该规则来自phpstan/phpstan-strict-rules扩展包，而不是 PHPStan 核心本身。换言之，只有当你显式启用了 strict rules 扩展时，PHPStan 才会报告这类错误。

触发示例：完整复现

原文档给出了一个最小化、可直接运行的触发示例（来自官方文档 if.condNotBoolean.md）：

<?php declare(strict_types = 1); function greet(string $name): string { if ($name) { // error: Only booleans are allowed in an if condition, string given. return "Hello, $name!"; } return 'Hello, stranger!'; }

$name的类型是string，直接放入if条件中，PHPStan（在 strict rules 下）会报告：

Only booleans are allowed in an if condition, string given.

注意，这与if.alwaysFalse/if.alwaysTrue不同：后两者是 PHPStan 核心在条件恒真/恒假时给出的死代码提示（参见同类文档 if.alwaysFalse.md）；而if.condNotBoolean关注的是条件类型本身是否为布尔，即便该条件可能随运行时输入变化，只要类型不是bool就会被报告。

为什么会被报告：PHP 的隐式 truthy/falsy 转换

原文档从 PHP 语言语义角度解释了根因，这也是官方文档目录约定（见 website/errors/CLAUDE.md）要求的"解释 PHP 语言语义，而非 PHPStan 内部机制"：

PHP 在求值条件表达式时会执行隐式类型强制转换（implicit type coercion）。0、''（空字符串）、'0'（字符串零）、[]（空数组）和null都被视为 falsy，而同类型的其他值视为 truthy。
这种隐式转换会掩盖 bug。最典型的陷阱是字符串'0'是 falsy 的——一个来自表单或外部输入的用户名/ID，如果其值恰好是字符串"0"，if ($value)会错误地走进 else 分支，而这很可能不是开发者期望的行为。

结合同族文档 while.condNotBoolean.md 的表述可以确认，同一规则家族将0、''、'0'、[]、null均列为 falsy 值，并强调"依赖条件中的隐式类型转换会让代码难以推理"。

因此，要求条件使用显式布尔表达式，是为了让代码意图更清晰，并避免由 truthy/falsy 强制转换引起的细微错误。这正是 strict rules 扩展的设计哲学：不满足于"类型正确"，而是强制开发者写出意图明确、无歧义的代码。

如何修复：显式布尔比较

原文档给出的修复方案是使用返回布尔值的显式比较：

<?php declare(strict_types = 1); function greet(string $name): string { - if ($name) { + if ($name !== '') { return "Hello, $name!"; } return 'Hello, stranger!'; }

对于可空类型，应显式与null比较：

<?php declare(strict_types = 1); function process(?array $items): int { if ($items !== null) { return count($items); } return 0; }

同样的修复思路适用于整个条件家族。例如while循环既可以用显式比较，也可以显式强转(bool)来表达意图（见 while.condNotBoolean.md）：

$someString = 'hello'; -while ($someString) { +while ($someString !== '') { $someString = ''; }

或：

$someString = 'hello'; -while ($someString) { +while ((bool) $someString) { $someString = ''; }

修复优先级参考

参考官方文档目录的写作约定（website/errors/CLAUDE.md），官方推荐的修复优先级是：

修复真正的 bug（例如把条件改成对业务字段的显式比较）；
使用原生 PHP 类型声明收窄类型；
使用PHPDoc 类型（@param、@return、属性上的@var）收窄类型；
在函数体内使用类型收窄手段；
若规则可配置，再考虑调整 PHPStan 配置。

对if.condNotBoolean而言，最常见、最直接的修复就是第 1 步——把条件改写为显式比较表达式。注意官方文档明确不建议通过assert()、抛异常、内联@var或直接忽略错误来绕过（该标识符的详细页本身就提供了ignorable: true的忽略机制，属于另一主题）。

规则来源与实现佐证

仓库中的错误标识符注册表 website/src/errorsIdentifiers.json 明确记录了if.condNotBoolean的归属：

错误标识符	规则类	所属包
`if.condNotBoolean`	`PHPStan\Rules\BooleansInConditions\BooleanInIfConditionRule`	`phpstan/phpstan-strict-rules`

也就是说，该规则类位于phpstan-strict-rules包的src/Rules/BooleansInConditions/命名空间下，与while.condNotBoolean、doWhile.condNotBoolean、elseif.condNotBoolean、ternary.condNotBoolean属于同一规则家族（BooleansInConditions，即"条件中的布尔值"）。

完整的条件家族标识符

在 website/errors 目录下，与if.condNotBoolean同族的文档还包括：

while.condNotBoolean.md ——while循环条件非布尔
doWhile.condNotBoolean.md ——do...while循环条件非布尔
elseif.condNotBoolean.md ——elseif条件非布尔
ternary.condNotBoolean.md —— 三元运算符条件非布尔
以及booleanAnd.*NotBoolean、booleanOr.*NotBoolean、logicalAnd.*NotBoolean、logicalOr.*NotBoolean、booleanNot.exprNotBoolean等逻辑运算相关标识符

它们共享同一套规则类BooleanIn*Rule，触发与修复逻辑一致：只要某个条件位（condition position）上出现了非布尔类型，就会触发对应标识符。因此，本文的修复方法论可以无缝迁移到while、elseif、ternary等场景。

如何在项目中启用该规则

由于if.condNotBoolean由phpstan/phpstan-strict-rules提供，默认的 PHPStan 核心不会报告它。启用步骤如下：

安装扩展包（需使用 Composer，在项目根目录执行）：
```
composer require --dev phpstan/phpstan-strict-rules
```
在 PHPStan 配置中引入规则。仓库内的 e2e 测试配置 e2e/phpstan.neon 给出了实际可用的引入方式：
```
includes: - vendor/phpstan/phpstan-strict-rules/rules.neon
```
将该includes块加入你的phpstan.neon（或phpstan.neon.dist）即可启用整套 strict rules，其中就包括BooleanInIfConditionRule。
运行 PHPStan：
```
vendor/bin/phpstan analyse src --level max
```
启用后，所有if/while/do...while/elseif/ternary条件中的非布尔表达式都会被报告为对应标识符的错误。

仓库的 e2e 集成测试（如 e2e/integration 下各 composer.lock）大量依赖phpstan/phpstan-strict-rules（版本约束如^1.6 || ^2.0、^2等），说明该扩展是 PHPStan 生态中广泛使用的官方补充规则集，可以与 Laravel、Rector、Symfony 等各类项目的 PHPStan 配置协同工作。

常见误用与避坑建议

'0'陷阱：字符串'0'在 PHP 中是 falsy，但它是合法的非空字符串。若业务上"用户输入了'0'"应当视为有效值，if ($input)就会产生错误的控制流。这正是 strict rules 强制显式比较的核心动机。
可空类型：?array、?string等可空类型放入条件时，应显式写!== null，让"是否为 null"的语义一目了然。
不要用assert()绕过：官方文档明确禁止用assert()或抛异常来收窄类型，这会引入运行时副作用，且不符合静态分析意图。
区分同类错误：if.alwaysFalse/if.alwaysTrue属于"恒真恒假"死代码检查（核心规则），if.condNotBoolean属于"非布尔条件"检查（strict rules）。两者可以同时启用、互补工作。

总结

if.condNotBoolean是phpstan/phpstan-strict-rules中BooleansInConditions规则家族的核心成员，用于强制if条件必须是布尔表达式，杜绝依赖 PHP 隐式 truthy/falsy 转换带来的细微 bug。修复方式始终是"显式化"：用!== ''、!== null等布尔比较替代裸变量条件，必要时用(bool)显式强转表明意图。通过 website/src/errorsIdentifiers.json 可以追溯其规则归属，通过 e2e/phpstan.neon 可以复现其启用方式——掌握这一标识符，你的 PHP 代码将兼具可读性与可分析性。