PHP `Stream` 包装器：自定义协议流、文件系统流与网络流

各位观众，各位朋友，欢迎来到今天的PHP流包装器“瞎折腾”讲座！我是你们的老朋友，今天要带大家一起深入PHP那看似平静，实则暗流涌动的“流”的世界。别担心，咱们不搞那些晦涩难懂的理论，只聊实际能用、能让你眼前一亮的干货！

开场白：PHP的“流”到底是个啥？

PHP的流（Stream）其实就是一种抽象的概念，它代表了一种可以读取或写入的数据源。你可以把流想象成一条水管，数据就是水，你可以从水管里取水（读取），也可以往水管里灌水（写入）。而PHP的流包装器（Stream Wrapper）就是给这条水管定制各种各样的“接口”，让你可以用统一的方式去操作不同来源的数据，比如文件、网络连接、内存等等。

第一节：为啥要“瞎折腾”流包装器？

你可能会问，PHP自带的file_get_contents、fopen、fwrite这些函数不挺好用的吗？为啥还要费劲巴拉地自己写流包装器？

答案很简单：为了灵活！

想象一下，如果你要从一个特殊的数据库读取数据，这个数据库没有PHP官方的扩展，或者你想要实现一些特殊的文件系统操作，比如加密存储、版本控制等等，这时候，自定义流包装器就能派上大用场了。它可以让你以一种非常优雅和一致的方式来处理这些复杂的操作，而不用到处写冗余的代码。

第二节：流包装器的三大类别

PHP的流包装器大致可以分为三类：

自定义协议流（Protocol Stream Wrapper）： 就像http://、ftp://、data://这些，你可以自定义一个协议，比如myprotocol://，然后用fopen('myprotocol://path/to/resource', 'r')来访问你的资源。
自定义文件系统流（Filesystem Stream Wrapper）： 这种包装器可以让你像操作普通文件一样操作你的数据，比如copy('myprotocol://source', 'myprotocol://destination')。
自定义网络流（Network Stream Wrapper）： 这种包装器主要用于处理网络连接，比如实现自定义的HTTP客户端、WebSocket客户端等等。

第三节：自定义协议流（Protocol Stream Wrapper）实战

咱们先从最常用的自定义协议流开始。假设我们要创建一个名为mydata://的协议，它可以从一个数组中读取数据。

步骤1：定义一个类，实现streamWrapper接口

<?php

class MyDataStreamWrapper
{
    private $position = 0;
    private $data = [];
    private $context;

    public function stream_open(string $path, string $mode, int $options, ?string &$opened_path): bool
    {
        // 从路径中提取数据数组的名称
        $dataName = substr($path, strlen('mydata://'));

        // 假设我们有一个全局数组 $myData
        global $myData;

        if (isset($myData[$dataName]) && is_array($myData[$dataName])) {
            $this->data = $myData[$dataName];
            $this->position = 0;
            return true;
        }

        return false;
    }

    public function stream_read(int $count): string|false
    {
        $length = count($this->data);
        if ($this->position >= $length) {
            return false;
        }

        $readLength = min($count, $length - $this->position);
        $result = array_slice($this->data, $this->position, $readLength);
        $this->position += $readLength;

        return implode('', $result);
    }

    public function stream_write(string $data): int|false
    {
        // 我们的例子只读，所以返回 false
        return false;
    }

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

    public function stream_eof(): bool
    {
        return $this->position >= count($this->data);
    }

    public function stream_seek(int $offset, int $whence = SEEK_SET): bool
    {
        $length = count($this->data);
        switch ($whence) {
            case SEEK_SET:
                $this->position = $offset;
                break;
            case SEEK_CUR:
                $this->position += $offset;
                break;
            case SEEK_END:
                $this->position = $length + $offset;
                break;
            default:
                return false;
        }

        $this->position = max(0, min($this->position, $length)); // 确保 position 在有效范围内
        return true;
    }

    public function stream_stat(): array|false
    {
        // 返回一个模拟的 stat 数组
        return [
            'dev' => 0,
            'ino' => 0,
            'mode' => 0100644, // 权限，这里设置为 -rw-r--r--
            'nlink' => 1,
            'uid' => 0,
            'gid' => 0,
            'rdev' => 0,
            'size' => strlen(implode('', $this->data)),
            'atime' => time(),
            'mtime' => time(),
            'ctime' => time(),
            'blksize' => 0,
            'blocks' => 0,
        ];
    }

