PHP stream filter 怎样串联字符转换

PHP stream filter 串联字符转换时，应先确定数据在哪条链上处理，再按后一个过滤器需要的输入编码安排顺序。stream_filter_append 会把过滤器加到链尾；连续追加时，先追加的先处理。例如把 UTF-16LE 输入转成 UTF-8 后再使用 string.toupper，不能随意把两者对调，否则字节级大小写处理可能改坏 UTF-16LE 字符。

本文限定 PHP 8.2 或更新版本、启用 iconv、源编码已知。官方地址：https://www.php.net/manual/en/function.stream-filter-append.php。编码转换过滤器说明：https://www.php.net/manual/en/filters.convert.php。

字符变了，不一定是源文件编码猜错

假设导入程序接收 UTF-16LE 文本，要求输出 UTF-8，并把其中的 ASCII 英文字母改为大写。正常的职责划分是：convert.iconv.UTF-16LE.UTF-8 负责编码转换，string.toupper 负责 ASCII 大写。两项功能单独存在，并不意味着任意顺序组合都等价。

遇到非 ASCII 字符被替换成另一个合法字符的现象时，不应只尝试更换编码名称。先看大小写过滤器实际接收到的是 UTF-8 文本，还是尚未转码的 UTF-16LE 字节。后一种情况甚至可能不报转码错误，因为被改动后的字节仍然表示某个合法字符。

过滤器属于读取链还是写入链

读取链处理从流资源读出的数据；写入链处理写入资源的数据。一个可读写流可以拥有两条链。若省略 mode，追加行为与流打开模式有关，所以本例显式传 STREAM_FILTER_READ，避免相同转换在读写两端都被安装。STREAM_FILTER_WRITE 则用于明确只处理写入方向。

stream_filter_append 在现有链末尾追加，stream_filter_prepend 在链首插入。因此不能只看函数调用先后：连续 prepend 会把后来插入的过滤器放到前面。本文使用连续 append，直接让过滤器名列表表达顺序，不混用首插和尾插。

本例中的内存流保留原始输入，读取链包含编码转换和 ASCII 大写两个过滤器，读取方取得过滤后的 UTF-8 内容；写入链不包含它们。这样的结构便于区分“存储了哪些字节”与“读到了哪些字节”。

最小示例：先转 UTF-8，再做 ASCII 大写

下面直接构造 a、š、z 三个字符的 UTF-16LE 字节，不依赖编辑器保存编码，也不访问网络或真实业务文件。先写原始数据、回到开头，再安装读取链；此时尚未进行业务读取。代码是供读者复现的示例，本文没有在本机执行它。

依照本例的字符与过滤器语义，预期文本为 AšZ，UTF-8 十六进制为 41c5a15a。这是预期值，不是实测日志。š 保持不变是正确的，因为 string.toupper 对应 strtoupper，PHP 8.2 起只转换 ASCII 字母；它不是完整的 Unicode 大写转换器。

读取链只影响读取结果，本例也没有把转码后的结果回写成新的源内容。若目标是生成 UTF-16LE 文件，应另行确定写入链的数据契约；不能因为读取示例使用了某个顺序，就原样套在接收不同编码的写入链上。

反向顺序为什么会悄悄改掉字符

在这组已知字节中，š 是 U+0161，其 UTF-16LE 表示为 61 01。ASCII 字节级大写处理会把 0x61 当成小写 a，改成 0x41。若先对原始 UTF-16LE 字节运行 string.toupper，这两个字节就变成 41 01，表示 U+0141，即 Ł；再转 UTF-8 也无法知道原来应该是 š。

因此正确链的意义不是“大小写操作越晚越好”，而是“让每个过滤器接收符合自身语义的数据”。UTF-8 中非 ASCII 多字节字符不会被此 ASCII 转换器当作小写 a–z 修改；但把相同字节规则套在 UTF-16LE 上，就没有同样的字符边界保障。这是根据明确编码值推导的风险，不应推广成所有编码、所有转换器都遵循同一排列。

这里涉及四个明确对象：UTF-16LE 字节、UTF-8 文本、iconv 转码和 ASCII 大写；编码表示还决定 š 与 Ł 两个字符分别对应哪些字节。若业务要求 š 也转换成 Š，需要多字节大小写方案，不应宣称 string.toupper 已完成这项任务。

链顺序固定后，再留意缓冲与输入完整性

最简单的做法是在首次读取前安装完整的读取链，随后不要边读边换过滤器。官方 append 文档指出，读取涉及内部缓冲；后来追加过滤器时，已有未消费缓冲数据会被新过滤器处理。prepend 的缓冲行为又不同。因此，读了一部分后临时插入过滤器，不应当作“把全文件重新按新链处理”的可靠方式。

convert.iconv.* 要求 iconv 支持，源与目标编码写进过滤器名称，不是放进第四个 params 参数。源编码也必须真实已知，过滤器不会自动猜测。任意把 UTF-8 字节标成 UTF-16LE，即使名字合法，仍会得到错误语义。

真实输入可能含无效或不完整的多字节序列。不要靠屏蔽警告把部分结果当成成功；应保留转换警告，并按输入格式定义失败处理。这个内存示例只有已知合法字节，不能证明生产输入没有跨块、截断或坏数据。要流式处理大文件，也不必照搬 stream_get_contents 一次取出全部结果的演示方式。

相关问题

iconv 过滤器会自动识别编码吗？

不会。名称中的输入编码必须由数据来源或明确格式契约提供。

连续 append 和连续 prepend 一样吗？

不一样。append 加到末尾，prepend 插到开头，最终链位置不同。

UTF-8 输出是不是就保证所有字符都大写了？

不是。编码转换与大小写范围是两件事，string.toupper 只负责这里的 ASCII 字母。

进一步的官方说明：https://www.php.net/manual/en/function.stream-filter-prepend.php；https://www.php.net/manual/en/filters.string.php；https://www.php.net/manual/en/function.strtoupper.php。排查 filter 链时，把方向、最终链位置和每层编码契约同时写清楚，比反复切换编码名更容易定位问题。