實現(xiàn)流

php的流最強力的特性之一是它可以訪問眾多數(shù)據(jù)源: 普通文件, 壓縮文件, 網(wǎng)絡(luò)透明通道, 加密網(wǎng)絡(luò), 命名管道以及域套接字, 它們對于用戶空間以及內(nèi)部都是統(tǒng)一的API.

php流的表象之下

對于給定的流實例, 比如文件流和網(wǎng)絡(luò)流, 它們的不同在于上一章你使用的流創(chuàng)建函數(shù)返回的php_stream結(jié)構(gòu)體中的ops成員.

typedef struct _php_stream {
    ...
    php_stream_ops *ops;
    ...
} php_stream;

php_stream_ops結(jié)構(gòu)體定義的是一個函數(shù)指針集合以及一個描述標(biāo)記.

typedef struct _php_stream_ops {
    size_t (*write)(php_stream *stream, const char *buf,
                            size_t count TSRMLS_DC);
    size_t (*read)(php_stream *stream, char *buf,
                            size_t count TSRMLS_DC);
    int    (*close)(php_stream *stream, int close_handle
                            TSRMLS_DC);
    int    (*flush)(php_stream *stream TSRMLS_DC);

    const char *label;

    int (*seek)(php_stream *stream, off_t offset, int whence,
                            off_t *newoffset TSRMLS_DC);
    int (*cast)(php_stream *stream, int castas, void **ret
                            TSRMLS_DC);
    int (*stat)(php_stream *stream, php_stream_statbuf *ssb
                            TSRMLS_DC);
    int (*set_option)(php_stream *stream, int option,int value,
                            void *ptrparam TSRMLS_DC);
} php_stream_ops;

當(dāng)流訪問函數(shù)比如php_stream_read()被調(diào)用時, 流包裝層實際上解析調(diào)用了stream->ops中對應(yīng)的函數(shù), 這樣實際調(diào)用的就是當(dāng)前流類型特有的read實現(xiàn). 比如, 普通文件的流ops結(jié)構(gòu)體中的read函數(shù)實現(xiàn)如下(實際的該實現(xiàn)比下面的示例復(fù)雜一點):

size_t php_stdio_read(php_stream *stream, char *buf,
                                size_t count TSRMLS_DC)
{
    php_stdio_stream_data *data =
                (php_stdio_stream_data*)stream->abstract;
    return read(data->fd, buf, count);
}

而compress.zlib流使用的ops結(jié)構(gòu)體中則read則指向的是如下的函數(shù):

size_t php_zlib_read(php_stream *stream, char *buf,
                                size_t count TSRMLS_DC)
{
    struct php_gz_stream_data_t *data =
            (struct php_gz_stream_data_t *) stream->abstract;

    return gzread(data->gz_file, buf, count);
}

這里第一點需要注意的是ops結(jié)構(gòu)體指向的函數(shù)指針常常是對數(shù)據(jù)源真正的讀取函數(shù)的一個瘦代理. 在上面兩個例子中, 標(biāo)準(zhǔn)I/O流使用posix的read()函數(shù), 而zlib流使用的是libz的gzread()函數(shù).

你可能還注意到了, 這里使用了stream->abstract元素. 這是流實現(xiàn)的一個便利指針, 它可以被用于獲取各種相關(guān)的捆綁信息. 在上面的例子中, 指向自定義結(jié)構(gòu)體的指針, 用于存儲底層read函數(shù)要使用的文件描述符.

還有一件你可能注意到的事情是php_stream_ops結(jié)構(gòu)體中的每個函數(shù)都期望一個已有的流實例, 但是怎樣得到實例呢? abstract成員是怎樣設(shè)置的以及什么時候流指示使用哪個ops結(jié)構(gòu)體? 答案就在你在上一章使用過的第一個打開流的函數(shù)(php_stream_open_wrapper())中.

當(dāng)這個函數(shù)被調(diào)用時, php的流包裝層嘗試基于傳遞的URL中的scheme://部分確定請求的是什么協(xié)議. 這樣它就可以在已注冊的php包裝器中查找對應(yīng)的php_stream_wrapper項. 每個php_stream_wrapper結(jié)構(gòu)體都可以取到自己的ops元素, 它指向一個php_stream_wrapper_ops結(jié)構(gòu)體:

typedef struct _php_stream_wrapper_ops {
    php_stream *(*stream_opener)(php_stream_wrapper *wrapper,
                        char *filename, char *mode,
                        int options, char **opened_path,
                        php_stream_context *context
                        STREAMS_DC TSRMLS_DC);
    int (*stream_closer)(php_stream_wrapper *wrapper,
                        php_stream *stream TSRMLS_DC);
    int (*stream_stat)(php_stream_wrapper *wrapper,
                        php_stream *stream,
                        php_stream_statbuf *ssb
                        TSRMLS_DC);
    int (*url_stat)(php_stream_wrapper *wrapper,
                        char *url, int flags,
                        php_stream_statbuf *ssb,
                        php_stream_context *context
                        TSRMLS_DC);
    php_stream *(*dir_opener)(php_stream_wrapper *wrapper,
                        char *filename, char *mode,
                        int options, char **opened_path,
                        php_stream_context *context
                        STREAMS_DC TSRMLS_DC);

    const char *label;

    int (*unlink)(php_stream_wrapper *wrapper, char *url,
                        int options,
                        php_stream_context *context
                        TSRMLS_DC);

    int (*rename)(php_stream_wrapper *wrapper,
                        char *url_from, char *url_to,
                        int options,
                        php_stream_context *context
                        TSRMLS_DC);


    int (*stream_mkdir)(php_stream_wrapper *wrapper,
                        char *url, int mode, int options,
                        php_stream_context *context
                        TSRMLS_DC);
    int (*stream_rmdir)(php_stream_wrapper *wrapper, char *url,
                        int options,
                        php_stream_context *context
                        TSRMLS_DC);
} php_stream_wrapper_ops;

