关于PHP的stream_bucket的认识

       最近使用stream进行一些项目的开发，在使用到stream bucket时，查阅了google还是国内的百度，发现网上关于stream bucket的介绍文章很少，如php.net的官方手册对于这一块也没有具体的文档，也没有很详细地介绍这个bucket在stream中的作用。最多出现可用信息也就是stream_bucket_append — Append bucket to brigade、stream_bucket_make_writeable — Return a bucket object from the brigade for operating on、stream_bucket_new — Create a new bucket for use on the current stream、stream_bucket_prepend。 相信很多Phper在阅读到这里也会有一些困惑，特别是使用到php_user_filter时必然会接触到bucket。因此我将自己一些理解和应用实例记录下来，同时我也希望跟各位能有进一步的沟通，可以email我，lailaiji@163.com（赖来基）。

       在PHP中，可以将文件、网络、数据压缩等操作资源对象可以视为一个stream流对象，通过统一流操作实现对这些对象的抽象和封装，方便我们处理相关资源对象。这篇博文就没有涉及展开对流的细节讲解，而是侧重通过讲解php_user_filter带来对于stream bucket的一些认识。

       回到本文的正题，一开始我们需要先了解清楚两个概念，Bucket（桶）及Brigade（队列）。这里可以理解为装载数据的一个对象，该对象包含数据内容(data)及数据长度(datalen)，相当于我们把流数据装到这个桶里来，该桶除了有数据还有数据的高度；而Brigade呢，则是这些桶的一个队列，从而组织成为一个数据流，这个队列可以是一个或者多个桶组成。

       理解了上面的概念，我们通过自定义的一个filter来分步讲解这两个概念。

新建一个test_custom_filter.php

class foo extends php_user_filter {
  public function filter($in, $out, &$consumed, $closing) {
  	$bucket = stream_bucket_make_writeable($in);
  	if($bucket)
        {
            $consumed += $bucket->datalen;
            $_f = fopen("php://temp",'w');
            $new_bucket = stream_bucket_new($_f, '');
            $string     = $bucket->data."I am lailaiji\n";
            $new_bucket->data=ucfirst($string);
            fclose($_f);
            stream_bucket_append($out, $new_bucket);
        }
        //数据处理成功，可供其它管道读取
        return PSFS_PASS_ON;
  }
}
stream_filter_register('test', 'foo');
$data = file_get_contents('php://filter/read=test/resource=data.txt');
echo $data;

 而data.txt文件

hello

运行php -f test_custom_filter.php得到如下

Hello
I am lailaiji

自定义的filter需要继承基类php_user_filter，并且重写filter方法，这个方法共有四个参数

• $in: 指向输入流队列

• $out:指向输出流队列

• $consumed: 引用方式传递，必须增加了转换数据的长度

• $closing: 如果最后一个bucket或者即将关闭时，可以设置为true

认识第一个函数：stream_bucket_make_writeable($bregade)

用途：将队列里的每个bucket取出，得到一个bucket对象。

$bucket = stream_bucket_make_writeable($in);

该方法可以得到我们从data.txt文件中的内容，可以通过调用bucket对象属性$bucket->data

第二个函数：stream_bucket_new（$handle,$buffer)

用途：产生一个指定流的bucket对象，一般来说，我们都会使用临时php://temp进行操作流数据

第三个函数：stream_bucket_append($handle,$bucket) 或者stream_bucket_prepend($handle,$bucket)

用途，将bucket对象追加到队列里

stream_bucket_append($out, $new_bucket);

上面通过这个方法将我们的bucket追加到输出流（$out),因此我们可以通过file_get_contents获得输出内容

另外php_user_filter还定义了三个常量

PSFS_PASS_ON：过滤器处理成功，输出流有可用数据返回

PSFS_FEED_ME：过滤器处理成功,但是没有数据返回

PSFS_ERR_FATAL:默认返回值，有错误，不返回

还有一点需要说明的是：

如果仔细的读者在使用php_user_filter，会发现filter函数必然后运行两次或者两次以上，明明我只有一个输入流，怎么会被运行两次呢？后来仔细分析了才发现最后一次运行是由于最后一个bucket即将关闭时，也就是closing的值为true的时候被调起，为整理关闭前做一些处理，此时输入流输出为空