PHP 8 下 new MongoDBGridFSBucket($database) 大概率失败，因其构造函数非公开设计，必须通过 $database->selectGridFSBucket() 获取实例，否则因缺失内部初始化（如 chunkSizeBytes、collection 绑定）触发 InvalidArgumentException。
PHP 8 中直接用 MongoDBGridFSBucket 操作 GridFS 是可行的，但必须确认驱动版本 ≥1.16.0、MongoDB Server ≥4.4，且不能跳过 selectGridFSBucket() 或手动构造 Bucket 实例——否则会报 MongoDBExceptionInvalidArgumentException。
为什么 new MongoDBGridFSBucket($database) 在 PHP 8 下大概率失败
PHP 8 强化了类型检查和构造函数约束，而 MongoDBGridFSBucket::__construct() 并非设计为公开调用。官方明确要求通过 $database->selectGridFSBucket() 获取实例，否则会因缺少内部初始化（如 chunkSizeBytes 默认值注入、collection 名称绑定）触发参数校验异常。
- 错误现象：
Fatal error: Uncaught MongoDBExceptionInvalidArgumentException: Expected $database to be an instance of MongoDBDatabase或更隐蔽的Call to undefined method selectGridFSBucket()（若误传 Client 而非 Database） - 正确路径：先用
MongoDBClient连接，再调用->selectDatabase('dbname')，最后链式调用->selectGridFSBucket() - 可选参数：
selectGridFSBucket(['bucketName' => 'myfiles'])，不传则默认使用fs集合前缀
uploadFromStream() 接收前端文件流时的三个硬性条件
前端以 multipart/form-data 或原始二进制流（Content-Type: application/octet-stream）发送时，PHP 后端必须满足以下三点，否则 uploadFromStream() 读不到数据或写入空文件：
-
fopen('php://input', 'rb')必须配合fseek($stream, 0)—— 因为某些 SAPI（如 Apache mod_php）会提前读取流头，导致指针不在起始位置 -
$_POST['filename']不可靠：若前端未显式传该字段，应 fallback 到$_SERVER['HTTP_CONTENT_DISPOSITION']解析或生成安全文件名，避免空字符串触发InvalidArgumentException -
contentType选项必须显式传入，不能依赖$_SERVER['CONTENT_TYPE']—— 它在 multipart 场景下是 boundary 类型，不是真实文件 MIME，应从$_FILES或前端自定义 header（如X-File-Type）获取
下载文件用 downloadToStreamByName() 要注意修订版本语义
同一 filename 多次上传会生成多个 GridFS 文件文档（按 uploadDate 排序），downloadToStreamByName() 默认只取最新版（revision => -1），这不是 bug，而是设计行为：
立即学习“PHP免费学习笔记（深入）”；
- 若需历史版本，必须传
['revision' => 0]（首版）、['revision' => 1]（第二版）等整数；负数仅支持-1（最新）和-2（倒数第二） - 不要试图用
findOne(['filename' => 'x'])->_id再调downloadToStream()—— 这种方式绕过 revision 机制，但需额外查库，且downloadToStream()接收的是ObjectId，不是文档对象 - 流目标必须是可写资源：
fopen('php://output', 'wb')直接输出浏览器时，务必在调用前清空输出缓冲（ob_end_clean()），否则 HTTP 头混乱
deleteByName() 和 delete() 的实际删除范围差异
deleteByName() 删除所有同名文件（全部 revision），而 delete() 只删单个 _id 对应文件——这点容易误判：
- 调用
$bucket->deleteByName('report.pdf')会删掉该名字下所有历史版本，不可逆 - 若只想删某次上传（比如用户撤回刚传错的版本），必须先
$bucket->find(['filename' => 'report.pdf'])->toArray()拿到带uploadDate的列表，再按时间筛选出要删的_id，最后传给$bucket->delete($objectId) - 注意：GridFS 的
delete()不会自动清理孤立 chunks，但现代驱动（≥1.15）已内置检测，无需手动跑db.fs.chunks.remove({files_id: ObjectId(...)})
真正容易被忽略的是：GridFS Bucket 实例**不是线程安全的**，在长生命周期的 PHP 应用（如 Swoole 或 RoadRunner）中复用同一个 $bucket 实例可能引发并发写冲突，应按请求新建或严格控制作用域。