這里, 流包裝層調(diào)用wrapper->ops->stream_opener(), 它將執(zhí)行包裝器特有的操作創(chuàng)建流實例, 賦值恰當(dāng)?shù)膒hp_stream_ops結(jié)構(gòu)體, 綁定相關(guān)的抽象數(shù)據(jù).

dir_opener()函數(shù)和stream_opener()提供相同的基礎(chǔ)服務(wù); 不過, 它是對php_stream_opendir()這個API調(diào)用的響應(yīng), 并且通常會綁定一個不同的php_stream_ops結(jié)構(gòu)體到返回的實例. stat()和close()函數(shù)在這一層上是重復(fù)的, 這樣做是為了給包裝器的這些操作增加協(xié)議特有的邏輯.

其他的函數(shù)則允許執(zhí)行靜態(tài)流操作而不用實際的創(chuàng)建流實例. 回顧這些流API調(diào)用, 它們并不實際返回php_stream對象, 你馬上就會看到它們的細(xì)節(jié).

盡管在php 4.3中引入流包裝層時, url_stat在內(nèi)部作為一個包裝器的ops函數(shù)存在, 但直到php 5.0它才開始被使用. 此外, 最后的3個函數(shù), rename(), stream_mkdir()以及stream_rmdir()一直到php 5.0才引入, 在這個版本之前, 它們并不在包裝器的ops結(jié)構(gòu)中.

包裝器操作

除了url_stat()函數(shù), 包裝器操作中在const char *label元素之前的每個操作都可以用于激活的流實例上. 每個函數(shù)的意義如下:

stream_opener()實例化一個流實例. 當(dāng)某個用戶空間的fopen()函數(shù)被調(diào)用時, 這個函

數(shù)將被調(diào)用. 這個函數(shù)返回的php_stream實例是fopen()函數(shù)返回的

文件資源句柄的內(nèi)部表示. 集成函數(shù)比如file(), file_get_contents(),

file_put_contents(), readfile()等等, 在請求包裝資源時, 都使用這個包

裝器ops.

stream_closer()當(dāng)一個流實例結(jié)束其生命周期時這個函數(shù)被調(diào)用. stream_opener()時

分配的所有資源都應(yīng)該在這個函數(shù)中被釋放.

stream_stat()類似于用戶空間的fstat()函數(shù), 這個函數(shù)應(yīng)該填充ssb結(jié)構(gòu)體(實際上

只包含一個struct statbuf sb結(jié)構(gòu)體成員),

dir_opener()和stream_opener()行為一致, 不過它是調(diào)用opendir()一族的用戶空間

函數(shù)時被調(diào)用的. 目錄流使用的底層流實現(xiàn)和文件流遵循相同的規(guī)則;

不過目錄流只需要返回包含在打開的目錄中找到的文件名的記錄, 它

的大小為struct dirent這個結(jié)構(gòu)體的大小.

靜態(tài)包裝器操作

包裝器操作函數(shù)中的其他函數(shù)是在URI路徑上執(zhí)行原子操作, 具體取決于包裝器協(xié)議. 在php4.3的php_stream_wrapper_ops結(jié)構(gòu)體中只有url_stat()和unlink(); 其他的方式是到php 5.0后才定義的, 編碼時應(yīng)該適時的使用#ifdef塊說明.

url_stat()stat()族函數(shù)使用, 返回文件元數(shù)據(jù), 比如訪問授權(quán), 大小, 類型; 以及

訪問, 修改,創(chuàng)建時間. 盡管這個函數(shù)是在php 4.3引入流包裝層時出現(xiàn)

在php_stream_wrapper_ops結(jié)構(gòu)體中的, 但直到php 5.0才被用戶空

間的stat()函數(shù)使用.

unlink()和posix文件系統(tǒng)的同名函數(shù)語義相同, 它執(zhí)行文件刪除. 如果對于當(dāng)

前的包裝器刪除沒有意義, 比如內(nèi)建的http://包裝器, 這個函數(shù)應(yīng)該被

定義為NULL, 以便內(nèi)核去引發(fā)適當(dāng)?shù)腻e誤消息.

rename()當(dāng)用戶空間的rename()函數(shù)的參數(shù)$from和$to參數(shù)指向的是相同的

底層包裝器實現(xiàn), php則將這個重命名請求分發(fā)到包裝器的rename函

數(shù).

mkdir() & rmdir()這兩個函數(shù)直接映射到對應(yīng)的用戶空間函數(shù).

實現(xiàn)一個包裝器

為了演示包裝器和流操作的內(nèi)部工作原理, 我們需要重新實現(xiàn)php手冊的stream_wrapper_register()一頁示例中的var://包裝器.

此刻, 首先從下面功能完整的變量流包裝實現(xiàn)開始. 構(gòu)建他, 并開始檢查每一塊的工作原理.

