Implementing a Wrapper

To illustrate the internal workings of wrappers and stream operations, you'll be reimplementing the var:// wrapper described in the PHP manual's stream_wrapper_register() page.

This time, start with the following, fully functional, variable stream wrapper implementation. Once built, you can start examining the workings of each individual piece (see Listings 14.1, 14.2, and 14.3).

Listing 14.1. config.m4

Listing 14.2. php_varstream.h

Listing 14.3. varstream.c

After building and loading the extension, PHP will be aware of, and ready to dispatch stream requests for, URLs beginning with var:// mimicking all the behavior found in the matching userspace implementation.

Inside the Implementation

The first thing you'll notice about this extension is that it exports absolutely no userspace functions whatsoever. What is does do is call into a core PHPAPI hook from its MINIT method to associate a scheme namevar in this casewith a short and simple wrapper definition structure.

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

The most important element here is, obviously, the ops element, which provides access to the wrapper-specific stream creation and inspection functions. You can safely ignore the abstract property as it's only used during runtime and exists in the initial declaration as simply a placeholder. The third element, is_url, tells PHP whether or not the allow_url_fopen option in the php.ini should be considered when using this wrapper. If this value is nonzero and allow_url_fopen is set to false, this wrapper will be unavailable to running scripts.

As you already know from earlier in this chapter, calls to userspace functions such as fopen() will follow this wrapper through its ops element to php_varstream_wrapper_ops, where it can call the stream opener function, php_varstream_opener.

The first block of code used by this method checks to see whether a persistent stream has been requested:

if (options & STREAM_OPEN_PERSISTENT) {

For many wrappers such a request is perfectly valid; however, in this case such behavior simply doesn't make sense. Userspace variables are ephemeral by definition and the relative cheapness of instantiating a varstream makes the advantages of using persistency negligible.

Reporting failure to the streams layer requires nothing more than returning a NULL value from the method rather than a stream instance. As the failure bubbles its way up to userspace, the streams layer will generate a nondescript failure message saying that it was unable to open the URL. To give the developer more detailed information, you'd use the php_stream_wrapper_log_error() function prior to returning:

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

URL Parsing

The next step in instantiating varstream requires taking the human readable URL, and chunking it up into manageable pieces. Fortunately, the same mechanism used by the userspace url_parse() function is available as an internal API call. If the URL can be successfully parsed, a php_url structure will be allocated and populated with the appropriate values. If a particular value is not present in the URL, its value will be set to NULL. This structure must be explicitly freed before leaving the php_varstream_opener function, or its memory will be leaked.

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;

Finally, the varstream wrapper creates a data structure to hold the name of the variable being streamed, and its current locationfor read streams. This structure will be used by the stream's read and write functions to locate the variable to act upon, and will be freed during stream shutdown by the php_varstream_close method.

opendir()

This example could be extended beyond the basic implementation of reading and writing variable contents. One new feature might be to allow the use of the directory functions to read through the keys in an array. Add the following code prior to your existing php_varstream_wrapper_ops structure:

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; type = zend_hash_get_current_key_ex(Z_ARRVAL_P(data->arr), &key, &key_len, &idx, 0, &(data->pos)); 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; } memcpy(ent->d_name, key, key_len); ent->d_name[key_len] = 0; } else if (type == HASH_KEY_IS_LONG) { snprintf(ent->d_name, sizeof(ent->d_name), "%ld",idx); } else { /* No more keys */ return 0; } 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) { /* rewinddir() */ zend_hash_internal_pointer_reset_ex( Z_ARRVAL_P(data->arr), &(data->pos)); if (newoffset) { *newoffset = 0; } return 0; } /* Other types of seeking not supported */ 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 = php_url_parse(filename); if (!url) { php_stream_wrapper_log_error(wrapper, options TSRMLS_CC, "Unexpected error parsing URL"); return NULL; } 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; } php_url_free(url); data = emalloc(sizeof(php_varstream_dirdata)); if ((*var)->is_ref && (*var)->refcount > 1) { /* Make a full copy */ MAKE_STD_ZVAL(data->arr); *(data->arr) = **var; zval_copy_ctor(data->arr); INIT_PZVAL(data->arr); } else { /* Put in copy-on-write set */ data->arr = *var; ZVAL_ADDREF(data->arr); } zend_hash_internal_pointer_reset_ex(Z_ARRVAL_P(data->arr), &data->pos); return php_stream_alloc(&php_varstream_dirops,data,0,mode); }

Now, replace the NULL entry in your php_varstream_wrapper_ops structure for dir_opener with a reference to your php_varstream_opendir method. Lastly, add the new defines and types used in this code block to your php_varstream.h file following the definition of php_varstream_data:

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

In the fopen()-based implementation of your varstream wrapper, you simply referenced the name of the variable and fetched it from the symbol table each time a read or write operation was performed. This time, you fetched the variable during the opendir() implementation allowing errors such as the variable not existing or being of the wrong type to be handled immediately. You also made a point-in-time copy of the array variable, meaning that any changes to the original array will not change the results of subsequent readdir() calls. The original approachstoring the variable namewould have worked just as well; this alternative is simply provided for illustration.

Because directory access is based on blocksdirectory entriesrather than characters, a separate set of stream operations is necessary. For this version, write has no meaning so you're able to simply leave it as NULL. read is implemented as a method that uses the zend_hash_get_current_key_ex() method to map the array indices to directory names. And seek focuses on the SEEK_SET whence to jump to the start of the array in response to calls to rewinddir().

Note

In practice, directory streams never use SEEK_SET, SEEK_END, or an offset other than 0. When implementing directory stream operations, however, it's best to design your method with some way to handle these cases should the streams layer ever change to accommodate the notion of true directory seeking.