PHP stream_filter 链式转换的读取方法

PHP 读取文件时，如果要先做 Base64 解码、再做大小写转换，或者先完成字符转换再交给业务代码处理，可以把多个 stream filter 串成一条读取链。关键不是把过滤器名称写在一起，而是明确过滤方向、链顺序和资源打开时机：php://filter 适合在打开资源时声明静态链，stream_filter_append() 和 stream_filter_prepend() 适合对已打开的流动态调整。

官方文档：https://www.php.net/manual/en/stream.filters.php

先分清读取链和写入链

过滤器是附着在流上的数据处理环节。以读取文件为例，数据从资源进入 PHP 后会经过读取链；写入文件时则经过写入链。同一个过滤器名称放在不同方向，结果可能完全相反，所以第一步要根据调用场景选择 STREAM_FILTER_READ 或 STREAM_FILTER_WRITE。

例如，下面的代码把一段 Base64 文本当作输入，只在读取时解码。这里的 convert.base64-decode 是示例过滤器，实际可用名称仍应以当前运行环境返回的过滤器列表为准。

用 php://filter 声明静态链

当过滤器在打开资源前就已经确定时，php://filter 写法更紧凑。resource= 必须指向实际资源，read= 后面可以放一个或多个过滤器，过滤器之间用竖线分隔。下面的例子先解码，再把结果转成大写，重点是让链顺序直接出现在资源路径中。

不要把这段路径理解成“两个过滤器同时执行”。它表达的是一条有顺序的链：前一个过滤器的输出会成为后一个过滤器的输入。转换不可交换时，顺序就是结果的一部分，例如先解码再转大写，和先对 Base64 字符串转大写不是同一个操作。

动态追加时，append 和 prepend 不是同义词

动态处理的常见故障是“过滤器都挂上了，但输出顺序不对”。stream_filter_append() 会把过滤器放在当前链的末尾；stream_filter_prepend() 则放在开头。因此，当文本需要先去除某类标记、再做编码转换时，要把先做的那一环放到链首，而不是机械地连续调用 append。

');
if ($first === false) {
    fclose($stream);
    throw new RuntimeException('标签过滤器不可用');
}

$result = stream_get_contents($stream);
fclose($stream); // 即使读取结果为空，也要关闭流。
echo $result;

这段示例只展示链的组织方式。实际项目中应确认过滤器参数格式符合当前 PHP 版本，并注意读取缓冲区：官方手册说明，流中已经取入内部缓冲区的数据，在追加过滤器时会被送入新过滤器，而前置过滤器对已有缓冲数据的处理时机不同。需要严格控制边界时，应在打开流后尽早完成链配置。

读取异常时按三层证据排查

如果输出为空、大小写没有变化或读取直接失败，可以按“名称—方向—资源”三层排查，而不是先更换整个读取方案：

1. 先执行 stream_get_filters()，确认目标过滤器在当前环境已注册；不同 PHP 安装可能提供不同列表。
2. 再确认方向参数。读取文件却传入 STREAM_FILTER_WRITE，过滤器不会按预期作用于 fread() 或 stream_get_contents()。
3. 最后检查返回值和资源路径。附加函数返回 false 时，不要继续把它当作过滤器资源；php://filter 路径中 resource= 应放在末尾。

把链顺序写进代码审查清单

一个可维护的 stream_filter 读取实现，至少应能回答四个问题：数据从哪个资源进入、过滤器作用在哪个方向、多个过滤器的先后顺序是什么、失败时是否关闭了已打开的流。静态链优先使用 php://filter；需要按条件追加时使用动态 API，并在每次附加后检查返回值。这样排查时看到的不是一串难以解释的函数调用，而是一条有明确边界的转换链。

常见问题

多个读取过滤器应该用什么符号连接？

在 php://filter/read= 中用竖线 | 连接过滤器名称，链的顺序会影响最终结果。

append 和 prepend 会不会同时处理读写？

默认方向取决于流的打开模式，也可以显式传入 STREAM_FILTER_READ、STREAM_FILTER_WRITE 或 STREAM_FILTER_ALL。需要稳定行为时建议明确传入方向。

过滤器附加失败后还能继续读取吗？

可以读取原始流，但不要假设转换已经生效。先根据返回的 false 检查过滤器名称、参数、方向和资源状态；如果已经打开了流，处理完后要关闭它。