譯注: 為了方便大家閱讀, 對代碼的注釋進行了適量補充調(diào)整, 此外, 由于phpapi的調(diào)整, 原著中的代碼不能直接在譯者使用的php-5.4.10中運行, 進行了適當(dāng)?shù)男薷? 因此下面代碼結(jié)構(gòu)可能和原著略有不同, 請參考閱讀.(下面opendir的例子也進行了相應(yīng)的修改)

config.m4

PHP_ARG_ENABLE(varstream,whether to enable varstream support,
[  enable-varstream      Enable varstream support])

if test "$PHP_VARSTREAM" = "yes"; then
  AC_DEFINE(HAVE_VARSTREAM,1,[Whether you want varstream])
  PHP_NEW_EXTENSION(varstream, varstream.c, $ext_shared)
fi

php_varstream.h

#ifndef PHP_VARSTREAM_H
#define PHP_VARSTREAM_H

extern zend_module_entry varstream_module_entry;
#define phpext_varstream_ptr &varstream_module_entry

#ifdef PHP_WIN32
#   define PHP_VARSTREAM_API __declspec(dllexport)
#elif defined(__GNUC__) && __GNUC__ >= 4
#   define PHP_VARSTREAM_API __attribute__ ((visibility("default")))
#else
#   define PHP_VARSTREAM_API
#endif

#ifdef ZTS
#include "TSRM.h"
#endif

PHP_MINIT_FUNCTION(varstream);
PHP_MSHUTDOWN_FUNCTION(varstream);

#define PHP_VARSTREAM_WRAPPER       "var"
#define PHP_VARSTREAM_STREAMTYPE    "varstream"

/* 變量流的抽象數(shù)據(jù)結(jié)構(gòu) */
typedef struct _php_varstream_data {
    off_t   position;
    char    *varname;
    int     varname_len;
} php_varstream_data;

#ifdef ZTS
#define VARSTREAM_G(v) TSRMG(varstream_globals_id, zend_varstream_globals *, v)
#else
#define VARSTREAM_G(v) (varstream_globals.v)
#endif

#endif

varstream.c

#ifdef HAVE_CONFIG_H
#include "config.h"
#endif

#include "php.h"
#include "php_ini.h"
#include "ext/standard/info.h"
#include "ext/standard/url.h"
#include "php_varstream.h"

static size_t php_varstream_write(php_stream *stream,
                const char *buf, size_t count TSRMLS_DC)
{
    php_varstream_data *data = stream->abstract;
    zval **var;
    size_t newlen;

    /* 查找變量 */
    if (zend_hash_find(&EG(symbol_table), data->varname,
            data->varname_len + 1,(void**)&var) == FAILURE) {
        /* 變量不存在, 直接創(chuàng)建一個字符串類型的變量, 并保存新傳遞進來的內(nèi)容 */
       zval *newval;
       MAKE_STD_ZVAL(newval);
       ZVAL_STRINGL(newval, buf, count, 1); 
       /* 將新的zval *放到變量中 */
       zend_hash_add(&EG(symbol_table), data->varname,
           data->varname_len + 1, (void*)&newval,
           sizeof(zval*), NULL);
       return count;
    }   
    /* 如果需要, 讓變量可寫. 這里實際上處理的是寫時復(fù)制 */
    SEPARATE_ZVAL_IF_NOT_REF(var);
    /* 轉(zhuǎn)換為字符串類型 */
    convert_to_string_ex(var);
    /* 重置偏移量(譯注: 相比于正常的文件系統(tǒng), 這里的處理實際上不支持文件末尾的空洞創(chuàng)建, 讀者如果熟悉*nix文件系統(tǒng), 應(yīng)該了解譯者所說, 否則請略過) */
    if (data->position > Z_STRLEN_PP(var)) {
        data->position = Z_STRLEN_PP(var);
    }   
    /* 計算新的字符串長度 */
    newlen = data->position + count;
    if (newlen < Z_STRLEN_PP(var)) {
        /* 總長度不變 */
        newlen = Z_STRLEN_PP(var);
    } else if (newlen > Z_STRLEN_PP(var)) {
        /* 重新調(diào)整緩沖區(qū)大小以保存新內(nèi)容 */
        Z_STRVAL_PP(var) =erealloc(Z_STRVAL_PP(var),newlen+1);
        /* 更新字符串長度 */
        Z_STRLEN_PP(var) = newlen;
        /* 確保字符串NULL終止 */
        Z_STRVAL_PP(var)[newlen] = 0;
    }   
    /* 將數(shù)據(jù)寫入到變量中 */
    memcpy(Z_STRVAL_PP(var) + data->position, buf, count);
    data->position += count;

    return count;
}

static size_t php_varstream_read(php_stream *stream,
                char *buf, size_t count TSRMLS_DC)
{
    php_varstream_data *data = stream->abstract;
    zval **var, copyval;
    int got_copied = 0;
    size_t toread = count;

    if (zend_hash_find(&EG(symbol_table), data->varname,
        data->varname_len + 1, (void**)&var) == FAILURE) {
        /* 變量不存在, 讀不到數(shù)據(jù), 返回0字節(jié)長度 */
        return 0;
    }   
    copyval = **var;
    if (Z_TYPE(copyval) != IS_STRING) {
        /* 對于非字符串類型變量, 創(chuàng)建一個副本進行讀, 這樣對于只讀的變量, 就不會改變其原始類型 */
        zval_copy_ctor(?val);
        INIT_PZVAL(?val);
        got_copied = 1;
    }   
    if (data->position > Z_STRLEN(copyval)) {
        data->position = Z_STRLEN(copyval);
    }   
    if ((Z_STRLEN(copyval) - data->position) < toread) {
        /* 防止讀取到變量可用緩沖區(qū)外的內(nèi)容 */
        toread = Z_STRLEN(copyval) - data->position;
    }   
    /* 設(shè)置緩沖區(qū) */
    memcpy(buf, Z_STRVAL(copyval) + data->position, toread);
    data->position += toread;

    /* 如果創(chuàng)建了副本, 則釋放副本 */
    if (got_copied) {
        zval_dtor(?val);
    }   

    /* 返回設(shè)置到緩沖區(qū)的字節(jié)數(shù) */
    return toread;
}

