实现一个包装器

    此刻, 首先从下面功能完整的变量流包装实现开始. 构建他, 并开始检查每一块的工作原理.

    php_varstream.h

    2. #define PHP_VARSTREAM_H
    4. extern zend_module_entry varstream_module_entry;
    5. #define phpext_varstream_ptr &varstream_module_entry
    7. #ifdef PHP_WIN32
    8. #   define PHP_VARSTREAM_API __declspec(dllexport)
    9. #elif defined(__GNUC__) && __GNUC__ >= 4
    10. #   define PHP_VARSTREAM_API __attribute__ ((visibility("default")))
    11. #else
    12. #   define PHP_VARSTREAM_API
    13. #endif
    15. #ifdef ZTS
    16. #include "TSRM.h"
    17. #endif
    19. PHP_MINIT_FUNCTION(varstream);
    20. PHP_MSHUTDOWN_FUNCTION(varstream);
    22. #define PHP_VARSTREAM_WRAPPER       "var"
    23. #define PHP_VARSTREAM_STREAMTYPE    "varstream"
    25. /* 变量流的抽象数据结构 */
    26. typedef struct _php_varstream_data {
    27.     off_t   position;
    28.     char    *varname;
    29.     int     varname_len;
    30. } php_varstream_data;
    32. #ifdef ZTS
    33. #define VARSTREAM_G(v) TSRMG(varstream_globals_id, zend_varstream_globals *, v)
    34. #else
    35. #define VARSTREAM_G(v) (varstream_globals.v)
    36. #endif
    38. #endif
    1. #ifdef HAVE_CONFIG_H
    2. #include "config.h"
    3. #endif
    5. #include "php.h"
    6. #include "php_ini.h"
    7. #include "ext/standard/info.h"
    8. #include "ext/standard/url.h"
    9. #include "php_varstream.h"
    11. static size_t php_varstream_write(php_stream *stream,
    12.                 const char *buf, size_t count TSRMLS_DC)
    13. {
    14.     php_varstream_data *data = stream->abstract;
    15.     zval **var;
    16.     size_t newlen;
    18.     /* 查找变量 */
    19.     if (zend_hash_find(&EG(symbol_table), data->varname,
    20.             data->varname_len + 1,(void**)&var) == FAILURE) {
    21.         /* 变量不存在, 直接创建一个字符串类型的变量, 并保存新传递进来的内容 */
    22.        zval *newval;
    23.        MAKE_STD_ZVAL(newval);
    24.        ZVAL_STRINGL(newval, buf, count, 1); 
    25.        /* 将新的zval *放到变量中 */
    26.        zend_hash_add(&EG(symbol_table), data->varname,
    27.            data->varname_len + 1, (void*)&newval,
    28.            sizeof(zval*), NULL);
    29.        return count;
    30.     }   
    31.     /* 如果需要, 让变量可写. 这里实际上处理的是写时复制 */
    32.     SEPARATE_ZVAL_IF_NOT_REF(var);
    33.     /* 转换为字符串类型 */
    34.     convert_to_string_ex(var);
    35.     /* 重置偏移量(译注: 相比于正常的文件系统, 这里的处理实际上不支持文件末尾的空洞创建, 读者如果熟悉*nix文件系统, 应该了解译者所说, 否则请略过) */
    36.     if (data->position > Z_STRLEN_PP(var)) {
    37.         data->position = Z_STRLEN_PP(var);
    38.     }   
    39.     /* 计算新的字符串长度 */
    40.     newlen = data->position + count;
    41.     if (newlen < Z_STRLEN_PP(var)) {
    42.         /* 总长度不变 */
    43.         newlen = Z_STRLEN_PP(var);
    44.     } else if (newlen > Z_STRLEN_PP(var)) {
    45.         /* 重新调整缓冲区大小以保存新内容 */
    46.         Z_STRVAL_PP(var) =erealloc(Z_STRVAL_PP(var),newlen+1);
    47.         /* 更新字符串长度 */
    48.         Z_STRLEN_PP(var) = newlen;
    49.         /* 确保字符串NULL终止 */
    50.         Z_STRVAL_PP(var)[newlen] = 0;
    51.     }   
    52.     /* 将数据写入到变量中 */
    53.     memcpy(Z_STRVAL_PP(var) + data->position, buf, count);
    54.     data->position += count;
    56.     return count;
    57. }
    59. static size_t php_varstream_read(php_stream *stream,
    60.                 char *buf, size_t count TSRMLS_DC)
    61. {
    62.     php_varstream_data *data = stream->abstract;
    63.     zval **var, copyval;
    64.     int got_copied = 0;
    65.     size_t toread = count;
    67.     if (zend_hash_find(&EG(symbol_table), data->varname,
    68.         data->varname_len + 1, (void**)&var) == FAILURE) {
    69.         /* 变量不存在, 读不到数据, 返回0字节长度 */
    70.         return 0;
    71.     }   
    72.     copyval = **var;
    73.     if (Z_TYPE(copyval) != IS_STRING) {
    74.         /* 对于非字符串类型变量, 创建一个副本进行读, 这样对于只读的变量, 就不会改变其原始类型 */
    75.         zval_copy_ctor(&copyval);
    76.         INIT_PZVAL(&copyval);
    77.         got_copied = 1;
    78.     }   
    79.     if (data->position > Z_STRLEN(copyval)) {
    80.         data->position = Z_STRLEN(copyval);
    81.     }   
    82.     if ((Z_STRLEN(copyval) - data->position) < toread) {
    83.         /* 防止读取到变量可用缓冲区外的内容 */
    84.         toread = Z_STRLEN(copyval) - data->position;
    85.     }   
    86.     /* 设置缓冲区 */
    87.     memcpy(buf, Z_STRVAL(copyval) + data->position, toread);
    88.     data->position += toread;
    90.     /* 如果创建了副本, 则释放副本 */
    91.     if (got_copied) {
    92.         zval_dtor(&copyval);
    93.     }   
    95.     /* 返回设置到缓冲区的字节数 */
    96.     return toread;
    97. }
    99. static int php_varstream_closer(php_stream *stream,
    100.                             int close_handle TSRMLS_DC)
    101. {
    102.     php_varstream_data *data = stream->abstract;
    104.     /* 释放内部结构避免泄露 */
    105.     efree(data->varname);
    106.     efree(data);
    108.     return 0;
    109. }
    111. static int php_varstream_flush(php_stream *stream TSRMLS_DC)
    112. {
    113.     php_varstream_data *data = stream->abstract;
    114.     zval **var;
    116.     /* 根据不同情况, 重置偏移量 */
    117.     if (zend_hash_find(&EG(symbol_table), data->varname,
    118.                     data->varname_len + 1, (void**)&var)
    119.                     == SUCCESS) {
    120.         if (Z_TYPE_PP(var) == IS_STRING) {
    121.             data->position = Z_STRLEN_PP(var);
    122.         } else {
    123.             zval copyval = **var;
    124.             zval_copy_ctor(&copyval);
    125.             convert_to_string(&copyval);
    126.             data->position = Z_STRLEN(copyval);
    127.             zval_dtor(&copyval);
    128.     } else {
    129.         data->position = 0;
    130.     }
    132.     return 0;
    133. }
    135. static int php_varstream_seek(php_stream *stream, off_t offset,
    136.                     int whence, off_t *newoffset TSRMLS_DC)
    137. {
    138.     php_varstream_data *data = stream->abstract;
    140.     switch (whence) {
    141.         case SEEK_SET:
    142.             data->position = offset;
    143.             break;
    144.         case SEEK_CUR:
    145.             data->position += offset;
    146.             break;
    147.         case SEEK_END:
    148.         {
    149.             zval **var;
    150.            size_t curlen = 0;
    152.            if (zend_hash_find(&EG(symbol_table),
    153.                    data->varname,    data->varname_len + 1,
    154.                    (void**)&var) == SUCCESS) {
    155.               if (Z_TYPE_PP(var) == IS_STRING) {
    156.                   curlen = Z_STRLEN_PP(var);
    157.               } else {
    158.                   zval copyval = **var;
    159.                   zval_copy_ctor(&copyval);
    160.                   convert_to_string(&copyval);
    161.                   curlen = Z_STRLEN(copyval);
    162.                   zval_dtor(&copyval);
    163.               }
    164.            }
    166.            data->position = curlen + offset;
    167.            break;
    168.        }
    169.     }
    171.     /* 防止随机访问指针移动到缓冲区开始位置之前 */
    172.     if (data->position < 0) {
    173.         data->position = 0;
    174.     }
    176.     if (newoffset) {
    177.         *newoffset = data->position;
    178.     }
    180.     return 0;
    181. }
    183. static php_stream_ops php_varstream_ops = {
    184.     php_varstream_write,
    185.     php_varstream_read,
    186.     php_varstream_closer,
    187.     php_varstream_flush,
    188.     PHP_VARSTREAM_STREAMTYPE,
    189.     php_varstream_seek,
    190.     NULL, /* cast */
    191.     NULL, /* stat */
    192.     NULL, /* set_option */
    193. };
    195. /* Define the wrapper operations */
    196. static php_stream *php_varstream_opener(
    197.             php_stream_wrapper *wrapper,
    198.             char *filename, char *mode, int options,
    199.             char **opened_path, php_stream_context *context
    200.             STREAMS_DC TSRMLS_DC)
    201. {
    202.     php_varstream_data *data;
    203.     php_url *url;
    205.     if (options & STREAM_OPEN_PERSISTENT) {
    206.         /* 按照变量流的定义, 是不能持久化的
    207.          * 因为变量在请求结束后将被释放
    208.          */
    209.         php_stream_wrapper_log_error(wrapper, options
    210.             TSRMLS_CC, "Unable to open %s persistently",
    211.                                         filename);
    212.         return NULL;
    213.     }
    215.     /* 标准URL解析: scheme://user:pass@host:port/path?query#fragment */
    216.     url = php_url_parse(filename);
    217.     if (!url) {
    218.         php_stream_wrapper_log_error(wrapper, options
    219.             TSRMLS_CC, "Unexpected error parsing URL");
    220.         return NULL;
    221.     }
    222.     /* 检查是否有变量流URL必须的元素host, 以及scheme是否是var */
    223.     if (!url->host || (url->host[0] == 0) ||
    224.         strcasecmp("var", url->scheme) != 0) {
    225.         /* Bad URL or wrong wrapper */
    226.         php_stream_wrapper_log_error(wrapper, options
    227.             TSRMLS_CC, "Invalid URL, must be in the form: "
    228.                      "var://variablename");
    229.         php_url_free(url);
    230.         return NULL;
    231.     }
    233.     /* 创建一个数据结构保存协议信息(变量流协议重要是变量名, 变量名长度, 当前偏移量) */
    234.     data = emalloc(sizeof(php_varstream_data));
    235.     data->position = 0;
    236.     data->varname_len = strlen(url->host);
    237.     data->varname = estrndup(url->host, data->varname_len + 1);
    238.     /* 释放前面解析出来的url占用的内存 */
    239.     php_url_free(url);
    241.     /* 实例化一个流, 为其赋予恰当的流ops, 绑定抽象数据 */
    242.     return php_stream_alloc(&php_varstream_ops, data, 0, mode);
    243. }
    245. static php_stream_wrapper_ops php_varstream_wrapper_ops = {
    246.     php_varstream_opener, /* 调用php_stream_open_wrapper(sprintf("%s://xxx", PHP_VARSTREAM_WRAPPER))时执行 */
    247.     NULL, /* stream_close */
    248.     NULL, /* stream_stat */
    249.     NULL, /* url_stat */
    250.     NULL, /* dir_opener */
    251.     PHP_VARSTREAM_WRAPPER,
    252.     NULL, /* unlink */
    253. #if PHP_MAJOR_VERSION >= 5
    254.     /* PHP >= 5.0 only */
    255.     NULL, /* rename */
    256.     NULL, /* mkdir */
    257.     NULL, /* rmdir */
    258. #endif
    259. };
    261. static php_stream_wrapper php_varstream_wrapper = {
    262.     &php_varstream_wrapper_ops,
    263.     NULL, /* abstract */
    264.     0, /* is_url */
    265. };
    267. PHP_MINIT_FUNCTION(varstream)
    268. {
    269.     /* 注册流包装器:
    270.      * 1. 检查流包装器名字是否正确(符合这个正则: /^[a-zA-Z0-9+.-]+$/)
    271.      * 2. 将传入的php_varstream_wrapper增加到url_stream_wrappers_hash这个HashTable中, key为PHP_VARSTREAM_WRAPPER
    272.      */
    273.     if (php_register_url_stream_wrapper(PHP_VARSTREAM_WRAPPER,
    274.             &php_varstream_wrapper TSRMLS_CC)==FAILURE) {
    275.         return FAILURE;
    276.     }
    277.     return SUCCESS;
    278. }
    280. PHP_MSHUTDOWN_FUNCTION(varstream)
    281. {
    282.     /* 卸载流包装器: 从url_stream_wrappers_hash中删除 */
    283.     if (php_unregister_url_stream_wrapper(PHP_VARSTREAM_WRAPPER
    284.                                 TSRMLS_CC) == FAILURE) {
    285.         return FAILURE;
    286.     }
    287.     return SUCCESS;
    288. }
    290. zend_module_entry varstream_module_entry = {
    291. #if ZEND_MODULE_API_NO >= 20010901
    292.     STANDARD_MODULE_HEADER,
    293. #endif
    294.     "varstream",
    295.     NULL,
    296.     PHP_MINIT(varstream),
    297.     PHP_MSHUTDOWN(varstream),
    298.     NULL,
    299.     NULL,
    300. #if ZEND_MODULE_API_NO >= 20010901
    301.     "0.1",
    302. #endif
    303.     STANDARD_MODULE_PROPERTIES
    304. };
    306. #ifdef COMPILE_DL_VARSTREAM
    307. ZEND_GET_MODULE(varstream)
    308. #endif

    在构建加载扩展后, php就可以处理以var://开始的URL的请求, 它的行为和手册中用户空间实现的行为一致.

    内部实现

    首先你注意到的可能是这个扩展完全没有暴露用户空间函数. 它所做的只是在MINIT函数中调用了一个核心PHPAPI的钩子, 将var协议和我们定义的包装器关联起来:

    在本章前面你已经知道, 调用用户空间函数比如fopen将通过这个包装器的ops元素得到php_varstream_wrapper_ops, 这样去调用流的打开函数php_varstream_opener.

    这个函数的第一块代码检查是否请求持久化的流:

    1. if (options & STREAM_OPEN_PERSISTENT) {

    对于很多包装器这样的请求是合法的. 然而目前的情况这个行为没有意义. 一方面用户空间变量的定义就是临时的, 另一方面, varstream的实例化代价很低, 这就使得持久化的优势很小.

    像流包装层报告错误很简单, 只需要返回一个NULL值而不是流实例即可. 流包装层透出到用户空间的失败消息并不会说明具体的错误, 只是说明不能打开URL. 要想给开发者暴露更多的错误信息, 可以在返回之前使用php_stream_wrapper_log_error()函数.

    1. php_stream_wrapper_log_error(wrapper, options
    2.     TSRMLS_CC, "Unable to open %s persistently",
    3.                                 filename);
    4. return NULL;

    最后, varstream包装器创建了一个数据结构, 保存了流指向的变量名, 读取时的当前位置. 这个结构体将在流的读取和写入函数中用于获取变量, 并且将在流结束使用时由php_varstream_close函数释放.

    opendir()

    读写变量内容的实现可以再次进行扩展. 这里可以加入一个新的特性, 允许使用目录函数读取数组中的key. 在你的php_varstream_wrapper_ops结构体之前增加下面的代码:

    1. static size_t php_varstream_readdir(php_stream *stream,
    2.                 char *buf, size_t count TSRMLS_DC)
    3. {
    4.     php_stream_dirent *ent = (php_stream_dirent*)buf;
    5.     php_varstream_dirdata *data = stream->abstract;
    6.     char *key;
    7.     int type, key_len;
    8.     long idx;
    10.     /* 查找数组中的key */
    11.     type = zend_hash_get_current_key_ex(Z_ARRVAL_P(data->arr),
    12.                     &key, &key_len, &idx, 0, &(data->pos));
    14.     /* 字符串key */
    15.     if (type == HASH_KEY_IS_STRING) {
    16.         if (key_len >= sizeof(ent->d_name)) {
    17.             /* truncate long keys to maximum length */
    18.             key_len = sizeof(ent->d_name) - 1;
    19.         }
    20.         /* 设置到目录结构上 */
    21.         memcpy(ent->d_name, key, key_len);
    22.         ent->d_name[key_len] = 0;
    23.     /* 数值key */
    24.     } else if (type == HASH_KEY_IS_LONG) {
    25.         /* 设置到目录结构上 */
    26.         snprintf(ent->d_name, sizeof(ent->d_name), "%ld",idx);
    27.     } else {
    28.         /* 迭代结束 */
    29.         return 0;
    30.     }
    31.     /* 移动数组指针(位置记录到流的抽象结构中) */
    32.     zend_hash_move_forward_ex(Z_ARRVAL_P(data->arr),
    33.                                         &data->pos);
    34.     return sizeof(php_stream_dirent);
    35. }
    37. static int php_varstream_closedir(php_stream *stream,
    38.                             int close_handle TSRMLS_DC)
    39. {
    40.     php_varstream_dirdata *data = stream->abstract;
    42.     zval_ptr_dtor(&(data->arr));
    43.     efree(data);
    44.     return 0;
    45. }
    47. static int php_varstream_dirseek(php_stream *stream,
    48.                     off_t offset, int whence,
    49.                     off_t *newoffset TSRMLS_DC)
    50. {
    51.     php_varstream_dirdata *data = stream->abstract;
    53.     if (whence == SEEK_SET && offset == 0) {
    54.         /* 重置数组指针 */
    55.         zend_hash_internal_pointer_reset_ex(
    56.                     Z_ARRVAL_P(data->arr), &(data->pos));
    57.         if (newoffset) {
    58.             *newoffset = 0;
    59.         }
    60.         return 0;
    61.     }
    62.     /* 不支持其他类型的随机访问 */
    63.     return -1;
    64. }
    66. static php_stream_ops php_varstream_dirops = {
    67.     NULL, /* write */
    68.     php_varstream_readdir,
    69.     php_varstream_closedir,
    70.     NULL, /* flush */
    71.     PHP_VARSTREAM_DIRSTREAMTYPE,
    72.     php_varstream_dirseek,
    73.     NULL, /* cast */
    74.     NULL, /* stat */
    75.     NULL, /* set_option */
    76. };
    78. static php_stream *php_varstream_opendir(
    79.             php_stream_wrapper *wrapper,
    80.             char *filename, char *mode, int options,
    81.             char **opened_path, php_stream_context *context
    82.             STREAMS_DC TSRMLS_DC)
    83. {
    84.     php_varstream_dirdata *data;
    85.     php_url *url;
    86.     zval **var;
    88.     /* 不支持持久化流 */
    89.     if (options & STREAM_OPEN_PERSISTENT) {
    90.         php_stream_wrapper_log_error(wrapper, options
    91.                 TSRMLS_CC, "Unable to open %s persistently",
    92.                 filename);
    93.         return NULL;
    94.     }
    96.     /* 解析URL */
    97.     url = php_url_parse(filename);
    98.     if (!url) {
    99.         php_stream_wrapper_log_error(wrapper, options
    100.                 TSRMLS_CC, "Unexpected error parsing URL");
    101.         return NULL;
    102.     }
    103.     /* 检查请求URL的正确性 */
    104.     if (!url->host || (url->host[0] == 0) ||
    105.             strcasecmp("var", url->scheme) != 0) {
    106.         /* Bad URL or wrong wrapper */
    107.         php_stream_wrapper_log_error(wrapper, options
    108.                 TSRMLS_CC, "Invalid URL, must be in the form: "
    109.                 "var://variablename");
    110.         php_url_free(url);
    111.         return NULL;
    112.     }
    114.     /* 查找变量 */
    115.     if (zend_hash_find(&EG(symbol_table), url->host,
    116.                 strlen(url->host) + 1, (void**)&var) == FAILURE) {
    117.         php_stream_wrapper_log_error(wrapper, options
    118.                 TSRMLS_CC, "Variable $%s not found", url->host);
    119.         php_url_free(url);
    120.         return NULL;
    121.     }
    123.     /* 检查变量类型 */
    124.     if (Z_TYPE_PP(var) != IS_ARRAY) {
    125.         php_stream_wrapper_log_error(wrapper, options
    126.                 TSRMLS_CC, "$%s is not an array", url->host);
    127.         php_url_free(url);
    128.         return NULL;
    129.     }
    130.     /* 释放前面分配的URL结构 */
    131.     php_url_free(url);
    133.     /* 分配抽象数据结构 */
    134.     data = emalloc(sizeof(php_varstream_dirdata));
    135.     if ( Z_ISREF_PP(var) && Z_REFCOUNT_PP(var) > 1) {
    136.         /* 全拷贝 */
    137.         MAKE_STD_ZVAL(data->arr);
    138.         *(data->arr) = **var;
    139.         zval_copy_ctor(data->arr);
    140.         INIT_PZVAL(data->arr);
    141.     } else {
    142.         /* 写时拷贝 */
    143.         data->arr = *var;
    144.         Z_SET_REFCOUNT_P(data->arr, Z_REFCOUNT_P(data->arr) + 1);
    145.     }
    146.     /* 重置数组指针 */
    147.     zend_hash_internal_pointer_reset_ex(Z_ARRVAL_P(data->arr),
    148.             &data->pos);
    149.     return php_stream_alloc(&php_varstream_dirops,data,0,mode);
    150. }

    现在, 将你的php_varstream_wrapper_ops结构体中的dir_opener的NULL替换成你的php_varstream_opendir函数. 最后, 将下面新定义的类型放入到你的php_varstream.h文件的php_varstream_data定义下面:

    1. #define PHP_VARSTREAM_DIRSTREAMTYPE    "varstream directory"
    2. typedef struct _php_varstream_dirdata {
    3.     zval *arr;
    4.     HashPosition pos;

    在你基于fopen()实现的varstream包装器中, 你直接使用持久变量名, 每次执行读写操作时从符号表中获取变量. 而这里, opendir()的实现中获取变量时处理了变量不存在或者类型错误的异常. 你还有一个数组变量的拷贝, 这就说明原数组的改变并不会影响后续的readdir()调用的结果. 原来存储变量名的方式也可以正常工作, 这里只是给出另外一种选择作为演示示例.

    实际上, 目录流并没有使用SEEK_CUR, SEEK_END, 或者除了0之外的偏移量. 在实现目录流操作时, 最好还是涉及你的函数能以某种方式处理这些情况, 以使得在流包装层变化时能够适应其目录随机访问.