存储大文件

概述

在本指南中，您将学习如何通过使用 GridFS 在 MongoDB 中存储和检索大文件。GridFS 是 MongoDB PHP 库实现的一个规范，描述了在存储文件时如何将其分割成块，并在检索时重新组合它们。库对 GridFS 的实现是一个抽象，用于管理文件存储的操作和组织。

如果您的文件大小超过 16MB 的 BSON 文档大小限制，请使用 GridFS。有关 GridFS 是否适合您的用例的更多详细信息，请参阅GridFS MongoDB 服务器手册。

GridFS 的工作原理

GridFS 将文件组织在一个 桶 中，这是一个包含文件块及其描述信息的 MongoDB 集合组。桶包含以下集合，使用 GridFS 规范中定义的约定命名

• 集合chunks 集合存储二进制文件块。

• files 集合存储文件元数据。

当您创建一个新的 GridFS 桶时，库会创建上述集合，前缀为默认的桶名称 fs，除非您指定了不同的名称。库还会在每个集合上创建索引，以确保高效检索文件和相关元数据。只有在第一次执行写操作时，库才会创建 GridFS 桶（如果不存在）。只有在索引不存在且桶为空时，库才会创建索引。有关 GridFS 索引的更多信息，请参阅 MongoDB 服务器手册中的 GridFS 索引。

在使用GridFS存储文件时，库会将文件分割成更小的块，每个块由chunks集合中的一个单独文档表示。它还在files集合中创建一个文档，包含文件ID、文件名和其他文件元数据。您可以通过向MongoDB PHP库传递流来消费或直接创建新流并写入它来上传文件。有关流的更多信息，请参阅PHP手册中的流。

查看以下图表以了解GridFS在将文件上传到存储桶时如何分割文件

在检索文件时，GridFS从指定存储桶的files集合中检索元数据，并使用这些信息从chunks集合中的文档中重建文件。您可以通过将文件内容写入现有流或创建一个指向文件的新流来读取文件。

创建GridFS存储桶

要存储或从GridFS检索文件，请调用您数据库上的MongoDB\Database::selectGridFSBucket()方法。此方法访问现有存储桶或如果不存在则创建新存储桶。

以下示例在db数据库上调用selectGridFSBucket()方法

$bucket = $client->db->selectGridFSBucket();

$custom_bucket = $client->db->selectGridFSBucket(
    ['bucketName' => 'myCustomBucket']
);

上传文件

您可以通过以下方法将文件上传到GridFS bucket

• MongoDB\GridFS\Bucket::openUploadStream()：打开一个新的上传流，您可以将文件内容写入其中

• MongoDB\GridFS\Bucket::uploadFromStream()：将现有流的内溶上传到GridFS文件

$stream = $bucket->openUploadStream('my_file', [
    'metadata' => ['contentType' => 'text/plain']
]);
fwrite($stream, 'Data to store');
fclose($stream);

$file = fopen('/path/to/input_file', 'rb');
$bucket->uploadFromStream('new_file', $file);

检索文件信息

在本节中，您可以学习如何检索存储在GridFS存储桶的files集合中的文件元数据。元数据包含关于所引用文件的信息，包括

• 文件的_id

• 文件的名称

• 文件长度/大小

• 上传日期和时间

• 一个metadata文档，您可以在此存储其他任何信息

要从GridFS存储桶检索文件，请调用MongoDB\GridFS\Bucket::find()方法，该方法在MongoDB\GridFS\Bucket实例上。该方法返回一个MongoDB\Driver\Cursor实例，您可以从中访问结果。要了解更多关于MongoDB PHP库中Cursor对象的信息，请参阅从游标中访问数据指南。

$files = $bucket->find();
foreach ($files as $file_doc) {
    echo toJSON($file_doc), PHP_EOL;
}

{ "_id" : { "$oid" : "..." }, "chunkSize" : 261120, "filename" : "my_file",
"length" : 13, "uploadDate" : { ... }, "metadata" : { "contentType" : "text/plain" },
"md5" : "6b24249b03ea3dd176c5a04f037a658c" }
{ "_id" : { "$oid" : "..." }, "chunkSize" : 261120, "filename" : "new_file",
"length" : 13, "uploadDate" : { ... }, "md5" : "6b24249b03ea3dd176c5a04f037a658c" }

function toJSON(object $document): string
{
    return MongoDB\BSON\Document::fromPHP($document)->toRelaxedExtendedJSON();
}

下载文件

您可以使用以下方法从GridFS桶中下载文件

• MongoDB\GridFS\Bucket::openDownloadStreamByName() 或 MongoDB\GridFS\Bucket::openDownloadStream()：打开一个新的下载流，从中您可以读取文件内容

• MongoDB\GridFS\Bucket::downloadToStream()：将整个文件写入现有的下载流

$stream = $bucket->openDownloadStreamByName('my_file');
$contents = stream_get_contents($stream);
echo $contents, PHP_EOL;
fclose($stream);

"Data to store"

$stream = $bucket->openDownloadStream(new ObjectId('66e0a5487c880f844c0a32b1'));
$contents = stream_get_contents($stream);
fclose($stream);

$stream = $bucket->openDownloadStreamByName('my_file', ['revision' => 0]);
$contents = stream_get_contents($stream);
fclose($stream);

$file = fopen('/path/to/output_file', 'wb');
$bucket->downloadToStream(
	new ObjectId('66e0a5487c880f844c0a32b1'),
	$file,
);

重命名文件

使用 MongoDB\GridFS\Bucket::rename() 方法来更新您bucket中GridFS文件的名称。您必须通过其 _id 字段而不是文件名来指定要重命名的文件。

以下示例展示了如何通过引用文档的 _id 字段来更新 filename 字段为 'new_file_name'。

$bucket->rename(new ObjectId('66e0a5487c880f844c0a32b1'), 'new_file_name');

删除文件

使用 MongoDB\GridFS\Bucket::delete() 方法从您的bucket中删除文件的集合文档和相关块，从而有效地删除文件。您必须通过其 _id 字段而不是文件名来指定文件。

以下示例展示了如何通过引用 _id 字段来删除文件。

$bucket->delete(new ObjectId('66e0a5487c880f844c0a32b1'));

API 文档

要了解更多关于使用 MongoDB PHP 库存储和检索大文件的信息，请参阅以下 API 文档

• MongoDB\Database::selectGridFSBucket()

• MongoDB\GridFS\Bucket::openUploadStream()

• MongoDB\GridFS\Bucket::uploadFromStream()

• MongoDB\GridFS\Bucket::find()

• MongoDB\GridFS\Bucket::openDownloadStreamByName()

• MongoDB\GridFS\Bucket::openDownloadStream()

• MongoDB\GridFS\Bucket::downloadToStream()

• MongoDB\GridFS\Bucket::rename()

• MongoDB\GridFS\Bucket::delete()