static int php_varstream_closer(php_stream *stream,
                            int close_handle TSRMLS_DC)
{
    php_varstream_data *data = stream->abstract;

    /* 釋放內(nèi)部結(jié)構(gòu)避免泄露 */
    efree(data->varname);
    efree(data);

    return 0;
}

static int php_varstream_flush(php_stream *stream TSRMLS_DC)
{
    php_varstream_data *data = stream->abstract;
    zval **var;

    /* 根據(jù)不同情況, 重置偏移量 */
    if (zend_hash_find(&EG(symbol_table), data->varname,
                    data->varname_len + 1, (void**)&var)
                    == SUCCESS) {
        if (Z_TYPE_PP(var) == IS_STRING) {
            data->position = Z_STRLEN_PP(var);
        } else {
            zval copyval = **var;
            zval_copy_ctor(?val);
            convert_to_string(?val);
            data->position = Z_STRLEN(copyval);
            zval_dtor(?val);
        }
    } else {
        data->position = 0;
    }

    return 0;
}

static int php_varstream_seek(php_stream *stream, off_t offset,
                    int whence, off_t *newoffset TSRMLS_DC)
{
    php_varstream_data *data = stream->abstract;

    switch (whence) {
        case SEEK_SET:
            data->position = offset;
            break;
        case SEEK_CUR:
            data->position += offset;
            break;
        case SEEK_END:
        {
            zval **var;
           size_t curlen = 0;

           if (zend_hash_find(&EG(symbol_table),
                   data->varname,    data->varname_len + 1,
                   (void**)&var) == SUCCESS) {
              if (Z_TYPE_PP(var) == IS_STRING) {
                  curlen = Z_STRLEN_PP(var);
              } else {
                  zval copyval = **var;
                  zval_copy_ctor(?val);
                  convert_to_string(?val);
                  curlen = Z_STRLEN(copyval);
                  zval_dtor(?val);
              }
           }

           data->position = curlen + offset;
           break;
       }
    }

    /* 防止隨機訪問指針移動到緩沖區(qū)開始位置之前 */
    if (data->position < 0) {
        data->position = 0;
    }

    if (newoffset) {
        *newoffset = data->position;
    }

    return 0;
}

static php_stream_ops php_varstream_ops = {
    php_varstream_write,
    php_varstream_read,
    php_varstream_closer,
    php_varstream_flush,
    PHP_VARSTREAM_STREAMTYPE,
    php_varstream_seek,
    NULL, /* cast */
    NULL, /* stat */
    NULL, /* set_option */
};

/* Define the wrapper operations */
static php_stream *php_varstream_opener(
            php_stream_wrapper *wrapper,
            char *filename, char *mode, int options,
            char **opened_path, php_stream_context *context
            STREAMS_DC TSRMLS_DC)
{
    php_varstream_data *data;
    php_url *url;

    if (options & STREAM_OPEN_PERSISTENT) {
        /* 按照變量流的定義, 是不能持久化的
         * 因為變量在請求結(jié)束后將被釋放
         */
        php_stream_wrapper_log_error(wrapper, options
            TSRMLS_CC, "Unable to open %s persistently",
                                        filename);
        return NULL;
    }

    /* 標(biāo)準(zhǔn)URL解析: scheme://user:pass@host:port/path?query#fragment */
    url = php_url_parse(filename);
    if (!url) {
        php_stream_wrapper_log_error(wrapper, options
            TSRMLS_CC, "Unexpected error parsing URL");
        return NULL;
    }
    /* 檢查是否有變量流URL必須的元素host, 以及scheme是否是var */
    if (!url->host || (url->host[0] == 0) ||
        strcasecmp("var", url->scheme) != 0) {
        /* Bad URL or wrong wrapper */
        php_stream_wrapper_log_error(wrapper, options
            TSRMLS_CC, "Invalid URL, must be in the form: "
                     "var://variablename");
        php_url_free(url);
        return NULL;
    }

    /* 創(chuàng)建一個數(shù)據(jù)結(jié)構(gòu)保存協(xié)議信息(變量流協(xié)議重要是變量名, 變量名長度, 當(dāng)前偏移量) */
    data = emalloc(sizeof(php_varstream_data));
    data->position = 0;
    data->varname_len = strlen(url->host);
    data->varname = estrndup(url->host, data->varname_len + 1);
    /* 釋放前面解析出來的url占用的內(nèi)存 */
    php_url_free(url);

    /* 實例化一個流, 為其賦予恰當(dāng)?shù)牧鱫ps, 綁定抽象數(shù)據(jù) */
    return php_stream_alloc(&php_varstream_ops, data, 0, mode);
}