    public function stream_close(): void
    {
        $this->data = [];
        $this->position = 0;
    }

    public function unlink(string $path): bool
    {
        // 不支持删除
        return false;
    }

    public function rename(string $path_from, string $path_to): bool
    {
        // 不支持重命名
        return false;
    }

    public function mkdir(string $path, int $mode, int $options): bool
    {
        // 不支持创建目录
        return false;
    }

    public function rmdir(string $path, int $options): bool
    {
        // 不支持删除目录
        return false;
    }

    // 上下文支持
    public function stream_set_option(int $option, int $arg1, int $arg2): bool
    {
        switch ($option) {
            case STREAM_OPTION_BLOCKING:
                // 模拟阻塞/非阻塞模式
                return true;
            case STREAM_OPTION_TIMEOUT:
                // 模拟超时
                return true;
            default:
                return false;
        }
    }
    public function stream_metadata(string $path, int $option, mixed $value): bool
    {
        // 不支持设置元数据
        return false;
    }
    public function dir_opendir(string $path, int $options): bool
    {
        // 不支持打开目录
        return false;
    }

    public function dir_readdir(): string|false
    {
        // 不支持读取目录
        return false;
    }

    public function dir_rewind(): bool
    {
        // 不支持重置目录指针
        return false;
    }

    public function dir_closedir(): bool
    {
        // 不支持关闭目录
        return false;
    }

    public function url_stat(string $path, int $flags): array|false
    {
        // 返回一个模拟的 stat 数组，用于文件系统函数 (file_exists, is_dir, etc.)
        return $this->stream_stat();
    }

    public function stream_cast(int $cast_as)
    {
        // 不支持 stream_select 函数
        return false;
    }

    public function stream_lock(int $operation) : bool
    {
        //不支持文件锁
        return false;
    }
}

?>

步骤2：注册流包装器

<?php

stream_wrapper_register('mydata', 'MyDataStreamWrapper');

?>

步骤3：使用流包装器

<?php

global $myData;
$myData = [
    'test' => ['H', 'e', 'l', 'l', 'o', ' ', 'W', 'o', 'r', 'l', 'd', '!'],
];

$content = file_get_contents('mydata://test');
echo $content; // 输出：Hello World!

$file = fopen('mydata://test', 'r');
if ($file) {
    while (!feof($file)) {
        echo fread($file, 1);
    }
    fclose($file);
}

?>

代码解释：

stream_open： 这是流包装器的“构造函数”，当使用fopen或其他类似函数打开流时，这个方法会被调用。你可以在这里进行一些初始化操作，比如连接数据库、读取配置文件等等。
- $path: 包含协议的路径，例如 mydata://test
- $mode: 打开模式，例如 r (只读), w (只写)
- $options: 一些选项，例如 STREAM_USE_PATH
- &$opened_path: 如果成功打开，可以修改这个参数来返回实际打开的路径。
stream_read： 从流中读取数据。$count参数指定要读取的字节数。
stream_write： 向流中写入数据。$data参数包含要写入的数据。注意，我们的例子是只读的，所以stream_write方法直接返回false。
stream_tell： 返回当前流的读取/写入位置。
stream_eof： 判断是否到达流的末尾。
stream_seek： 移动流的读取/写入位置。
stream_stat： 返回流的状态信息，比如文件大小、修改时间等等。这个方法主要用于stat()、file_exists()等函数。
stream_close： 这是流包装器的“析构函数”，当流被关闭时，这个方法会被调用。你可以在这里进行一些清理操作，比如关闭数据库连接等等。
stream_wrapper_register： 这个函数用于注册流包装器。第一个参数是协议名称，第二个参数是类名。

注意事项：

streamWrapper接口中的所有方法都必须实现，即使你不需要它们，也应该返回一个默认值（比如false）。
错误处理非常重要！如果你的流包装器遇到错误，应该返回false，并使用trigger_error函数来抛出一个错误信息。
为了安全起见，尽量避免在流包装器中执行一些危险的操作，比如执行系统命令等等。

第四节：自定义文件系统流（Filesystem Stream Wrapper）进阶

自定义文件系统流包装器允许你使用PHP的文件系统函数（比如copy、rename、unlink等等）来操作你的数据。要实现一个文件系统流包装器，你需要实现以下方法：

unlink：删除文件。
rename：重命名文件。
mkdir：创建目录。
rmdir：删除目录。
dir_opendir：打开目录。
dir_readdir：读取目录。
dir_rewind：重置目录指针。
dir_closedir：关闭目录。
url_stat：返回文件的状态信息。

