PHP stream_filter 处理上传内容的分段方式

PHP 用 stream_filter 处理上传内容时，关键不是人为指定每段大小，而是把过滤器挂到“读取上传数据”的流上：普通 multipart/form-data 上传应读取 $_FILES 指向的临时文件，原始请求体上传则读取 php://input。流会按内部 bucket 分批交给过滤器，应用只需要保存跨 bucket 的残留内容，并在关闭阶段完成最后一次刷新。

bucket 是 PHP 流层的内部数据块，不等同于一行、一条 CSV 记录或 multipart 的一个 part。凡是依赖记录边界的过滤器，都必须自己保存不完整片段。

先区分两种上传入口

对于浏览器常见的 multipart/form-data，PHP 会先解析请求并把文件保存到临时目录，然后通过 $_FILES 提供文件名、大小、错误码和临时路径。此时再给临时文件的读取流挂过滤器，可以避免把整个文件一次性读入内存，但不能改变 PHP 已经完成上传解析这个事实。

如果客户端直接发送 application/octet-stream 等原始请求体，应用可以打开 php://input。过滤器会参与应用层读取过程，适合边清洗边落盘。两种入口最终都能接到同一个输出流，但它们的错误处理和请求约定不同。

最小写法：给临时上传文件挂读取过滤器

下面先注册过滤器，再打开上传临时文件。STREAM_FILTER_READ 明确表示过滤发生在读取链；stream_copy_to_stream() 会持续读取剩余数据并写入目标流，不需要 file_get_contents() 把全部内容放进内存。

不要使用客户端传来的原始文件名拼接目标路径。示例中的 $targetPath 应由应用根据业务 ID、随机名或白名单扩展名生成，并放在受控目录中。

自定义过滤器如何跨 bucket 保留半行

过滤器的 filter() 接收输入和输出 bucket brigade。每取出一个可写 bucket，都要把其字节数加入 $consumed。如果业务以换行符为记录边界，就把本次数据和上次留下的半行拼接，输出完整行，把最后一段继续留在对象属性中。

datalen;
            $data = $this->tail . $bucket->data;
            $parts = explode("\n", $data);

            // 最后一段可能是不完整行，保留到下一次调用。
            $this->tail = array_pop($parts);

            foreach ($parts as $line) {
                $normalized = rtrim($line, "\r \t") . "\n";
                $outputBucket = stream_bucket_new($this->stream, $normalized);
                stream_bucket_append($out, $outputBucket);
            }
        }

        if ($closing && $this->tail !== '') {
            // 流关闭前输出最后一段没有换行符的内容。
            $outputBucket = stream_bucket_new(
                $this->stream,
                rtrim($this->tail, "\r \t")
            );
            stream_bucket_append($out, $outputBucket);
            $this->tail = '';
        }

        return PSFS_PASS_ON;
    }
}

这里返回 PSFS_PASS_ON，因为完整输出 bucket 已经追加到输出 brigade。如果当前没有足够数据产生任何输出，可按过滤器设计返回 PSFS_FEED_ME；遇到不可恢复错误才返回 PSFS_ERR_FATAL。不要假设每次调用都会收到固定长度，也不要假设一个 bucket 正好对应一行。

原始请求体用 php://input 分段落盘

客户端和服务端约定直接上传原始内容时，只需把输入流换成 php://input。过滤器注册代码可以复用，但应用仍应先检查请求方法、Content-Type、认证信息和允许的最大长度。

如果应用把 enable_post_data_reading 设为 0，PHP 不会自动填充 $_POST 和 $_FILES，请求体仍可由应用从 php://input 自行解析。这属于另一套协议设计，不能与默认 multipart 上传代码直接混用。

哪些限制不会被 stream_filter 绕过

采用建议

如果目标只是保存上传文件，直接使用 move_uploaded_file() 更简单；只有在落盘前必须执行编码归一化、逐行清洗、哈希统计或内容转换时，才值得引入 stream_filter。标准表单上传优先过滤临时文件读取流，原始上传接口再使用 php://input。无论选择哪种方式，都要把半条记录放进过滤器状态，并把上传限制、安全校验和异常清理保留在外层。

常见问题

能指定每个 bucket 的固定大小吗？

不能把 bucket 当作稳定的应用协议分片。底层读取方式和缓冲状态会影响 bucket，业务应只依赖内容边界。

为什么 stream_filter_append 要在读取前调用？

过滤器只会处理挂载后经过该链的数据。尽早挂载可以避免部分数据先被读取而绕过过滤逻辑。

过滤器能代替上传大小限制吗？

不能。它处理的是已经进入流读取阶段的数据；请求接收上限、临时目录和上传错误仍由服务器与 PHP 上传配置负责。