PHP stream识别文件与 HTTP wrapper 的差异的实现方法

我第一次把“文件”和“HTTP 返回体”放进同一个 PHP 读取器时，误以为只要看 stream_type 就够了。实际排查下来，stream_type 更像底层实现标签，协议来源应该看 wrapper_type，本地性再用 stream_is_local() 交叉确认。这样才能区分“本地文件”“HTTP wrapper”“底层是 socket 但仍由 wrapper 管理”这几种情况。

实用判断顺序是：先确认资源确实打开，再读取 stream_get_meta_data()；用 stream_is_local() 判断本地性，用 wrapper_type 判断协议层，最后结合 seekable 决定能否定位读取。

先把 stream 和 wrapper 分成两层看

PHP 官方文档把 stream 描述为一套通用的线性读写抽象，文件、网络和压缩操作都可以通过相近的函数访问。wrapper 则告诉 PHP 如何处理某个 scheme，例如 file:// 访问本地文件，http:// 把 URL 转成 HTTP 请求。换句话说，fopen() 的调用形状可以相似，但资源背后的协议层并不相同。

$path = __DIR__ . '/config.json';
$local = fopen($path, 'rb');

// scheme 选择 wrapper，target 指向具体资源。
$remote = fopen('https://example.com/data.json', 'rb');

// 读取完成后显式关闭资源，避免把连接或文件句柄留给调用方。
if (is_resource($local)) {
    fclose($local);
}
if (is_resource($remote)) {
    fclose($remote);
}

这里的 https:// 不是“另一种文件格式”，而是另一种 wrapper 入口。没有指定 scheme 时，文件函数通常使用默认的 file wrapper，所以代码里最好把资源来源保留在元数据里，而不是靠传入字符串猜测。

文件流与 HTTP 流，关键差异在元数据

stream_get_meta_data() 返回的是一个数组，常用字段包括 wrapper_type、stream_type、uri、mode 和 seekable。本地文件常见的是 file wrapper；HTTP 流的底层实现可能显示为 TCP socket 或 SSL socket，因此不能只看 stream_type 下结论。

我在日志里会同时保留这几个值，而不是只输出一个布尔结果。这样当某个自定义 wrapper 改变实现方式时，仍能从 uri、wrapper 和可定位能力判断它到底属于哪一类。

用组合判断替代一个字段猜测

下面这个小函数不读取正文，只把已打开的资源整理成可记录的摘要。它把“来源”“协议”“底层实现”和“定位能力”分开，调用方可以据此决定是否允许缓存、重试或随机读取。

function describeStream($handle): array
{
    // 资源无效时返回可解释的失败状态，不访问不存在的元数据。
    if (!is_resource($handle)) {
        return ['ok' => false, 'reason' => 'invalid-stream'];
    }

    // 元数据描述实现和能力，不能把 stream_type 当成协议名。
    $meta = stream_get_meta_data($handle);

    return [
        'ok' => true,
        'is_local' => stream_is_local($handle),
        'wrapper_type' => $meta['wrapper_type'] ?? null,
        'stream_type' => $meta['stream_type'] ?? null,
        'uri' => $meta['uri'] ?? null,
        'seekable' => (bool) ($meta['seekable'] ?? false),
    ];
}

真正的业务判断应该在这层摘要之上完成。例如，要求随机读取时检查 seekable；要求只读本地文件时检查 is_local；要求识别 HTTP 时看 wrapper_type，而不是把所有 socket 都当成 HTTP。

自定义 wrapper 与几个容易漏掉的边界

PHP 允许通过 stream_wrapper_register() 注册自定义协议。部署环境可能没有某个扩展或 wrapper，因此可以先用 stream_get_wrappers() 检查名称是否存在。另一方面，HTTP 与 FTP 等远程 URL 能否被文件函数打开，还受 allow_url_fopen 等配置影响；打开失败时应记录错误并结束当前资源路径，不要继续调用元数据函数。

• 打开失败：先判断返回值，不能对 false 调用 stream_get_meta_data()。
• 字段不完整：使用空合并处理可选字段，避免自定义 wrapper 的实现差异触发 notice。
• 资源释放：调用方明确资源所有权，读取完成或异常退出都要 fclose()。
• 协议能力：存在 wrapper 不代表远端一定可访问，网络、配置和上下文选项仍然可能阻止打开。

常见问题

stream_type 是不是文件或 HTTP 的唯一标识？

不是。它更接近底层实现描述；HTTP 流可能显示为 socket。识别协议应优先看 wrapper_type，再结合本地性和 URI。

本地流一定可以 fseek() 吗？

不一定。是否可定位由 seekable 表示，判断本地性和判断定位能力是两件事。

为什么自定义 wrapper 的字段不能照抄 HTTP？

HTTP wrapper 有自己的 wrapper_data 和底层实现，自定义 wrapper 可以只实现部分能力。读取元数据时应把字段视为描述信息，并对缺失值做兼容。

把 stream、wrapper 和底层实现拆开之后，文件与 HTTP 的差异就不再依赖经验猜测。先拿到元数据，再按本地性、协议和 seek 能力分别做判断，代码会更容易适配自定义 wrapper，也更容易解释异常。