过滤器

过滤器作为读写操作的流内容传输过程中的附加阶段. 要注意的是直到php 4.3中才加入了流过滤器, 在php 5.0对流过滤器的API设计做过较大的调整. 本章的内容遵循的是php 5的流过滤器规范.

在流上应用已有的过滤器

在一个打开的流上应用一个已有的过滤器只需要几行代码即可:

  1. php_stream *php_sample6_fopen_read_ucase(const char *path
  2.                                         TSRMLS_DC) {
  3.     php_stream_filter *filter;
  4.     php_stream *stream;
  6.     stream = php_stream_open_wrapper_ex(path, "r",
  7.                         REPORT_ERRORS | ENFORCE_SAFE_MODE,
  8.                         NULL, FG(default_context));
  9.     if (!stream) {
  10.         return NULL;
  11.     }
  13.     filter = php_stream_filter_create("string.toupper", NULL,
  14.                                         0 TSRMLS_CC);
  15.     if (!filter) {
  16.         php_stream_close(stream);
  17.         return NULL;
  18.     }
  19.     php_stream_filter_append(&stream->readfilters, filter);
  21.     return stream;
  22. }

首先来看看这里引入的API函数以及它的兄弟函数:

  1. php_stream_filter *php_stream_filter_create(
  2.                 const char *filtername, zval *filterparams,
  3.                 int persistent TSRMLS_DC);
  4. void php_stream_filter_prepend(php_stream_filter_chain *chain,
  5.                 php_stream_filter *filter);
  6. void php_stream_filter_append(php_stream_filter_chain *chain,
  7.                 php_stream_filter *filter);

php_stream_filter_create()的filterparams参数和用户空间对应的stream_filter_append()和stream_filter_prepend()函数的同名参数含义一致. 要注意, 所有传递到php_stream_filter_create()的zval *数据都不是过滤器所拥有的. 它们只是在过滤器创建期间被借用而已, 因此在调用作用域分配传入的所有内存空间都要手动释放.

如果过滤器要被应用到一个持久化流, 则必须设置persistent参数为非0值. 如果你不确认你要应用过滤器的流是否持久化的, 则可以使用php_stream_is_persistent()宏进行检查, 它只接受一个php_stream *类型的参数.

如在前面例子中看到的, 流过滤器被隔离到两个独立的链条中. 一个用于写操作中对php_stream_write()调用响应时的stream->ops->write()调用之前. 另外一个用于读操作中对stream->ops->read()取回的所有数据进行处理.

在这个例子中你使用&stream->readfilters指示读的链条. 如果你想要在写的链条上应用一个过滤器, 则可以使用&stream->writefilters.

定义一个过滤器实现

注册过滤器实现和注册包装器遵循相同的基础规则. 第一步是在MINIT阶段向php中引入你的过滤器, 与之匹配的是在MSHUTDOWN阶段移除它. 下面是需要调用的API原型以及两个注册过滤器工厂的示例:

  1. int php_stream_filter_register_factory(
  2.             const char *filterpattern,
  3.             php_stream_filter_factory *factory TSRMLS_DC);
  4. int php_stream_filter_unregister_factory(
  5.             const char *filterpattern TSRMLS_DC);
  7. PHP_MINIT_FUNCTION(sample6)
  8. {
  9.     php_stream_filter_register_factory("sample6",
  10.             &php_sample6_sample6_factory TSRMLS_CC);
  11.     php_stream_filter_register_factory("sample.*",
  12.             &php_sample6_samples_factory TSRMLS_CC);
  13.     return SUCCESS;
  14. }
  15. PHP_MSHUTDOWN_FUNCTION(sample6)
  16. {
  17.     php_stream_filter_unregister_factory("sample6" TSRMLS_CC);
  18.     php_stream_filter_unregister_factory("sample.*"
  19.                                         TSRMLS_CC);
  20.     return SUCCESS;
  21. }

这里注册的第一个工厂定义了一个具体的过滤器名sample6; 第二个则利用了流包装层内部的基本匹配规则. 为了进行演示, 下面的用户空间代码, 每行都将尝试通过不同的名字实例化php_sample6_samples_factory.

  1. <?php
  2.     stream_filter_append(STDERR, 'sample.one');
  3.     stream_filter_append(STDERR, 'sample.3');
  4.     stream_filter_append(STDERR, 'sample.filter.thingymabob');
  5.     stream_filter_append(STDERR, 'sample.whatever');
  6. ?>

