ShowDoc 依赖的代码行数统计库 sebastian/lines-of-code:实现原理与版本演进全解析

原创2026-09-22 22:36:581,988 阅读
文章标签:后端文档知识管理

ShowDoc 依赖的代码行数统计库 sebastian/lines-of-code:实现原理与版本演进全解析

导读

sebastian/lines-of-code 是 PHP 单元测试生态中的一个小型统计组件,专门用于从 PHP 源码中精确统计物理代码行数、注释行数与逻辑代码行数。它随 PHPUnit 的代码覆盖率组件 phpunit/php-code-coverage 被引入 ShowDoc 项目,位于 server/vendor/sebastian/lines-of-code,当前锁定版本为 1.0.4。本文以其 ChangeLog.md 为骨架,完整梳理 1.0.0 到 1.0.4 的每一次变更,并结合仓库内真实源码剖析每条变更背后的实现细节,帮助读者既读懂版本历史,也理解"代码行数"这一指标在 AST 层面的统计原理。

一、库的定位:一个为覆盖率工具服务的行数计数器

在 ShowDoc 的 composer.lock 中可以看到,sebastian/lines-of-code 1.0.4 由 phpunit/php-code-coverage 以 "^1.0.4" 的版本约束间接引入(见 composer.lock 中 php-code-coverage 的 require 列表)。它自身不依赖 PHPUnit 主框架,而是作为覆盖率报告中的数据来源之一:当统计"被测代码的规模"时,需要知道代码总量(LOC)、其中注释占多少(CLOC)、非注释占多少(NCLOC)以及真正构成逻辑分支的行数(LLOC)。

组件本身结构极简,src 下只有三个核心类:

  • Counter.php:对外入口,负责把源码文件或源码字符串交给 nikic/php-parser 解析,再驱动访问器统计;
  • LineCountingVisitor.php:NodeTraverser 的访问器,逐节点收集注释与表达式所在行;
  • LinesOfCode.php:不可变结果对象,承载四类行数指标。

此外还有三个异常类(NegativeValueException、IllogicalValuesException、RuntimeException),统一实现 Exception.php 接口,用于约束结果对象的合法性与解析失败时的错误上抛。

二、四个核心指标:LOC / CLOC / NCLOC / LLOC

LinesOfCode 结果对象对外提供四个只读方法,含义如下:

指标 方法 含义
LOC linesOfCode() 源码文件的物理总行数
CLOC commentLinesOfCode() 注释行数
NCLOC nonCommentLinesOfCode() 非注释行数,恒等于 LOC - CLOC
LLOC logicalLinesOfCode() 逻辑代码行数,即至少包含一个表达式(Expr 节点)的起始行数,去重后计数

从 LinesOfCode.php 的构造函数可以看到两条硬性校验规则:

  1. 四个参数均不允许为负数,否则抛出 NegativeValueException(继承自 InvalidArgumentException);
  2. 必须满足恒等式 linesOfCode - commentLinesOfCode === nonCommentLinesOfCode,否则抛出 IllogicalValuesException(继承自 LogicException)。

结果对象被 @psalm-immutable 注解标记,并提供一个 plus() 方法,用于把多个文件的统计结果累加为目录或项目级的汇总值——这也解释了为什么它在覆盖率聚合场景中能够被反复合并而不会产生副作用。

三、版本演进全记录:1.0.0 至 1.0.4

以下内容完整继承自 ChangeLog.md,该文件遵循 Keep a CHANGELOG 的维护惯例(按时间倒序列出所有值得记录的变更,并标注类型为 Fixed / Changed 等)。

1.0.4(2023-12-22)——兼容 php-parser 5.0

变更内容:组件开始兼容 nikic/php-parser 5.0。

源码验证:composer.json 中的依赖声明为 "nikic/php-parser": "^4.18 || ^5.0",即同时允许 4.18+ 与 5.x 两个大版本。这一放宽意味着库本身只使用 php-parser 的稳定公共 API——从 Counter.php 看,它只用到了 ParserFactory->createForHostVersion()->parse()、NodeTraverser 与 Node / Expr 类型判断,这些接口在 5.0 中保持稳定,因此无需改动统计逻辑即可双版本兼容。对 ShowDoc 这类使用老式 ThinkPHP 栈、同时又要升级工具链的项目而言,这条兼容性保障是"依赖升级不炸"的关键前提。

1.0.3(2020-11-28)——两项关键修正

Fixed:不含换行符的文件处理错误

此前,若一个源码文件内容非空但末尾没有换行符,物理行数会被错误地统计为 0。修复后 Counter.php 中 countInSourceString() 的处理逻辑为:

$linesOfCode = substr_count($source, "\n");

if ($linesOfCode === 0 && !empty($source)) {
    $linesOfCode = 1;
}

即以换行符数量估算物理行数,同时对"非空但无换行符"的退化情况兜底为 1 行。这一修正保证了单行文件(无结尾换行)也能得到正确的 LOC 基数,后续所有指标都建立在这个基数之上。

Changed:不含 Expr 节点的行不再计为逻辑代码行

LLOC 的定义从"出现语句的行"收紧为"出现表达式(Expr 节点)的行"。对应的实现位于 LineCountingVisitor.php 的 enterNode():

public function enterNode(Node $node): void
{
    $this->comments = array_merge($this->comments, $node->getComments());

    if (!$node instanceof Expr) {
        return;
    }

    $this->linesWithStatements[] = $node->getStartLine();
}

