PHP流包装器是文件系统函数的底层抽象机制，所有fopen()等操作均依赖其统一接口；vfsStream通过注册vfs://协议在内存构建虚拟文件树，setup()注册协议并设根，create()挂载结构，二者不可颠倒。
PHP 的流包装器不是“可选技巧”，而是文件系统抽象层的底层机制——所有 fopen()、file_get_contents()、include() 等函数都走这层。你注册一个协议，就等于给 PHP 新增了一种“文件类型”。vfsStream 本质就是个注册了 vfs:// 协议的自定义包装器，它不碰磁盘，只在内存里建树状结构。
为什么 stream_wrapper_register() 必须在首次使用前调用
PHP 流系统在解析 URL（如 myproto://path）时，会查内部注册表；如果没找到对应包装器，直接报 Warning: fopen(): Unable to find wrapper "myproto" 并失败。这个注册表是运行时静态的，不会自动重载。
- 不能在类构造函数或测试方法里注册——可能已被其他代码提前触发了流操作
- 不能依赖 autoloader 触发注册——
stream_wrapper_register()是纯函数调用，不触发自动加载 - 推荐放在
bootstrap.php或 PHPUnit 的setUpBeforeClass()中，确保全局唯一且最早执行 - 重复注册同名协议会触发致命错误：
Fatal error: stream_wrapper_register(): Protocol myproto is already registered
vfsStream::setup() 和 vfsStream::create() 的行为差异
这两个方法看似都是“建文件系统”，但职责完全不同：vfsStream::setup() 只注册 vfs:// 协议并创建根目录对象；vfsStream::create() 才真正把数组结构转成内存中的 vfsStreamDirectory 和 vfsStreamFile 实例树。
- 不调用
vfsStream::setup()就直接vfsStream::create()—— 会抛出RuntimeException：“No root directory defined” -
vfsStream::setup('root')后，vfsStream::url('root')返回vfs://root；但此时目录下什么都没有，file_exists(vfsStream::url('root/foo.txt'))为false -
vfsStream::create(['foo.txt' => 'hello'])必须在 setup 之后，它会把键值对挂到当前根目录下；若未指定根，就用上次setup()创建的那个 - 多次
create()是追加，不是覆盖——第二次调用会把新结构合并进已有树，而非清空重建
自定义流包装器里 stream_open() 的参数陷阱
stream_open() 方法签名是 public function stream_open(string $path, string $mode, int $options, string &$opened_path): bool，其中 $mode 和 $options 容易误读。
立即学习“PHP免费学习笔记（深入）”；
-
$mode是原始字符串，如'r+'、'c'、'w+b'，不是 vfsStream 里的READ/TRUNCATE常量——那些只是 vfsStream 自己封装的语义，PHP 内核传进来的是标准 C 风格 mode 字符串 -
$options是位掩码，常见值有STREAM_USE_PATH（表示应使用 include_path）、STREAM_REPORT_ERRORS（出错时触发 warning），不是布尔值 - 返回
false表示打开失败，PHP 会立即中止后续操作；返回true后，stream_read()等方法才可能被调用 - 必须在
stream_open()里解析$path，提取 scheme 后的路径部分（如myproto://config/db.json中的config/db.json），否则后续所有操作都找不到上下文
vfsStream 不支持 opendir() + readdir() 迭代的真实限制
vfsStream 声称“兼容所有 PHP 文件系统函数”，但 opendir() 返回的 resource 在底层其实是 vfsStreamDirectory 对象的包装，并非真实 dir handle。这就导致某些依赖 C 层 readdir 行为的扩展或函数会出问题。
-
scandir()和glob()能正常工作，因为它们走的是 PHP 用户层封装 - 但
while (($f = readdir($dh)) !== false)在 vfsStream 下虽不报错，却可能漏掉子项——尤其当目录结构在迭代中途被修改时，vfsStream 的迭代器不保证强一致性 - 更隐蔽的问题：某些框架的自动加载器（如早期 Symfony ClassLoader）用
opendir()遍历 vendor 目录，若用 vfsStream 模拟 vendor，可能因迭代顺序或缓存行为导致类找不到 - 解决办法不是避免用
opendir()，而是明确在测试中用scandir()替代，或在 vfsStream 根目录上预建完整结构，避免运行时动态增删
流包装器的协议名一旦注册，就进入 PHP 全局命名空间；vfsStream 的 vfs:// 看似安全，但如果测试套件里混用多个自定义包装器，或者某些扩展也注册了同名协议，冲突会在运行时才暴露——没有编译期检查，也没有命名空间隔离。