php_sample6_samples_factory的定义如下面代码, 你可以将这些代码放到你的MINIT块上面:

  1. #include "ext/standard/php_string.h"
  3. typedef struct {
  4.     char    is_persistent;
  5.     char    *tr_from;
  6.     char    *tr_to;
  7.     int     tr_len;
  8. } php_sample6_filter_data;
  10. /* 过滤逻辑 */
  11. static php_stream_filter_status_t php_sample6_filter(
  12.         php_stream *stream, php_stream_filter *thisfilter, 
  13.         php_stream_bucket_brigade *buckets_in, 
  14.         php_stream_bucket_brigade *buckets_out, 
  15.         size_t *bytes_consumed, int flags TSRMLS_DC) 
  16. {
  17.     php_stream_bucket       *bucket;
  18.     php_sample6_filter_data *data       = thisfilter->abstract;
  19.     size_t                  consumed    = 0;
  21.     while ( buckets_in->head ) { 
  22.         bucket      = php_stream_bucket_make_writeable(buckets_in->head TSRMLS_CC);
  23.         php_strtr(bucket->buf, bucket->buflen, data->tr_from, data->tr_to, data->tr_len);
  24.         consumed    += bucket->buflen;
  25.         php_stream_bucket_append(buckets_out, bucket TSRMLS_CC);
  26.     }   
  27.     if ( bytes_consumed ) { 
  28.         *bytes_consumed = consumed;
  29.     }   
  30.     return PSFS_PASS_ON;
  31. }
  33. /* 过滤器的释放 */
  34. static void php_sample6_filter_dtor(php_stream_filter *thisfilter TSRMLS_DC)
  35. {
  36.     php_sample6_filter_data *data   = thisfilter->abstract;
  37.     pefree(data, data->is_persistent);
  38. }
  40. /* 流过滤器操作表 */
  41. static php_stream_filter_ops php_sample6_filter_ops = { 
  42.     php_sample6_filter, 
  43.     php_sample6_filter_dtor, 
  44.     "sample.*",
  45. };
  47. /* 字符翻译使用的表 */
  48. #define PHP_SAMPLE6_ALPHA_UCASE     "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
  49. #define PHP_SAMPLE6_ALPHA_LCASE     "abcdefghijklmnopqrstuvwxyz"
  50. #define PHP_SAMPLE6_ROT13_UCASE     "NOPQRSTUVWXYZABCDEFGHIJKLM"
  51. #define PHP_SAMPLE6_ROT13_LCASE     "nopqrstuvwxyzabcdefghijklm"
  53. /* 创建流过滤器实例的过程 */
  54. static php_stream_filter *php_sample6_filter_create(
  55.         const char *name, zval *param, int persistent TSRMLS_DC)
  56. {
  57.     php_sample6_filter_data *data;
  58.     char                    *subname;
  60.     /* 安全性检查 */
  61.     if ( strlen(name) < sizeof("sample.") || strncmp(name, "sample.", sizeof("sample.") - 1) ) { 
  62.         return NULL;
  63.     }   
  65.     /* 分配流过滤器数据 */
  66.     data    = pemalloc(sizeof(php_sample6_filter_data), persistent);
  68.     if ( !data ) { 
  69.         return NULL;
  70.     }   
  72.     /* 设置持久性 */
  73.     data->is_persistent = persistent;
  75.     /* 根据调用时的名字, 对过滤器数据进行适当初始化 */
  76.     subname = (char *)name + sizeof("sample.") - 1;
  77.     if ( strcmp(subname, "ucase") == 0 ) { 
  78.         data->tr_from   = PHP_SAMPLE6_ALPHA_LCASE;
  79.         data->tr_to     = PHP_SAMPLE6_ALPHA_UCASE;
  80.     } else if ( strcmp(subname, "lcase") == 0 ) { 
  81.         data->tr_from   = PHP_SAMPLE6_ALPHA_UCASE;
  82.         data->tr_to     = PHP_SAMPLE6_ALPHA_LCASE;
  83.     } else if ( strcmp(subname, "rot13") == 0 ) { 
  84.         data->tr_from   = PHP_SAMPLE6_ALPHA_LCASE
  85.                         PHP_SAMPLE6_ALPHA_UCASE;;
  86.         data->tr_to     = PHP_SAMPLE6_ROT13_LCASE
  87.                         PHP_SAMPLE6_ROT13_UCASE;
  88.     } else {
  89.         /* 不支持 */
  90.         pefree(data, persistent);
  91.         return NULL;
  92.     }   
  94.     /* 节省未来使用时每次的计算 */
  95.     data->tr_len    = strlen(data->tr_from);
  97.     /* 分配一个php_stream_filter结构并按指定参数初始化 */
  98.     return php_stream_filter_alloc(&php_sample6_filter_ops, data, persistent);
  99. }
  101. /* 流过滤器工厂, 用于创建流过滤器实例(php_stream_filter_append/prepend的时候) */
  102. static php_stream_filter_factory php_sample6_samples_factory = { 
  103.     php_sample6_filter_create
  104. };

译注: 下面是译者对整个流程的分析

一. MINIT阶段的register操作将在stream_filters_hash这个HashTable中注册一个php_stream_filter_factory结构, 它只有一个成员create_filter, 用来创建过滤器实例.

二. 用户空间代码stream_filter_append(STDERR, ‘sapmple.one’);在内部的实现是apply_filter_to_stream()函数(ext/standard/streamsfuncs.c中), 这里有两步操作, 首先创建过滤器, 然后将过滤器按照参数追加到流的readfilters/writefilters相应链中;

