如何在PHP中通过MongoDB驱动操作GridFS存储？-MongoDB-PHP中文网

php mongodb驱动中gridfs类名为mongodb\gridfs\bucket，必须用new mongodb\gridfs\bucket($database)初始化，不可用gridfsbucket或旧类名；需传入database实例，可选桶名（如'uploads'）和配置，桶名决定底层fs.files/fs.chunks集合前缀。

如何在php中通过mongodb驱动操作gridfs存储？

PHP MongoDB驱动里GridFS的类名和初始化方式

PHP官方MongoDB驱动（mongodb/mongodb）从1.0开始不再内置GridFS支持，必须手动用MongoDB\GridFS\Bucket类操作。不是GridFS或GridFSBucket，也不是旧驱动里的MongoGridFS——用错类名会直接抛Class not found错误。

初始化需要先连上数据库，再传入数据库对象和可选配置：

$client = new MongoDB\Client('mongodb://localhost:27017');
$database = $client->selectDatabase('myapp');
$bucket = new MongoDB\GridFS\Bucket($database); // 默认使用 fs 作为桶名
// 或指定桶名：new MongoDB\GridFS\Bucket($database, 'uploads')

$bucket是实际操作入口，所有读写都通过它，不是$database->selectCollection()那种方式
桶名（bucket name）对应底层两个集合：<bucket>.files</bucket>和<bucket>.chunks</bucket>，改桶名会影响这两者前缀
不传配置时默认使用_id为ObjectId，且chunkSizeBytes为262144（256KB），改这个值需权衡网络分片与内存占用

上传文件时怎么处理大文件和元数据

$bucket->uploadFromStream()是主力方法，但容易忽略流资源状态和元数据结构。它不接受路径字符串，只认resource或StreamInterface，传fopen()结果最稳妥。

元数据（metadata）必须是关联数组，且键名不能含.或$，否则插入files集合时会报InvalidDocument错误：

PHP 8.5.5

PHP 8.5.5 是 PHP 8.5 分支的维护更新版本。该版本延续了“小步快跑”的迭代逻辑，通过深度错误修复、底层性能微调以及安全加固，旨在为开发者提供一个更健壮、更高效的运行环境。该版本严格遵守语义化版本规范，不包含破坏性变更。

下载

$stream = fopen('/tmp/report.pdf', 'r');
$oid = $bucket->uploadFromStream(
    'report-2024.pdf',
    $stream,
    [
        'metadata' => [
            'user_id' => 123,
            'mime_type' => 'application/pdf',
            'uploaded_at' => new MongoDB\BSON\UTCDateTime(),
        ]
    ]
);
fclose($stream);

上传后返回的是MongoDB\BSON\ObjectId，不是字符串，别直接echo；要存ID就调->__toString()
如果文件已存在同名，uploadFromStream()默认覆盖，没提示也不报错——需要先find()查重就得自己做
大文件（如>100MB）建议配合stream_set_chunk_size()控制内存，否则可能触发PHP内存限制

下载文件时如何避免内存溢出和404问题

$bucket->openDownloadStream()返回的是流资源，不是内容字符串。直接stream_get_contents()加载整个文件到内存，对大文件就是灾难。

正确做法是边读边写，比如输出到浏览器：

$stream = $bucket->openDownloadStream($fileId);
header('Content-Type: ' . ($metadata['mime_type'] ?? 'application/octet-stream'));
header('Content-Disposition: attachment; filename="' . $filename . '"');
fpassthru($stream);
fclose($stream);

$fileId必须是ObjectId实例，不能是字符串ID，否则抛InvalidArgumentException：“Expected ObjectId”
查不到文件时openDownloadStream()直接抛MongoDB\Driver\Exception\RuntimeException，错误信息是File not found for id，得用try/catch捕获
别用downloadToStream()再写文件——它内部也是调openDownloadStream()，多一层封装没额外价值