PHP stream_bucket_make_writeable 怎样修改过滤器中的数据桶

在 PHP 自定义流过滤器里，stream_bucket_make_writeable() 的作用不是把字符串直接变成可改的普通变量，而是从输入 brigade 取出一个可以交给过滤器处理的数据桶。真正需要改写内容时，稳妥的做法是读取旧桶的 data，用新字符串创建一个 bucket，再把新 bucket 追加到输出 brigade。

官方地址：https://www.php.net/manual/en/function.stream-bucket-make-writeable.php

PHP 8.4 开始，这个函数返回 StreamBucket 实例；它的 data、dataLength 等属性用于描述当前桶。下面的写法把输入、变换和输出分开，既能解释 API 边界，也能避免把旧版示例中的“直接给 $bucket->data 赋值”当成所有版本都适用的方案。

先把数据桶当作输入载体读取

php_user_filter::filter() 会收到输入 brigade 和输出 brigade。调用 stream_bucket_make_writeable($in) 后，函数一次取出一个输入桶；当输入 brigade 没有可取的桶时，返回值为 null，while 循环自然结束。

这里的“writeable”更接近流内部可以把这个桶交给过滤器处理的语义。写文章或维护 PHP 8.4+ 代码时，不要把它理解成可以随意改写 StreamBucket::$data 的承诺。先读取数据，再决定生成什么输出，是更稳的边界。

读取 data，长度字段按版本兼容

$bucket->data 是当前数据块的字符串。长度字段在 PHP 8.4 中推荐使用 dataLength，旧代码中常见的是 datalen。如果文章或组件需要兼容多个 PHP 版本，可以用空合并运算符先取新名称，再回退到旧名称。

$consumed 记录的是从输入 brigade 消费掉的长度，所以应以原始输入桶的长度累计，而不是用转换后字符串的长度替代。比如大小写转换通常长度不变，但编码转换、过滤控制字符或拼接内容时，输入和输出长度可能不同。

data;
    $inputLength = $bucket->dataLength ?? $bucket->datalen;

    // 变换只作用于读取到的字符串，不直接改写 StreamBucket 属性。
    $output = strtoupper($input);
    $consumed += $inputLength;
}
?>

这段片段只展示数据关系，不能单独作为完整过滤器运行。完整实现还需要创建输出桶，并把它交给 $out。

用新 bucket 承接变换后的字符串

推荐的兼容模式是调用 stream_bucket_new($this->stream, $output) 创建新桶。创建时使用过滤器当前绑定的流资源，随后用 stream_bucket_append($out, $newBucket) 把它放到输出 brigade。这样不依赖直接修改 StreamBucket 的只读属性，也让“输入桶”和“输出桶”在代码上清楚分离。

data;
            $inputLength = $bucket->dataLength ?? $bucket->datalen;
            $output = strtoupper($input);

            // 新建 bucket，避免依赖直接写入 StreamBucket::$data。
            $newBucket = stream_bucket_new($this->stream, $output);
            if ($newBucket === null) {
                // 无法创建输出桶时终止过滤器，避免丢弃后继续传递。
                return PSFS_ERR_FATAL;
            }

            // consumed 统计输入字节，输出桶负责承接变换后的数据。
            $consumed += $inputLength;
            stream_bucket_append($out, $newBucket);
        }

        // closing 只表示本次回调处于收尾阶段，仍要交接已取出的桶。
        return PSFS_PASS_ON;
    }
}
?>

注册过滤器时同时确认方向和关闭责任

过滤器类定义完成后，用 stream_filter_register() 注册名称，再把它附加到目标流。写入过滤器和读取过滤器的方向不同，STREAM_FILTER_WRITE 表示写入流时变换，STREAM_FILTER_READ 则表示读取流时变换。方向写错时，代码本身可能没有语法问题，但读者观察到的内容不会出现在预期环节。

示例的关键不是把它当成截图结果，而是确认三件事：过滤器名称注册成功、过滤方向与数据路径一致、输出 brigade 最终被交回流链。过滤器自身不要在 filter() 中关闭宿主流；如需清理过滤器状态，使用 onClose() 管理自己的资源。

几个容易混淆的版本和返回边界

常见追问

为什么不直接写 `$bucket->data = strtoupper($bucket->data)`？

旧版基于 stdClass 的示例经常这样写，但 PHP 8.4+ 引入了专门的 StreamBucket 类型和属性边界。跨版本代码把输入桶视为读取对象，使用 stream_bucket_new() 创建输出桶更清楚，也更容易处理长度变化。

什么时候要使用 stream_bucket_prepend()？

当一个过滤器需要把新桶放到输出 brigade 前端时可以使用 prepend；普通的逐桶变换通常按读取顺序调用 stream_bucket_append()，这样输出顺序更直观。

stream_bucket_make_writeable() 会替我把桶放到输出队列吗？

不会。它只负责从输入 brigade 取出桶并返回对象。无论是原桶还是新桶，过滤器都需要显式调用 stream_bucket_append() 或 stream_bucket_prepend() 把要继续传递的数据交给输出 brigade。

总结

记住这条组合即可：stream_bucket_make_writeable() 负责取输入，StreamBucket::data 负责读内容，stream_bucket_new() 负责承接变换结果，stream_bucket_append() 负责输出交接。面对 PHP 8.4+，把“可写 bucket”理解成过滤器可处理的输入单元，而不是直接修改只读属性，代码边界会更稳定。