PHP stream_filter_append 处理大文件换行：过滤器链、资源关闭与内存检查

处理几百 MB 的访问日志时，先用 file_get_contents() 把文件整段读进来，内存峰值很快就会超过脚本限制。更稳妥的做法是让 PHP 流在读取过程中完成换行规范化：用 stream_filter_append() 把过滤器挂到资源上，再按行消费数据。这样既能保持流式处理，也能把过滤器是否生效变成可检查的证据。

先把大文件问题缩小到流读取链

假设输入文件可能同时包含 Unix 换行和 Windows 换行，目标是输出统一的行记录。这里不需要把整个文件复制成新字符串，读取链可以按块接收数据，过滤器在数据经过时做转换。

先准备一个最小测试文件，故意放入两种换行：

这段代码先验证“资源能否打开”和“逐行读取能否结束”。它没有改变输入内容，也没有证明过滤器已经工作，所以不要把它当作最终验收。

把换行转换放进 stream_filter_append

PHP 自带的 string.strip_tags、convert.* 等过滤器适用于明确的转换场景。换行规范化通常更适合使用自定义过滤器，因为它能同时处理块边界：一个 \r 可能出现在本次读取的末尾，而 \n 在下一块开头。

下面的过滤器把 CRLF 和孤立的 CR 都转换成 LF。过滤器类只改变传入桶中的内容，不负责打开或关闭文件。

data = str_replace(["\r\n", "\r"], "\n", $bucket->data);
            $consumed += $bucket->datalen;
            stream_bucket_append($out, $bucket);
        }

        return PSFS_PASS_ON;
    }
}

stream_filter_register('app.normalize_lines', NormalizeLineEndings::class);
$handle = fopen(__DIR__ . '/access.log', 'rb');
if ($handle === false) {
    throw new RuntimeException('无法打开日志文件');
}

try {
    $filter = stream_filter_append($handle, 'app.normalize_lines', STREAM_FILTER_READ);
    if ($filter === false) {
        throw new RuntimeException('换行过滤器注册失败');
    }

    while (($line = fgets($handle)) !== false) {
        echo rtrim($line, "\n") . PHP_EOL;
    }
} finally {
    fclose($handle);
}

这里最容易漏掉的是返回值检查。stream_filter_append() 返回过滤器资源，失败时是 false；如果忽略这个返回值，后面的 fgets() 仍可能正常读完文件，但内容并没有经过预期转换。

用证据判断过滤器是否真的生效

调试时不要只看“脚本没有报错”。可以记录读取行数、规范化后的换行计数和内存峰值，形成一条很短的验收链：

如果文件总大小是 800 MB，而脚本的峰值只比单行最大长度多出少量缓冲，说明处理路径仍然是流式的。这个指标比单纯打印“处理完成”更有区分度。

过滤器链里最常见的三个误区

把过滤器方向写成写入

本文是读取文件，所以方向应为 STREAM_FILTER_READ。写成 STREAM_FILTER_WRITE 不会自动作用于 fgets() 读出的数据，排查时先对齐数据流方向。

在过滤器里依赖完整的一行

过滤器拿到的是桶，不保证每个桶就是一整行。不要在过滤器中根据桶边界解析业务字段；需要按行判断时，把换行转换留在过滤器，把业务解析放到 fgets() 之后。

只在成功路径关闭句柄

文件打开成功后，过滤器注册、读取和业务解析都可能抛出异常。finally 是稳定的收口位置，既能覆盖正常结束，也能覆盖中途失败。

把示例改成可复查的小型命令

实际项目中可以把行数和内存峰值写到日志中，便于和旧实现对比：

$count = 0;
$startMemory = memory_get_usage(true);
$peakBefore = memory_get_peak_usage(true);

while (($line = fgets($handle)) !== false) {
    $count++;
    // 在这里解析一行，不要保存所有行。
}

$peakAfter = memory_get_peak_usage(true);
printf("lines=%d peak_delta=%d bytes%n", $count, $peakAfter - max($peakBefore, $startMemory));

验收时至少准备一个空文件、一个只有一行的文件、包含 CRLF 的文件，以及一份超过内存限制数倍的大文件。小文件验证结果正确，大文件验证峰值没有随文件总量线性上涨，两者缺一不可。

相关问题

stream_filter_append 注册失败怎么办？

先检查过滤器名称是否已经通过 stream_filter_register() 注册，再确认传入的是有效流资源和正确方向；不要先怀疑文件内容。

过滤器会替代 fclose 吗？

不会。过滤器只参与数据转换，资源生命周期仍由打开流的代码负责，建议把 fclose() 放在 finally 中。

大文件一定要使用自定义过滤器吗？

不一定。如果只是逐行读取，直接使用 fgets() 就够了；只有在读取链上确实需要统一编码、换行或其他转换时，才增加过滤器。

最后的检查清单

• 打开文件后立即检查句柄是否为 false。
• 注册过滤器后检查返回值，并确认读写方向。
• 用 fgets 逐行消费，避免 file_get_contents 或一次性数组化。
• 在 finally 中关闭资源，再用行数、尾部状态和内存峰值复查。