PHP-CS-Fixer modernize_types_casting 规则详解：将 intval/strval 等函数调用统一转换为类型强制转换

• 开发工具
• 代码质量
• 静态分析
• Lint
• 格式化

导读

modernize_types_casting是 PHP-CS-Fixer 中@PhpCsFixer:risky与@Symfony:risky规则集内置的一条 risky 规则，其核心职责是把intval、floatval、doubleval、strval、boolval这五个"类型转换辅助函数"的调用，自动改写为等价的 PHP 原生类型转换运算符(int)、(float)、(string)、(bool)。阅读本文后，你将掌握该规则的确切转换行为、Risky 标记背后的风险边界、底层 Token 级实现原理（含优先级、边界场景与安全防护），以及如何在配置文件中启用它与规避误伤。

规则定位与核心功能

一句话定义

依据 官方规则文档，本规则执行如下替换：

Replacesintval,floatval,doubleval,strvalandboolvalfunction calls with according type casting operator.

即把"以函数形式完成的类型转换"替换为"语言内置的强制转换运算符"。二者的运行时语义在默认参数下完全等价，但强制转换写法更短、更快、也更符合现代 PHP 的编码习惯。

完整的转换映射表

转换关系在 ModernizeTypesCastingFixer.php 中以一张映射表硬编码定义：

注意两点细节：其一，doubleval与floatval在 PHP 中本就是double/float的别名关系，因此二者统一转换为(float)；其二，函数调用与强制转换对多字节字符串以外的参数语义一致，这是本规则成立的前提。

官方示例

文档给出了标准转换示例（官方规则文档）：

--- Original +++ New <?php - $a = intval($b); - $a = floatval($b); - $a = doubleval($b); - $a = strval ($b); - $a = boolval($b); + $a = (int) $b; + $a = (float) $b; + $a = (float) $b; + $a = (string) $b; + $a = (bool) $b;

示例中strval ($b)（函数名与左括号之间存在空格）同样会被规范化，转换结果自动带上运算符与操作数之间的单个空格，即(string) $b。

Risky 标记：为什么这条规则被列为 risky

风险来源

该规则被官方标记为RISKY，文档中的 Warning 说明如下：

Risky if any of the functionsintval,floatval,doubleval,strvalorboolvalare overridden.

也就是说：如果用户代码中覆盖（重定义）了这些函数，规则就会产生语义破坏。PHP 允许在命名空间内自定义与内置函数同名的函数，一旦代码中use function引入或自定义了同名函数，原本的函数调用语义（可能带有自定义逻辑、额外的基数参数等）会被无差别改写为强制转换，导致行为改变。

测试如何印证风险场景

ModernizeTypesCastingFixerTest.php 专门用一个"覆盖intval"的用例说明风险：在类方法中调用未加反斜杠的intval(...)会被替换为(int) (...)，而这正是规则 risky 属性的来源——它无法静态判断当前作用域里是否有人重定义了同名函数：

<?php class overridesIntval { public function intval($x) { return \intval($x); } public function usesInval() { // that's why it is risky return intval(mt_rand(0, 100)); // 会被改写为 (int) (mt_rand(0, 100)); } }

规避策略

启用 risky 规则前，请确认项目中不存在以下情况：

• 未使用\前缀、以命名空间形式自定义的intval/floatval/doubleval/strval/boolval函数；
• 通过use function intval;等语句将自定义函数导入当前命名空间；
• 依赖intval第二个参数$base（进制）等附加参数的调用——这类调用不会被本规则转换（见下文"不做转换的边界场景"），但混用会带来不一致性。

从源码结构看，规则本身也通过FunctionsAnalyzer::isGlobalFunctionCall()尽量排除"明确不是全局函数调用"的情况，例如$object->intval(...)、ClassA::intval(...)、ScopeA\intval(...)均不会被改写（详见 AbstractFunctionReferenceFixer.php 与对应测试用例），但"确实被覆盖的全局函数调用"无法在静态层面完全排除，这正是 risky 的根本原因。

精确的转换边界：哪些会改、哪些绝对不改

规则的行为边界由测试套件 ModernizeTypesCastingFixerTest.php 完整锁定，每个测试用例都是向后兼容承诺的一部分（原文档 References 一节明确说明）。以下边界均来自测试数据提供器provideFixCases。

会被转换的场景

1. 单参数调用：intval($x)→(int) $x，五种函数各自对应转换。
2. 带命名空间前缀的根级调用：\intval(mt_rand(0, 100))→(int) (mt_rand(0, 100))，规则会主动移除多余的\。
3. 参数是复合表达式：strval($b . $c)→(string) ($b . $c)，此时保留内层括号以保证运算优先级。
4. 嵌套调用：strval(intval(intval($x) + floatval($x)))→(string) ((int) ((int) $x + (float) $x))，支持递归式的嵌套转换。
5. 参数后的尾随逗号：intval($b, )、intval($b , )→(int) $b，尾随逗号会被清理。
6. 结果被下标访问或求幂：
   • strval($x)[0]→((string) $x)[0]；
   • intval($x)**2→((int) $x)**2； 此时额外加一层括号，避免(string)$x[0]的解析歧义。
7. 多行/带注释的复杂写法：形如函数名与括号分离多行、参数区散布注释的写法也能正确处理，注释位置被保留（如/**/intval/**/ /** x*/(...)的用例）。

明确不做转换的场景

1. 多参数调用：intval($x, 16)、intval($x, $options["base"])保持原样——因为(int)无法表达"按指定进制转换"的语义。
2. 零参数或超过一个参数：intval(); intval(1,2,3);原样保留。
3. 非全局函数调用：$object->intval(...)、ClassA::intval(...)、ScopeA\intval(...)、namespace\intval(...)、new \intval(...)、new intval(...)、new ScopeB\intval(...)均不动。
4. 同名标识符的其他用途：字符串里的"intval"、拼接串"test" . "intval"、变量赋值$x = "intval"、前缀函数intvalSmth(...)、smth_intval(...)均不受影响。
5. 接口方法声明：interface Test { public function floatval($a); }这类方法定义不会被误改。
6. PHP 8.1 起的一等可调用语法：intval(...)保持原样（见provideFix81Cases，要求 PHP >= 8.1）。

与规则集及其他规则的配合

所属规则集

原文档明确列出该规则属于以下两个规则集（对应源码见 SymfonyRiskySet.php 与 PhpCsFixerRiskySet.php）：

• @PhpCsFixer:risky（见 PhpCsFixerRisky.rst）：该规则集继承@PER-CS:risky与@Symfony:risky，因此本规则随@Symfony:risky一并启用；
• @Symfony:risky（见 SymfonyRisky.rst）。

这意味着日常使用中，你通常不需要手动声明这一条，只要启用了上述两个 risky 规则集之一即可生效。

执行优先级

ModernizeTypesCastingFixer的getPriority()返回31，并在注释中声明"必须运行在 NoUnneededControlParenthesesFixer 之前"（源码）。优先级数值越大越先执行，先完成强制转换后，后续规则再去清理可能多余的括号，从而保证最终输出既简洁又不破坏语义。

配置示例

在.php-cs-fixer.dist.php中手动启用：

<?php return (new PhpCsFixer\Config()) ->setRules([ // 单独启用（需自行评估 risky 风险） 'modernize_types_casting' => true, // 或者直接引入包含它的规则集 // '@Symfony:risky' => true, // '@PhpCsFixer:risky' => true, ]) ->setFinder(PhpCsFixer\Finder::create()->in(__DIR__));

由于该规则无任何可配置选项（true/false即全部配置），用法非常简洁。

底层实现原理：Token 级别的三步走

从源码层面拆解 ModernizeTypesCastingFixer.php 的applyFix()，可以看到一次转换由三个关键步骤组成。

第一步：借助 AbstractFunctionReferenceFixer 定位函数调用

本 Fixer 继承自AbstractFunctionReferenceFixer（源码），其find()方法先通过Tokens::findSequence()匹配[T_STRING, 函数名] + '('的原始 Token 序列，再用FunctionsAnalyzer::isGlobalFunctionCall()判断该标识符是否确实是全局函数调用；只有通过该判断的候选者才会返回[函数名Token索引, 左括号索引, 右括号索引]三元组。这正是上面"类方法、命名空间函数、方法调用不被误改"的机制来源。

第二步：参数分析决定括号去留

拿到边界后，Fixer 使用ArgumentsAnalyzer::countArguments()统计参数个数：参数个数不等于 1 的调用直接跳过（这也解释了intval($x, 16)不被转换）。随后通过统计左括号与右括号之间"有意义的 Token 数量"决定是否保留参数外层的括号：

• 参数是单一简单变量（如$x）：删除函数名与括号，直接输出(int) $x；
• 参数是复合表达式（如$b . $c、mt_rand(0, 100)）：保留括号，输出(int) (mt_rand(0, 100))。

同时，若函数调用结果紧跟[、{或幂运算符**（见 源码），还会在转换后的表达式外加一层括号，防止优先级歧义——这正是测试中strval($x)[0]→((string) $x)[0]的来源。

第三步：Token 替换与清理

最后，Fixer 用[新Token, 空格Token]的序列覆盖原函数名 Token（$tokens->overrideRange()），并清理残留的括号与首尾空白；如果检测到根命名空间分隔符\（T_NS_SEPARATOR）也会一并移除。find()返回后把游标移回函数名位置继续循环，从而实现嵌套调用的递归转换（测试中strval(intval(...))的用例即由此保证）。

实战建议与注意事项

1. 先跑 dry-run 再落地：由于是 risky 规则，建议先用php-cs-fixer fix --dry-run --diff查看将被改写的文件清单，重点排查是否存在自定义的同名函数。
2. 警惕多参数调用：intval($x, 16)不会被转换，如果你的代码里这类调用与单参数调用混存，转换后风格会不统一，可结合no_alias_functions等规则统一决策。
3. 兼容性说明：规则对 PHP 8.1 的一等可调用语法（intval(...)）做了显式豁免（见provideFix81Cases）；而{0}形式的字符串偏移写法仅存在于 PHP 8.0 之前，对应行为由provideFixPre80Cases覆盖，当前版本项目按现代 PHP 处理即可。
4. 语义等价性：在未覆盖内置函数的项目中，转换前后结果一致，(int)等运算符还略快于函数调用开销，属于"风格 + 微性能"双收益的改动。

参考资源

• 规则官方文档：doc/rules/cast_notation/modernize_types_casting.rst
• Fixer 实现类：src/Fixer/CastNotation/ModernizeTypesCastingFixer.php
• 测试类（向后兼容承诺载体）：tests/Fixer/CastNotation/ModernizeTypesCastingFixerTest.php
• 基类实现：src/AbstractFunctionReferenceFixer.php
• 所属规则集：doc/ruleSets/SymfonyRisky.rst、doc/ruleSets/PhpCsFixerRisky.rst

• 开发工具
• 代码质量
• 静态分析
• Lint
• 格式化