只有 Expr 类型的节点才会把起始行号记入 linesWithStatements,最终 LLOC 通过 count(array_unique($this->linesWithStatements)) 去重得到。这意味着 use 导入语句、纯声明性质的节点等不含表达式的行不会虚增"逻辑代码行",使 LLOC 更贴近"真正承载计算逻辑"的行数,这也是 1.0.3 被称为行为变更(Changed)而非单纯修 bug 的原因。

1.0.2(2020-10-26)——异常层级修正

Fixed:SebastianBergmann\LinesOfCode\Exception 现在正确继承 \Throwable。

在 Exception.php 中可以看到接口声明:

interface Exception extends Throwable
{
}

Throwable 是 PHP 7 引入的统一异常/错误基接口,\Exception 与 \Error 都实现它。此前该接口若不显式继承 Throwable,则库内自定义异常无法被通用的 catch (Throwable $e) 捕获,也无法与 Error 统一处理。修复后,库中的三类异常(见 src/Exception)都通过 implements Exception 间接成为 Throwable 家族成员,保证了在 try/catch 与日志体系中的可捕获性。

1.0.1(2020-09-28)——放宽 PHP 版本约束

Changed:composer.json 中的 PHP 版本约束从 ^7.3 || ^8.0 调整为 >=7.3。

仓库中的 composer.json 当前声明为 "php": ">=7.3"。放宽后的语义是:任何高于 7.3 的 PHP 版本(包括尚未发布的 8.x 后续版本)在安装阶段都不会被 Composer 拒绝,避免因版本上限过于刚性而在未来 PHP 版本上产生不必要的安装失败。对 ShowDoc 这类部署环境差异较大的开源项目而言,依赖的约束越宽松,PHP 7.3+ 各版本环境下的 composer install 越不容易因版本校验而中断。

1.0.0(2020-07-22)——初始发布

首个正式版本发布,标志着行数统计 API(Counter、LinesOfCode、LineCountingVisitor)与异常体系的设计定型。此后的 1.0.x 系列均保持向后兼容,未出现破坏性接口变更。

四、统计流水线:从源码到四类行数的完整链路

综合 Counter.php 与 LineCountingVisitor.php,一次完整的统计分为四步:

  1. 读取:countInSourceFile() 读取文件内容,或直接调用 countInSourceString() 传入源码字符串;
  2. 估算物理行:以 substr_count($source, "\n") 计算换行符数量作为 LOC 基数,并对无换行符的非空内容兜底为 1;
  3. 语法解析:通过 (new ParserFactory)->createForHostVersion()->parse($source) 将源码解析为抽象语法树(AST);若语法错误,抛出 RuntimeException 并携带底层解析错误信息;
  4. 遍历统计:NodeTraverser 携带 LineCountingVisitor 遍历 AST,收集所有注释的起止行(CLOC 累加 getEndLine() - getStartLine() + 1,并通过起止行与 token 位置拼接的 key 去重,避免同一注释被多个节点重复收集),同时记录所有 Expr 节点的起始行。

最终在 result() 中组装:NCLOC = LOC - CLOC,LLOC = count(array_unique(表达式起始行))。可以看到,CLOC 与 LLOC 两条统计路径相互独立:注释行来自注释节点本身,逻辑行来自表达式节点,这保证了 1.0.3 之后"注释密集但逻辑稀疏"的代码也能得到符合直觉的统计结果。

五、在 ShowDoc 中的安装与使用前提

该库作为 phpunit/php-code-coverage 的传递依赖随 Composer 安装,无需手动声明。若需要在自己的 PHP 项目中单独引入,可参考其 README.md:

composer require sebastian/lines-of-code

如果仅用于开发期测试,则推荐作为开发期依赖:

composer require --dev sebastian/lines-of-code

使用前提(依据当前仓库 composer.json):

  • PHP 版本不低于 7.3(约束为 >=7.3);
  • 依赖 nikic/php-parser 4.18+ 或 5.0;
  • 开发期使用 PHPUnit 9.3+ 运行测试;
  • 采用 classmap 自动加载方式("autoload": { "classmap": ["src/"] }),无需额外维护 PSR-4 映射。

典型调用方式为:

use SebastianBergmann\LinesOfCode\Counter;

$result = (new Counter)->countInSourceFile('path/to/file.php');

$result->linesOfCode();           // 物理总行数
$result->commentLinesOfCode();    // 注释行数
$result->nonCommentLinesOfCode(); // 非注释行数
$result->logicalLinesOfCode();    // 逻辑代码行数

六、小结:一个"小而稳"的统计组件的演进启示

回顾 ChangeLog.md 记录的五个版本,可以看到一个工具库在成熟期前后的典型轨迹:1.0.0 定型 API,1.0.1 放宽安装约束,1.0.2 修正异常层级以融入现代 PHP 的错误体系,1.0.3 修复边界输入并重新定义 LLOC 语义,1.0.4 拥抱 php-parser 5.0 保持生态同步。每一次变更都能在 src 的对应实现中找到直接落点——这正是阅读变更日志的正确方式:不仅知道"改了什么",更知道"为什么这样改、改在代码的哪一行"。

对于 ShowDoc 的开发者而言,理解这一依赖的价值在于:当覆盖率报告中出现 LOC 与 LLOC 数据时,可以准确解释其口径差异(物理行 vs 含表达式行),也能在升级 PHPUnit / php-code-coverage 时预判该库的兼容边界(PHP >= 7.3、php-parser 4.18+ 或 5.0),从而避免盲升级带来的统计口径漂移。

登录后查看全文
showdoc