static php_stream_wrapper_ops php_varstream_wrapper_ops = {
    php_varstream_opener, /* 調(diào)用php_stream_open_wrapper(sprintf("%s://xxx", PHP_VARSTREAM_WRAPPER))時執(zhí)行 */
    NULL, /* stream_close */
    NULL, /* stream_stat */
    NULL, /* url_stat */
    NULL, /* dir_opener */
    PHP_VARSTREAM_WRAPPER,
    NULL, /* unlink */
#if PHP_MAJOR_VERSION >= 5
    /* PHP >= 5.0 only */
    NULL, /* rename */
    NULL, /* mkdir */
    NULL, /* rmdir */
#endif
};

static php_stream_wrapper php_varstream_wrapper = {
    &php_varstream_wrapper_ops,
    NULL, /* abstract */
    0, /* is_url */
};

PHP_MINIT_FUNCTION(varstream)
{
    /* 注冊流包裝器:
     * 1. 檢查流包裝器名字是否正確(符合這個正則: /^[a-zA-Z0-9+.-]+$/)
     * 2. 將傳入的php_varstream_wrapper增加到url_stream_wrappers_hash這個HashTable中, key為PHP_VARSTREAM_WRAPPER
     */
    if (php_register_url_stream_wrapper(PHP_VARSTREAM_WRAPPER,
            &php_varstream_wrapper TSRMLS_CC)==FAILURE) {
        return FAILURE;
    }
    return SUCCESS;
}

PHP_MSHUTDOWN_FUNCTION(varstream)
{
    /* 卸載流包裝器: 從url_stream_wrappers_hash中刪除 */
    if (php_unregister_url_stream_wrapper(PHP_VARSTREAM_WRAPPER
                                TSRMLS_CC) == FAILURE) {
        return FAILURE;
    }
    return SUCCESS;
}

zend_module_entry varstream_module_entry = {
#if ZEND_MODULE_API_NO >= 20010901
    STANDARD_MODULE_HEADER,
#endif
    "varstream",
    NULL,
    PHP_MINIT(varstream),
    PHP_MSHUTDOWN(varstream),
    NULL,
    NULL,
    NULL,
#if ZEND_MODULE_API_NO >= 20010901
    "0.1",
#endif
    STANDARD_MODULE_PROPERTIES
};

#ifdef COMPILE_DL_VARSTREAM
ZEND_GET_MODULE(varstream)
#endif

在構(gòu)建加載擴展后, php就可以處理以var://開始的URL的請求, 它的行為和手冊中用戶空間實現(xiàn)的行為一致.

內(nèi)部實現(xiàn)

首先你注意到的可能是這個擴展完全沒有暴露用戶空間函數(shù). 它所做的只是在MINIT函數(shù)中調(diào)用了一個核心PHPAPI的鉤子, 將var協(xié)議和我們定義的包裝器關(guān)聯(lián)起來:

static php_stream_wrapper php_varstream_wrapper = {
    &php_varstream_wrapper_ops,
    NULL, /* abstract */
    0, /* is_url */
}

很明顯, 最重要的元素就是ops, 它提供了訪問特定流包裝器的創(chuàng)建以及檢查函數(shù). 你可以安全的忽略abstract屬性, 它僅在運行時使用, 在初始化定義時, 它只是作為一個占位符. 第三個元素is_url, 它告訴php在使用這個包裝器時是否考慮php.ini中的allow_url_fopen選項. 如果這個值非0, 并且將allow_url_fopen設(shè)置為false, 則這個包裝器不能被腳本使用.

在本章前面你已經(jīng)知道, 調(diào)用用戶空間函數(shù)比如fopen將通過這個包裝器的ops元素得到php_varstream_wrapper_ops, 這樣去調(diào)用流的打開函數(shù)php_varstream_opener.

這個函數(shù)的第一塊代碼檢查是否請求持久化的流:

