Stream

## 简介
流是概括文件、网络、数据压缩和其它操作的方式，共享一组通用的函数和用途。在其的简单定义中，stream 是表现可流动行为的 resource 对象。也就是说，它可以以线性的方式读写，并且可以 fseek() 到流中的任意位置。

wrapper 是附加代码，用于告诉流如何处理指定协议/编码。例如，http 封装协议知道如何将 URL 转换为 HTTP/1.0 请求远程服务器上的文件。默认情况下，PHP 内置了很多封装协议（参阅 [支持的协议和封装协议](https://www.php.net/manual/zh/wrappers.php "支持的协议和封装协议")），另外也可以直接从 PHP 脚本中使用 stream_wrapper_register() 或者直接从扩展中添加自定义封装协议。 因为任何种类的封装协议都可以添加到 PHP 中，所以对它们可以做什么并没有限制。使用 stream_get_wrappers() 访问当前已注册封装协议列表。

流作为 `scheme://target` 引用

- scheme（string）——要使用的封装协议名称。示例为 file、http、https、ftp、ftps、compress.zlib、compress.bz2 和 php。PHP 内置封装协议列表，参阅[支持的协议和封装协议](https://www.php.net/manual/zh/wrappers.php "支持的协议和封装协议")。如果没有指定封装协议，函数使用默认值（通常是 file://）。
- target——取决于要使用的封装协议。对于文件系统相关的流，这通常是所需文件的路径和文件名。对网络相关的流，这通常是主机名，通常跟着路径。再有，请参阅[支持的协议和封装协议](https://www.php.net/manual/zh/wrappers.php "支持的协议和封装协议") 获取对流内置目标的描述。

## 安装/配置

### 需求
构建此扩展不需要其他扩展。

### 安装
使用这些函数不需要安装，它们是 PHP 核心的一部分。

### 运行时配置
此扩展没有在 `php.ini` 中定义配置指令。

### 资源类型
此扩展没有定义资源类型。

## Stream Classes
User designed wrappers can be registered via stream_wrapper_register(), using the class definition shown on that manual page.

Class php_user_filter is predefined and is an abstract baseclass for use with user defined filters. See the manual page for stream_filter_register() for details on implementing user defined filters.

## 预定义常量
下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

| Constant                    | Description |
|-----------------------------|------------------|
| STREAM_FILTER_READ          |  Used with stream_filter_append() and stream_filter_prepend() to indicate that the specified filter should only be applied when reading |
| STREAM_FILTER_WRITE         |  Used with stream_filter_append() and stream_filter_prepend() to indicate that the specified filter should only be applied when writing |
| STREAM_FILTER_ALL           | This constant is equivalent to STREAM_FILTER_READ &#124; STREAM_FILTER_WRITE |
| PSFS_PASS_ON                | Return Code indicating that the userspace filter returned buckets in $out. |
| PSFS_FEED_ME                | Return Code indicating that the userspace filter did not return buckets in $out  (i.e. No data available). |
| PSFS_ERR_FATAL              | Return Code indicating that the userspace filter encountered an unrecoverable error (i.e. Invalid data received). |
| PSFS_FLAG_NORMAL            | Regular read/write.  |
| PSFS_FLAG_FLUSH_INC         | An incremental flush.   |
| PSFS_FLAG_FLUSH_CLOSE       | Final flush prior to closing. |
| STREAM_USE_PATH             | Flag indicating if the stream used the include path. |
| STREAM_REPORT_ERRORS        | Flag indicating if the wrapper is responsible for raising errors using trigger_error()  during opening of the stream.  If this flag is not set, you should not raise any errors. |
| STREAM_CLIENT_ASYNC_CONNECT | Open client socket asynchronously. This option must be used together with the STREAM_CLIENT_CONNECT flag. Used with stream_socket_client(). |
| STREAM_CLIENT_CONNECT       | Open client socket connection. Client sockets should always include this flag. Used with stream_socket_client(). |
| STREAM_CLIENT_PERSISTENT    | Client socket opened with stream_socket_client() should remain persistent between page loads. |
| STREAM_SERVER_BIND          | Tells a stream created with stream_socket_server() to bind to the specified target.  Server sockets should always include this flag. |
| STREAM_SERVER_LISTEN        | Tells a stream created with stream_socket_server() and bound using the STREAM_SERVER_BIND flag to start listening on the socket. Connection-orientated transports (such as TCP) must use this flag, otherwise the server socket will not be enabled. Using this flag for connect-less transports (such as UDP) is an error.|
| STREAM_NOTIFY_RESOLVE       | A remote address required for this stream has been resolved, or the resolution failed.  See severity for an indication of which happened. |
| STREAM_NOTIFY_CONNECT       | A connection with an external resource has been established. |
| STREAM_NOTIFY_AUTH_REQUIRED |  Additional authorization is required to access the specified resource. Typical issued with severity level of STREAM_NOTIFY_SEVERITY_ERR. |
| STREAM_NOTIFY_MIME_TYPE_IS  |  The mime-type of resource has been identified, refer to message for a description of the discovered type. |
| STREAM_NOTIFY_FILE_SIZE_IS  |  The size of the resource has been discovered. |
| STREAM_NOTIFY_REDIRECTED    |  The external resource has redirected the stream to an alternate location.  Refer to message. |
| STREAM_NOTIFY_PROGRESS      | Indicates current progress of the stream transfer in bytes_transferred and possibly bytes_max as well. |
| STREAM_NOTIFY_COMPLETED     | There is no more data available on the stream. |
| STREAM_NOTIFY_FAILURE       |  A generic error occurred on the stream, consult message and message_code for details. |
| STREAM_NOTIFY_AUTH_RESULT   | Authorization has been completed (with or without success). |
| STREAM_NOTIFY_SEVERITY_INFO | Normal, non-error related, notification. |
| STREAM_NOTIFY_SEVERITY_WARN | Non critical error condition.  Processing may continue. |
| STREAM_NOTIFY_SEVERITY_ERR  | A critical error occurred.  Processing cannot continue. |
| STREAM_IPPROTO_ICMP +       | Provides a ICMP socket. |
| STREAM_IPPROTO_IP +         | Provides a IP socket. |
| STREAM_IPPROTO_RAW +        | Provides a RAW socket. |
| STREAM_IPPROTO_TCP +        | Provides a TCP socket. |
| STREAM_IPPROTO_UDP +        | Provides a UDP socket. |
| STREAM_PF_INET +            | Internet Protocol Version 4 (IPv4). |
| STREAM_PF_INET6 +           | Internet Protocol Version 6 (IPv6). |
| STREAM_PF_UNIX +            | Unix system internal protocols. |
| STREAM_SOCK_DGRAM +         | Provides datagrams, which are connectionless messages (UDP, for example). |
| STREAM_SOCK_RAW +           |  Provides a raw socket, which provides access to internal network protocols and interfaces. Usually this type of socket is just available to the root user. |
| STREAM_SOCK_RDM +           | Provides a RDM (Reliably-delivered messages) socket. |
| STREAM_SOCK_SEQPACKET +     | Provides a sequenced packet stream socket. |
| STREAM_SOCK_STREAM +        | Provides sequenced, two-way byte streams with a transmission mechanism for out-of-band data (TCP, for example). |
| STREAM_SHUT_RD              | Used with stream_socket_shutdown() to disable further receptions. |
| STREAM_SHUT_WR              | Used with stream_socket_shutdown() to disable further transmissions. |
| STREAM_SHUT_RDWR            | Used with stream_socket_shutdown() to disable further receptions and transmissions. |
| STREAM_CAST_FOR_SELECT      | Stream casting, for when stream_select() is calling stream_cast().  |
| STREAM_CAST_AS_STREAM       | Stream casting, when stream_cast() is called otherwise (see above). |
| STREAM_META_TOUCH           | Used with stream_metadata(), to specify touch() call. |
| STREAM_META_OWNER           | Used with stream_metadata(), to specify chown() call. |
| STREAM_META_OWNER_NAME      | Used with stream_metadata(), to specify chown() call. |
| STREAM_META_GROUP           | Used with stream_metadata(), to specify chgrp() call. |
| STREAM_META_GROUP_NAME      | Used with stream_metadata(), to specify chgrp() call. |
| STREAM_META_ACCESS          | Used with stream_metadata(), to specify chmod() call. |
| STREAM_BUFFER_NONE          | No buffering. |
| STREAM_BUFFER_LINE          | Line buffering. |
| STREAM_BUFFER_FULL          | Full buffering. |

<div class="callout callout-info mb-3">注意: The constants marked with + are meant to be used with stream_socket_pair(). Please note that some of these constants might not be available in your system.</div>

<div class="callout callout-info mb-3">注意: The STREAM_META_* constants are meant to be used with stream_metadata().</div>

## Stream 过滤
filter 是在流中执行读取或写入数据操作时的最后一段代码。可以将任意数量的过滤器堆叠到一个流上。可以在 PHP 脚本中使用 stream_filter_register() 或扩展定义自定义过滤器。要访问当前注册的过滤器列表，请使用 stream_get_filters()。

## Stream Contexts
A context is a set of parameters and wrapper specific options which modify or enhance the behavior of a stream. Contexts are created using stream_context_create() and can be passed to most filesystem related stream creation functions (i.e. fopen(), file(), file_get_contents(), etc...).

Options can be specified when calling stream_context_create(), or later using stream_context_set_option(). A list of wrapper specific options can be found in the 上下文（Context）选项和参数 chapter.

Parameters can be specified for contexts using the stream_context_set_params() function.

## Stream Errors
As with any file or socket related function, an operation on a stream may fail for a variety of normal reasons (i.e.: Unable to connect to remote host, file not found, etc...). A stream related call may also fail because the desired stream is not registered on the running system. See the array returned by stream_get_wrappers() for a list of streams supported by your installation of PHP. As with most PHP internal functions if a failure occurs an E_WARNING message will be generated describing the nature of the error.

## 示例
### 示例类注册为流封装器
下面的示例实现了一个 var:// 协议处理程序，允许使用诸如 fread() 之类的标准文件系统流函数对有名称的全局变量进行读写访问。下面实现的 var:// 协议，指定的 URL `“var://foo”` 将从 `$GLOBALS["foo"]` 读写数据。

示例 #1 用于读写全局变量的流

```php
<?php

class VariableStream {
    var $position;
    var $varname;

function stream_open($path, $mode, $options, &$opened_path)
    {
        $url = parse_url($path);
        $this->varname = $url["host"];
        $this->position = 0;

return true;
    }

function stream_read($count)
    {
        $ret = substr($GLOBALS[$this->varname], $this->position, $count);
        $this->position += strlen($ret);
        return $ret;
    }

function stream_write($data)
    {
        $left = substr($GLOBALS[$this->varname], 0, $this->position);
        $right = substr($GLOBALS[$this->varname], $this->position + strlen($data));
        $GLOBALS[$this->varname] = $left . $data . $right;
        $this->position += strlen($data);
        return strlen($data);
    }

function stream_tell()
    {
        return $this->position;
    }

function stream_eof()
    {
        return $this->position >= strlen($GLOBALS[$this->varname]);
    }

function stream_seek($offset, $whence)
    {
        switch ($whence) {
            case SEEK_SET:
                if ($offset < strlen($GLOBALS[$this->varname]) && $offset >= 0) {
                     $this->position = $offset;
                     return true;
                } else {
                     return false;
                }
                break;

case SEEK_CUR:
                if ($offset >= 0) {
                     $this->position += $offset;
                     return true;
                } else {
                     return false;
                }
                break;

case SEEK_END:
                if (strlen($GLOBALS[$this->varname]) + $offset >= 0) {
                     $this->position = strlen($GLOBALS[$this->varname]) + $offset;
                     return true;
                } else {
                     return false;
                }
                break;

default:
                return false;
        }
    }

stream_wrapper_register("var", "VariableStream")
    or die("Failed to register protocol");

$myvar = "";

$fp = fopen("var://myvar", "r+");

fwrite($fp, "line1\n");
fwrite($fp, "line2\n");
fwrite($fp, "line3\n");

rewind($fp);
while (!feof($fp)) {
    echo fgets($fp);
}
fclose($fp);
var_dump($myvar);

?>
```
以上示例会输出：

```
line1
line2
line3
string(18) "line1
line2
line3
"
```