示例：

<?php

class MyFileSystemStreamWrapper extends MyDataStreamWrapper
{
    public function unlink(string $path): bool
    {
        // 实现删除文件的逻辑
        $dataName = substr($path, strlen('mydata://'));

        global $myData;

        if (isset($myData[$dataName])) {
            unset($myData[$dataName]);
            return true;
        }

        return false;
    }

    // 其他方法类似，需要根据实际需求来实现
}

stream_wrapper_unregister('mydata'); // 先注销之前的协议
stream_wrapper_register('mydata', 'MyFileSystemStreamWrapper');

global $myData;
$myData = [
    'test' => ['H', 'e', 'l', 'l', 'o', ' ', 'W', 'o', 'r', 'l', 'd', '!'],
];

unlink('mydata://test');

var_dump(isset($myData['test'])); // 输出：bool(false)

?>

第五节：自定义网络流（Network Stream Wrapper）的挑战

自定义网络流包装器是三种类型中最复杂的，它主要用于处理网络连接。你需要处理诸如连接建立、数据传输、超时、错误处理等等问题。

关键方法：

stream_socket_client：建立网络连接。
stream_select：用于多路复用，可以同时监听多个socket。
stream_set_blocking：设置阻塞/非阻塞模式。
stream_set_timeout：设置超时时间。

示例（简略）：

<?php

class MyNetworkStreamWrapper
{
    private $socket;

    public function stream_open(string $path, string $mode, int $options, ?string &$opened_path): bool
    {
        $url = parse_url($path);
        if (!$url || !isset($url['host'], $url['port'])) {
            return false;
        }

        $this->socket = stream_socket_client(
            'tcp://' . $url['host'] . ':' . $url['port'],
            $errno,
            $errstr,
            30, // 超时时间
            STREAM_CLIENT_CONNECT
        );

        if (!$this->socket) {
            trigger_error("Failed to connect: $errstr ($errno)", E_USER_WARNING);
            return false;
        }

        return true;
    }

    public function stream_read(int $count): string|false
    {
        if (!is_resource($this->socket)) {
            return false;
        }

        return fread($this->socket, $count);
    }

    public function stream_write(string $data): int|false
    {
        if (!is_resource($this->socket)) {
            return false;
        }

        return fwrite($this->socket, $data);
    }

    public function stream_close(): void
    {
        if (is_resource($this->socket)) {
            fclose($this->socket);
        }
    }

    // 其他方法省略
}

?>

第六节：流上下文（Stream Context）的妙用

流上下文（Stream Context）是一个非常强大的工具，它可以让你在打开流的时候传递一些额外的参数。你可以使用stream_context_create函数创建一个流上下文，然后使用stream_context_set_option函数设置一些选项。

示例：

<?php

$context = stream_context_create([
    'mydata' => [
        'option1' => 'value1',
        'option2' => 'value2',
    ],
]);

$file = fopen('mydata://test', 'r', false, $context);

// 在 MyDataStreamWrapper 的 stream_open 方法中可以访问这些选项：
// $options = stream_context_get_options($this->context);

?>

第七节：调试流包装器

调试流包装器可能会比较棘手，因为很多错误都发生在底层。以下是一些调试技巧：

错误日志： 使用trigger_error函数抛出错误信息，并查看PHP的错误日志。
var_dump： 在关键的方法中打印一些变量的值，以便了解程序的执行流程。
xdebug： 使用xdebug进行单步调试，可以让你更清楚地了解程序的执行过程。

第八节：流包装器的应用场景

自定义文件存储： 比如将文件存储到云存储服务、数据库等等。
数据加密/解密： 可以在读取或写入数据的时候进行加密/解密操作。
数据压缩/解压缩： 可以在读取或写入数据的时候进行压缩/解压缩操作。
访问远程API： 可以创建一个流包装器来访问远程API，并以一种统一的方式来处理数据。
虚拟文件系统： 可以创建一个虚拟文件系统，用于测试、演示等等。

总结：

PHP的流包装器是一个非常灵活和强大的工具，它可以让你以一种优雅和一致的方式来处理各种各样的数据源。虽然学习曲线可能会比较陡峭，但是一旦掌握了它，你就可以写出更加高效、可维护的代码。希望今天的讲座能给你带来一些启发，让你在“瞎折腾”流包装器的道路上越走越远！谢谢大家！

发表回复 取消回复

发表回复取消回复