if (options & STREAM_OPEN_PERSISTENT) {

對于很多包裝器這樣的請求是合法的. 然而目前的情況這個行為沒有意義. 一方面用戶空間變量的定義就是臨時的, 另一方面, varstream的實例化代價很低, 這就使得持久化的優(yōu)勢很小.

像流包裝層報告錯誤很簡單, 只需要返回一個NULL值而不是流實例即可. 流包裝層透出到用戶空間的失敗消息并不會說明具體的錯誤, 只是說明不能打開URL. 要想給開發(fā)者暴露更多的錯誤信息, 可以在返回之前使用php_stream_wrapper_log_error()函數(shù).

php_stream_wrapper_log_error(wrapper, options
    TSRMLS_CC, "Unable to open %s persistently",
                                filename);
return NULL;

URL解析

實例化varstream的下一步需要一個人類可讀的URL, 將它分塊放入到一個易管理的結(jié)構(gòu)體中. 幸運的是它使用了和用戶空間url_parse()函數(shù)相同的機制. 如果URL成功解析, 將會分配一個php_url結(jié)構(gòu)體并設(shè)置合適的值. 如果在URL中沒有某些值, 在返回的php_url中對應(yīng)的將被設(shè)置為NULL. 這個結(jié)構(gòu)體必須在離開php_varstream_opener函數(shù)之前被顯式釋放, 否則它的內(nèi)存將會泄露:

typedef struct php_url {
    /* scheme://user:pass@host:port/path?query#fragment */
    char *scheme;
    char *user;
    char *pass;
    char *host;
    unsigned short port;
    char *path;
    char *query;
    char *fragment;
} php_url;

最后, varstream包裝器創(chuàng)建了一個數(shù)據(jù)結(jié)構(gòu), 保存了流指向的變量名, 讀取時的當(dāng)前位置. 這個結(jié)構(gòu)體將在流的讀取和寫入函數(shù)中用于獲取變量, 并且將在流結(jié)束使用時由php_varstream_close函數(shù)釋放.

opendir()

讀寫變量內(nèi)容的實現(xiàn)可以再次進行擴展. 這里可以加入一個新的特性, 允許使用目錄函數(shù)讀取數(shù)組中的key. 在你的php_varstream_wrapper_ops結(jié)構(gòu)體之前增加下面的代碼:

static size_t php_varstream_readdir(php_stream *stream,
                char *buf, size_t count TSRMLS_DC)
{
    php_stream_dirent *ent = (php_stream_dirent*)buf;
    php_varstream_dirdata *data = stream->abstract;
    char *key;
    int type, key_len;
    long idx;

    /* 查找數(shù)組中的key */
    type = zend_hash_get_current_key_ex(Z_ARRVAL_P(data->arr),
                    &key, &key_len, &idx, 0, &(data->pos));

    /* 字符串key */
    if (type == HASH_KEY_IS_STRING) {
        if (key_len >= sizeof(ent->d_name)) {
            /* truncate long keys to maximum length */
            key_len = sizeof(ent->d_name) - 1;
        }
        /* 設(shè)置到目錄結(jié)構(gòu)上 */
        memcpy(ent->d_name, key, key_len);
        ent->d_name[key_len] = 0;
    /* 數(shù)值key */
    } else if (type == HASH_KEY_IS_LONG) {
        /* 設(shè)置到目錄結(jié)構(gòu)上 */
        snprintf(ent->d_name, sizeof(ent->d_name), "%ld",idx);
    } else {
        /* 迭代結(jié)束 */
        return 0;
    }
    /* 移動數(shù)組指針(位置記錄到流的抽象結(jié)構(gòu)中) */
    zend_hash_move_forward_ex(Z_ARRVAL_P(data->arr),
                                        &data->pos);
    return sizeof(php_stream_dirent);
}

static int php_varstream_closedir(php_stream *stream,
                            int close_handle TSRMLS_DC)
{
    php_varstream_dirdata *data = stream->abstract;

    zval_ptr_dtor(&(data->arr));
    efree(data);
    return 0;
}

static int php_varstream_dirseek(php_stream *stream,
                    off_t offset, int whence,
                    off_t *newoffset TSRMLS_DC)
{
    php_varstream_dirdata *data = stream->abstract;

    if (whence == SEEK_SET && offset == 0) {
        /* 重置數(shù)組指針 */
        zend_hash_internal_pointer_reset_ex(
                    Z_ARRVAL_P(data->arr), &(data->pos));
        if (newoffset) {
            *newoffset = 0;
        }
        return 0;
    }
    /* 不支持其他類型的隨機訪問 */
    return -1;
}

static php_stream_ops php_varstream_dirops = {
    NULL, /* write */
    php_varstream_readdir,
    php_varstream_closedir,
    NULL, /* flush */
    PHP_VARSTREAM_DIRSTREAMTYPE,
    php_varstream_dirseek,
    NULL, /* cast */
    NULL, /* stat */
    NULL, /* set_option */
};

static php_stream *php_varstream_opendir(
            php_stream_wrapper *wrapper,
            char *filename, char *mode, int options,
            char **opened_path, php_stream_context *context
            STREAMS_DC TSRMLS_DC)
{
    php_varstream_dirdata *data;
    php_url *url;
    zval **var;

    /* 不支持持久化流 */
    if (options & STREAM_OPEN_PERSISTENT) {
        php_stream_wrapper_log_error(wrapper, options
                TSRMLS_CC, "Unable to open %s persistently",
                filename);
        return NULL;
    }

    /* 解析URL */
    url = php_url_parse(filename);
    if (!url) {
        php_stream_wrapper_log_error(wrapper, options
                TSRMLS_CC, "Unexpected error parsing URL");
        return NULL;
    }
    /* 檢查請求URL的正確性 */
    if (!url->host || (url->host[0] == 0) ||
            strcasecmp("var", url->scheme) != 0) {
        /* Bad URL or wrong wrapper */
        php_stream_wrapper_log_error(wrapper, options
                TSRMLS_CC, "Invalid URL, must be in the form: "
                "var://variablename");
        php_url_free(url);
        return NULL;
    }

    /* 查找變量 */
    if (zend_hash_find(&EG(symbol_table), url->host,
                strlen(url->host) + 1, (void**)&var) == FAILURE) {
        php_stream_wrapper_log_error(wrapper, options
                TSRMLS_CC, "Variable $%s not found", url->host);
        php_url_free(url);
        return NULL;
    }

    /* 檢查變量類型 */
    if (Z_TYPE_PP(var) != IS_ARRAY) {
        php_stream_wrapper_log_error(wrapper, options
                TSRMLS_CC, "$%s is not an array", url->host);
        php_url_free(url);
        return NULL;
    }
    /* 釋放前面分配的URL結(jié)構(gòu) */
    php_url_free(url);

    /* 分配抽象數(shù)據(jù)結(jié)構(gòu) */
    data = emalloc(sizeof(php_varstream_dirdata));
    if ( Z_ISREF_PP(var) && Z_REFCOUNT_PP(var) > 1) {
        /* 全拷貝 */
        MAKE_STD_ZVAL(data->arr);
        *(data->arr) = **var;
        zval_copy_ctor(data->arr);
        INIT_PZVAL(data->arr);
    } else {
        /* 寫時拷貝 */
        data->arr = *var;
        Z_SET_REFCOUNT_P(data->arr, Z_REFCOUNT_P(data->arr) + 1);
    }
    /* 重置數(shù)組指針 */
    zend_hash_internal_pointer_reset_ex(Z_ARRVAL_P(data->arr),
            &data->pos);
    return php_stream_alloc(&php_varstream_dirops,data,0,mode);
}

現(xiàn)在, 將你的php_varstream_wrapper_ops結(jié)構(gòu)體中的dir_opener的NULL替換成你的php_varstream_opendir函數(shù). 最后, 將下面新定義的類型放入到你的php_varstream.h文件的php_varstream_data定義下面:

#define PHP_VARSTREAM_DIRSTREAMTYPE    "varstream directory"
typedef struct _php_varstream_dirdata {
    zval *arr;
    HashPosition pos;
} php_varstream_dirdata;

在你基于fopen()實現(xiàn)的varstream包裝器中, 你直接使用持久變量名, 每次執(zhí)行讀寫操作時從符號表中獲取變量. 而這里, opendir()的實現(xiàn)中獲取變量時處理了變量不存在或者類型錯誤的異常. 你還有一個數(shù)組變量的拷貝, 這就說明原數(shù)組的改變并不會影響后續(xù)的readdir()調(diào)用的結(jié)果. 原來存儲變量名的方式也可以正常工作, 這里只是給出另外一種選擇作為演示示例.

由于目錄訪問是基于成塊的目錄條目, 而不是字符, 因此這里需要一套獨立的流操作. 這個版本中, write沒有意義, 因此保持它為NULL. read的實現(xiàn)使用zend_hash_get_current_key_ex()函數(shù)將數(shù)組映射到目錄名. 而隨機訪問也只是對SEEK_SET有效, 用來響應(yīng)rewinddir()跳轉(zhuǎn)到數(shù)組開始位置.

實際上, 目錄流并沒有使用SEEK_CUR, SEEK_END, 或者除了0之外的偏移量. 在實現(xiàn)目錄流操作時, 最好還是涉及你的函數(shù)能以某種方式處理這些情況, 以使得在流包裝層變化時能夠適應(yīng)其目錄隨機訪問.

操縱

5個靜態(tài)包裝器操作中的4個用來處理不是基于I/O的流資源操作. 你已經(jīng)看到過它們并了解它們的原型; 現(xiàn)在我們看看varstream包裝器框架中它們的實現(xiàn):

unlink

在你的wrapper_ops結(jié)構(gòu)體中增加下面的函數(shù), 它可以讓unlink()通過varstream包裝器, 擁有和unset()一樣的行為:

static int php_varstream_unlink(php_stream_wrapper *wrapper,
                        char *filename, int options,
                        php_stream_context *context
                        TSRMLS_DC)
{               
    php_url *url;   
                        
    url = php_url_parse(filename);
    if (!url) {         
        php_stream_wrapper_log_error(wrapper, options
            TSRMLS_CC, "Unexpected error parsing URL");
        return -1;   
    }       
    if (!url->host || (url->host[0] == 0) ||
        strcasecmp("var", url->scheme) != 0) {
        /* URL不合法 */
        php_stream_wrapper_log_error(wrapper, options
            TSRMLS_CC, "Invalid URL, must be in the form: "
                     "var://variablename");
        php_url_free(url);
        return -1;
    }
    
    /* 從符號表刪除變量 */
    //zend_hash_del(&EG(symbol_table), url->host, strlen(url->host) + 1);
    zend_delete_global_variable(url->host, strlen(url->host) + 1 TSRMLS_CC);
    
    php_url_free(url);                                      
    return 0;
}

這個函數(shù)的編碼量和php_varstream_opener差不多. 唯一的不同在于這里你需要傳遞變量名給zend_hash_del()去刪除變量.

譯注: 譯者的php-5.4.10環(huán)境中, 使用unlink()刪除變量后, 在用戶空間再次讀取該變量名的值會導(dǎo)致core dump. 因此上面代碼中譯者進行了修正, 刪除變量時使用了zend_delete_global_variable(), 請讀者參考閱讀zend_delete_global_variable()函數(shù)源代碼, 考慮為什么直接用zend_hash_del()刪除, 會導(dǎo)致core dump. 下面是譯者測試用的用戶空間代碼:

<?php
$fp = fopen(&#39;var://hello&#39;, &#39;r&#39;);
fwrite($fp, &#39;world&#39;);
var_dump($hello);
unlink(&#39;var://hello&#39;);
$a  = $hello;

這個函數(shù)的代碼量應(yīng)該和php_varstream_opener差不多. 唯一的不同是這里是傳遞變量名給zend_hash_del()去刪除變量.

rename, mkdir, rmdir

為了一致性, 下面給出rename, mkdir, rmdir函數(shù)的實現(xiàn):

static int php_varstream_rename(php_stream_wrapper *wrapper,
        char *url_from, char *url_to, int options,
        php_stream_context *context TSRMLS_DC)
{
    php_url *from, *to;
    zval **var;

    /* 來源URL解析 */
    from = php_url_parse(url_from);
    if (!from) {
        php_stream_wrapper_log_error(wrapper, options
            TSRMLS_CC, "Unexpected error parsing source");
        return -1;
    }
    /* 查找變量 */
    if (zend_hash_find(&EG(symbol_table), from->host,
                strlen(from->host) + 1,
                (void**)&var) == FAILURE) {
        php_stream_wrapper_log_error(wrapper, options
            TSRMLS_CC, "$%s does not exist", from->host);
        php_url_free(from);
        return -1;
    }
    /* 目標(biāo)URL解析 */
    to = php_url_parse(url_to);
    if (!to) {
        php_stream_wrapper_log_error(wrapper, options
            TSRMLS_CC, "Unexpected error parsing dest");
        php_url_free(from);
        return -1;
    }
    /* 變量的改名 */
    Z_SET_REFCOUNT_PP(var, Z_REFCOUNT_PP(var) + 1);
    zend_hash_update(&EG(symbol_table), to->host,
                strlen(to->host) + 1, (void*)var,
                sizeof(zval*), NULL);
    zend_hash_del(&EG(symbol_table), from->host,
                strlen(from->host) + 1);
    php_url_free(from);
    php_url_free(to);
    return 0;
}

static int php_varstream_mkdir(php_stream_wrapper *wrapper,
                char *url_from, int mode, int options,
                php_stream_context *context TSRMLS_DC)
{
    php_url *url;

    /* URL解析 */
    url = php_url_parse(url_from);
    if (!url) {
       php_stream_wrapper_log_error(wrapper, options
           TSRMLS_CC, "Unexpected error parsing URL");
       return -1;
    }

    /* 檢查變量是否存在 */
    if (zend_hash_exists(&EG(symbol_table), url->host,
                    strlen(url->host) + 1)) {
        php_stream_wrapper_log_error(wrapper, options
            TSRMLS_CC, "$%s already exists", url->host);
        php_url_free(url);
        return -1;
    }
    /* EG(uninitialized_zval_ptr)通常是IS_NULL的zval *, 引用計數(shù)無限大 */
    zend_hash_add(&EG(symbol_table), url->host,
            strlen(url->host) + 1,
            (void*)&EG(uninitialized_zval_ptr),
            sizeof(zval*), NULL);
    php_url_free(url);
    return 0;
}

static int php_varstream_rmdir(php_stream_wrapper *wrapper,
                char *url, int options,
                php_stream_context *context TSRMLS_DC)
{
    /* 行為等價于unlink() */
    wrapper->wops->unlink(wrapper, url, options,
                                context TSRMLS_CC);
}

檢查

并不是所有的流操作都涉及到資源的操縱. 有時候也需要查看活動的流在某個時刻的狀態(tài), 或檢查潛在可打開的資源的狀態(tài).

這一節(jié)流和包裝器的ops函數(shù)都是在相同的數(shù)據(jù)結(jié)構(gòu)php_stream_statbuf上工作的, 它只有一個元素: posix標(biāo)準(zhǔn)的struct statbuf. 當(dāng)本節(jié)的某個函數(shù)被調(diào)用時, 將嘗試填充盡可能多的statbuf元素的成員.

stat

如果設(shè)置, 當(dāng)請求激活流實例的信息時, 將會調(diào)用wrapper->ops->stream_stat(). 如果沒有設(shè)置, 則對應(yīng)的stream->ops->stat()將會被調(diào)用. 無論哪個函數(shù)被調(diào)用, 都應(yīng)該盡可能多的向返回的statbuf結(jié)構(gòu)體ssb->sb中填充盡可能多流實例的有用信息. 在普通文件I/O的用法中, 它對應(yīng)fstat()的標(biāo)準(zhǔn)I/O調(diào)用.

url_stat

在流實例外部調(diào)用wrapper->ops->url_stat()取到流資源的元數(shù)據(jù). 通常來說, 符號鏈接和重定向都應(yīng)該被解析, 直到找到一個真正的資源, 對其通過stat()系統(tǒng)調(diào)用這樣的機制讀取統(tǒng)計信息. url_stat的flags參數(shù)允許是下面PHP_STREAM_URL_STAT_*系列的常量值(省略PHP_STREAM_URL_STAT_前綴):

LINK不解析符號鏈接和重定向. 而是報告它碰到的第一個節(jié)點的信息, 無論是連

接還是真正的資源.

QUIET不報告錯誤. 注意, 這和許多其他流函數(shù)中的REPORT_ERRORS邏輯恰恰

相反.

小結(jié)

無論是暴露遠(yuǎn)程網(wǎng)絡(luò)I/O還是本地數(shù)據(jù)源的流資源, 都允許你的擴展在核心數(shù)據(jù)上掛在操縱函數(shù)的鉤子, 避免重新實現(xiàn)單調(diào)的描述符管理和I/O緩沖區(qū)工作. 這使得它在用戶空間環(huán)境中更加有用, 更加強大.

下一章將通過對過濾器和上下文的學(xué)習(xí)結(jié)束流包裝層的學(xué)習(xí), 過濾器和上下文可以用于選擇默認(rèn)的流行為, 甚至過程中修改數(shù)據(jù).

以上就是[翻譯][php擴展開發(fā)和嵌入式]第15章-php中流的實現(xiàn)的內(nèi)容，更多相關(guān)內(nèi)容請關(guān)注PHP中文網(wǎng)（miracleart.cn）！