二.一 创建过滤器(php_stream_filter_create()): 首先直接按照传入的名字精确的从stream_filters_hash(或FG(stream_filters))中查找, 如果没有, 从右向左替换句点后面的内容为星号”*”进行查找, 直到找到注册的过滤器工厂或错误返回. 一旦找到注册的过滤器工厂, 就调用它的create_filter成员, 创建流过滤器实例.

二.二 直接按照参数描述放入流的readfilters/writefilters相应位置.

三. 用户向该流进行写入或读取操作时(以写为例): 此时内部将调用_php_stream_write(), 在这个函数中, 如果流的writefilters非空, 则调用流过滤器的fops->filter()执行过滤, 并根据返回状态做相应处理.

四. 当流的生命周期结束, 流被释放的时候, 将会检查流的readfilters/writefilters是否为空, 如果非空, 相应的调用php_stream_filter_remove()进行释放, 其中就调用了fops->fdtor对流过滤器进行释放.

上一章我们已经熟悉了流包装器的实现, 你可能能够识别这里的基本结构. 工厂函数(php_sample6_samples_filter_create)被调用分配一个过滤器实例, 并赋值给一个操作集合和抽象数据. 这上面的例子中, 你的工厂为所有的过滤器类型赋值了相同的ops结构, 但使用了不同的初始化数据.

调用作用域将得到这里分配的过滤器, 并将它赋值给流的readfilters链或writefilters链. 接着, 当流的读/写操作被调用时, 过滤器链将数据放入到一个或多个php_stream_bucket结构体, 并将这些bucket组织到一个队列php_stream_bucket_brigade中传递给过滤器.

这里, 你的过滤器实现是前面的php_sample6_filter, 它取出输入队列bucket中的数据, 使用php_sample6_filter_create中确定的字符表执行字符串翻译, 并将修改后的bucket放入到输出队列.

由于这个过滤器的实现并没有其他内部缓冲, 因此几乎不可能出错, 因此它总是返回PSFS_PASS_ON, 告诉流包装层有数据被过滤器存放到了输出队列中. 如果过滤器执行了内部缓冲消耗了所有的输入数据而没有产生输出, 就需要返回PSFS_FEED_ME标识过滤器循环周期在没有其他输入数据时暂时停止. 如果过滤器碰到了关键性的错误, 它应该返回PSFS_ERR_FATAL, 它将指示流包装层, 过滤器链处于不稳定状态. 这将导致流被关闭.

用于维护bucket和bucket队列的API函数如下:

  1. php_stream_bucket *php_stream_bucket_new(php_stream *stream,
  2.                       char *buf, size_t buflen, int own_buf,
  3.                       int buf_persistent TSRMLS_DC);

创建一个php_stream_bucket用于存放到输出队列. 如果own_buf被设置为非0值, 流包装层可以并且通常都会修改它的内容或在某些点释放分配的内存. buf_persistent的非0值标识buf使用的内存是否持久分配的:

  1. int php_stream_bucket_split(php_stream_bucket *in,
  2.         php_stream_bucket **left, php_stream_bucket **right,
  3.         size_t length TSRMLS_DC);

这个函数将in这个bucket的内容分离到两个独立的bucket对象中. left这个bucket将包含in中的前length个字符, 而right则包含剩下的所有字符.

  1. void php_stream_bucket_delref(php_stream_bucket *bucket
  2.                                                  TSRMLS_DC);
  3. void php_stream_bucket_addref(php_stream_bucket *bucket);

Bucket使用和zval以及资源相同的引用计数系统. 通常, 一个bucket仅属于一个上下文, 也就是它依附的队列.

  1. void php_stream_bucket_prepend(
  2.                     php_stream_bucket_brigade *brigade,
  3.                     php_stream_bucket *bucket TSRMLS_DC);
  4. void php_stream_bucket_append(
  5.         php_stream_bucket_brigade *brigade,
  6.         php_stream_bucket *bucket TSRMLS_DC);

这两个函数扮演了过滤器子系统的苦力, 用于附加bucket到队列的开始(prepend)或末尾(append)

  1. void php_stream_bucket_unlink(php_stream_bucket *bucket
  2.                                                  TSRMLS_DC);

在过滤器逻辑应用处理完成后, 旧的bucket必须使用这个函数从它的输入队列删除(unlink).

  1. php_stream_bucket *php_stream_bucket_make_writeable(
  2.         php_stream_bucket *bucket TSRMLS_DC);

将一个bucket从它所依附的队列中移除, 并且如果需要, 赋值bucket->buf的内部缓冲区, 这样就使得它的内容可修改. 在某些情况下, 比如当输入bucket的引用计数大于1时, 返回的bucket将会是不同的实例, 而不是传入的实例. 因此, 我们要保证在调用作用域使用的是返回的bucket, 而不是传入的bucket.