📄 internals2.ze1.streams.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"><html> <head> <title>Streams API for PHP Extension Authors</title> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> </head> <body><div style="text-align: center;"> <div class="prev" style="text-align: left; float: left;"><a href="internals2.ze1.html">Zend Engine 1</a></div> <div class="next" style="text-align: right; float: right;"><a href="internals2.ze1.zendapi.html">Zend API: Hacking the Core of PHP</a></div> <div class="up"><a href="internals2.ze1.html">Zend Engine 1</a></div> <div class="home"><a href="index.html">PHP Manual</a></div></div><hr /><div id="internals2.ze1.streams" class="sect1"> <h2 class="title">Streams API for PHP Extension Authors</h2> <p class="para"> <blockquote><p><b class="note">Note</b>: The functions in this chapter are for use in the PHP source code and are not PHP functions. Information on userland stream functions can be found in the <a href="book.stream.html" class="link">Stream Reference</a>. <br /> </p></blockquote> </p> <div id="internals2.ze1.streams.overview" class="sect2"> <h3 class="title">Overview</h3> <p class="para"> The PHP Streams API introduces a unified approach to the handling of files and sockets in PHP extension. Using a single API with standard functions for common operations, the streams API allows your extension to access files, sockets, URLs, memory and script-defined objects. Streams is a run-time extensible API that allows dynamically loaded modules (and scripts!) to register new streams. </p> <p class="para"> The aim of the Streams API is to make it comfortable for developers to open files, URLs and other streamable data sources with a unified API that is easy to understand. The API is more or less based on the ANSI C stdio family of functions (with identical semantics for most of the main functions), so C programmers will have a feeling of familiarity with streams. </p> <p class="para"> The streams API operates on a couple of different levels: at the base level, the API defines php_stream objects to represent streamable data sources. On a slightly higher level, the API defines php_stream_wrapper objects which "wrap" around the lower level API to provide support for retrieving data and meta-data from URLs. An additional <i>context</i> parameter, accepted by most stream creation functions, is passed to the wrapper's <i>stream_opener</i> method to fine-tune the behavior of the wrapper. </p> <p class="para"> Any stream, once opened, can also have any number of <i>filters</i> applied to it, which process data as it is read from/written to the stream. </p> <p class="para"> Streams can be cast (converted) into other types of file-handles, so that they can be used with third-party libraries without a great deal of trouble. This allows those libraries to access data directly from URL sources. If your system has the <b>fopencookie()</b> or <b>funopen()</b> function, you can even pass any PHP stream to any library that uses ANSI stdio! </p> </div> <div id="internals2.ze1.streams.basics" class="sect2"> <h3 class="title">Streams Basics</h3> <p class="para"> Using streams is very much like using ANSI stdio functions. The main difference is in how you obtain the stream handle to begin with. In most cases, you will use <b>php_stream_open_wrapper()</b> to obtain the stream handle. This function works very much like fopen, as can be seen from the example below: </p> <p class="para"> <div class="example"> <p><b>Example #1 simple stream example that displays the PHP home page</b></p> <div class="example-contents"><div class="cdata"><pre>php_stream * stream = php_stream_open_wrapper("http://www.php.net", "rb", REPORT_ERRORS, NULL);if (stream) { while(!php_stream_eof(stream)) { char buf[1024]; if (php_stream_gets(stream, buf, sizeof(buf))) { printf(buf); } else { break; } } php_stream_close(stream);}</pre></div> </div> </div> </p> <p class="para"> The table below shows the Streams equivalents of the more common ANSI stdio functions. Unless noted otherwise, the semantics of the functions are identical. <table border="5"> <caption><b>ANSI stdio equivalent functions in the Streams API</b></caption> <colgroup> <thead valign="middle"> <tr valign="middle"> <th colspan="1">ANSI Stdio Function</th> <th colspan="1">PHP Streams Function</th> <th colspan="1">Notes</th> </tr> </thead> <tbody valign="middle" class="tbody"> <tr valign="middle"> <td colspan="1" rowspan="1" align="left">fopen</td> <td colspan="1" rowspan="1" align="left">php_stream_open_wrapper</td> <td colspan="1" rowspan="1" align="left">Streams includes additional parameters</td> </tr> <tr valign="middle"> <td colspan="1" rowspan="1" align="left">fclose</td> <td colspan="1" rowspan="1" align="left">php_stream_close</td> <td class="empty"> </td> </tr> <tr valign="middle"> <td colspan="1" rowspan="1" align="left">fgets</td> <td colspan="1" rowspan="1" align="left">php_stream_gets</td> <td class="empty"> </td> </tr> <tr valign="middle"> <td colspan="1" rowspan="1" align="left">fread</td> <td colspan="1" rowspan="1" align="left">php_stream_read</td> <td colspan="1" rowspan="1" align="left">The nmemb parameter is assumed to have a value of 1, so the prototype looks more like read(2)</td> </tr> <tr valign="middle"> <td colspan="1" rowspan="1" align="left">fwrite</td> <td colspan="1" rowspan="1" align="left">php_stream_write</td> <td colspan="1" rowspan="1" align="left">The nmemb parameter is assumed to have a value of 1, so the prototype looks more like write(2)</td> </tr> <tr valign="middle"> <td colspan="1" rowspan="1" align="left">fseek</td> <td colspan="1" rowspan="1" align="left">php_stream_seek</td> <td class="empty"> </td> </tr> <tr valign="middle"> <td colspan="1" rowspan="1" align="left">ftell</td> <td colspan="1" rowspan="1" align="left">php_stream_tell</td> <td class="empty"> </td> </tr> <tr valign="middle"> <td colspan="1" rowspan="1" align="left">rewind</td> <td colspan="1" rowspan="1" align="left">php_stream_rewind</td> <td class="empty"> </td> </tr> <tr valign="middle"> <td colspan="1" rowspan="1" align="left">feof</td> <td colspan="1" rowspan="1" align="left">php_stream_eof</td> <td class="empty"> </td> </tr> <tr valign="middle"> <td colspan="1" rowspan="1" align="left">fgetc</td> <td colspan="1" rowspan="1" align="left">php_stream_getc</td> <td class="empty"> </td> </tr> <tr valign="middle"> <td colspan="1" rowspan="1" align="left">fputc</td> <td colspan="1" rowspan="1" align="left">php_stream_putc</td> <td class="empty"> </td> </tr> <tr valign="middle"> <td colspan="1" rowspan="1" align="left">fflush</td> <td colspan="1" rowspan="1" align="left">php_stream_flush</td> <td class="empty"> </td> </tr> <tr valign="middle"> <td colspan="1" rowspan="1" align="left">puts</td> <td colspan="1" rowspan="1" align="left">php_stream_puts</td> <td colspan="1" rowspan="1" align="left">Same semantics as puts, NOT fputs</td> </tr> <tr valign="middle"> <td colspan="1" rowspan="1" align="left">fstat</td> <td colspan="1" rowspan="1" align="left">php_stream_stat</td> <td colspan="1" rowspan="1" align="left">Streams has a richer stat structure</td> </tr> </tbody> </colgroup> </table> </p> </div> <div id="internals2.ze1.streams.resources" class="sect2"> <h3 class="title">Streams as Resources</h3> <p class="para"> All streams are registered as resources when they are created. This ensures that they will be properly cleaned up even if there is some fatal error. All of the filesystem functions in PHP operate on streams resources - that means that your extensions can accept regular PHP file pointers as parameters to, and return streams from their functions. The streams API makes this process as painless as possible: </p> <p class="para"> <div class="example"> <p><b>Example #2 How to accept a stream as a parameter</b></p> <div class="example-contents"><div class="cdata"><pre>PHP_FUNCTION(example_write_hello){ zval *zstream; php_stream *stream; if (FAILURE == zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "r", &zstream)) return; php_stream_from_zval(stream, &zstream); /* you can now use the stream. However, you do not "own" the stream, the script does. That means you MUST NOT close the stream, because it will cause PHP to crash! */ php_stream_write(stream, "hello\n"); RETURN_TRUE();}</pre></div> </div>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -