GridFS

Creating a GridFS Bucket

You can construct a GridFS bucket using the PHP extension's MongoDB\Driver\Manager class, or select a bucket from the MongoDB PHP Library's MongoDB\Database class via the selectGridFSBucket() method.

The bucket can be constructed with various options:

• bucketName determines the prefix for the bucket's metadata and chunk collections. The default value is "fs".

• chunkSizeBytes determines the size of each chunk. GridFS divides the file into chunks of this length, except for the last, which is only as large as needed. The default size is 261120 (i.e. 255 KiB).

• readConcern, readPreference and writeConcern options can be used to specify defaults for read and write operations, much like the MongoDB\Collection options.

Uploading Files with Writable Streams

To upload a file to GridFS using a writable stream, you can either open a stream and write to it directly or write the entire contents of another readable stream to GridFS all at once.

To open an upload stream and write to it:

<?php
$bucket = (new MongoDB\Client)->test->selectGridFSBucket();
$stream = $bucket->openUploadStream('my-file.txt');
$contents = file_get_contents('/path/to/my-file.txt');
fwrite($stream, $contents);
fclose($stream);

To upload the entire contents of a readable stream in one call:

<?php
$bucket = (new MongoDB\Client)->test->selectGridFSBucket();
$file = fopen('/path/to/my-file.txt', 'rb');
$bucket->uploadFromStream('my-file.txt', $file);

Downloading Files with Readable Streams

To download a file from GridFS using a readable stream, you can either open a stream and read from it directly or download the entire file all at once.

To open a download stream and read from it:

<?php
// In practice, $fileId denotes the _id of an existing file in GridFS
$fileId = new MongoDB\BSON\ObjectId;
$bucket = (new MongoDB\Client)->test->selectGridFSBucket();
$stream = $bucket->openDownloadStream($fileId);
$contents = stream_get_contents($stream);

To download the file all at once and write it to a writable stream:

<?php
// In practice, $fileId denotes the _id of an existing file in GridFS
$fileId = new MongoDB\BSON\ObjectId;
$bucket = (new MongoDB\Client)->test->selectGridFSBucket();
$file = fopen('/path/to/my-output-file.txt', 'wb');
$bucket->downloadToStream($fileId, $file);

Selecting Files by Filename and Revision

You can also download a file specified by filename and (optionally) revision number. Revision numbers are used to distinguish between files sharing the same filename metadata field, ordered by date of upload (i.e. the uploadDate metadata field). The revision option accepted by openDownloadStreamByName() and downloadToStreamByName() can be positive or negative.

A positive revision number may be used to select files in order of the oldest upload date. A revision of 0 would denote the file with the oldest upload date, a revision of 1 would denote the second oldest upload, and so on.

A negative revision may be used to select files in order of the most recent upload date. A revision of -1 would denote a file with the most recent upload date, a revision of -2 would denote the second most recent upload, and so on. The revision option defaults to -1 if not specified.

The following example downloads the contents of the oldest version of a particular file:

<?php
$bucket = (new MongoDB\Client)->test->selectGridFSBucket();
$stream = $bucket->openDownloadStreamByName('my-file.txt', ['revision' => 0]);
$contents = stream_get_contents($stream);

Deleting Files

You can delete a GridFS file by its _id.

<?php
// In practice, $fileId denotes the _id of an existing file in GridFS
$fileId = new MongoDB\BSON\ObjectId;
$bucket = (new MongoDB\Client)->test->selectGridFSBucket();
$bucket->delete($fileId);

Finding File Metadata

The find() method allows you to retrieve documents from the GridFS files collection, which contain metadata about the GridFS files.

<?php
$bucket = (new MongoDB\Client)->test->selectGridFSBucket();
$cursor = $bucket->find(['filename' => 'my-file.txt']);

Accessing File Metadata for an Existing Stream

The getFileDocumentForStream() method may be used to get the file document for an existing readable or writable GridFS stream.

<?php
// In practice, $fileId denotes the _id of an existing file in GridFS
$fileId = new MongoDB\BSON\ObjectId;
$bucket = (new MongoDB\Client)->test->selectGridFSBucket();
$stream = $bucket->openDownloadStream($fileId);
$metadata = $bucket->getFileDocumentForStream($stream);

The getFileIdForStream() method may be used to get the _id for an existing readable or writable GridFS stream. This is a convenience for accessing the _id property of the object returned by getFileDocumentForStream().

<?php
$bucket = (new MongoDB\Client)->test->selectGridFSBucket();
$stream = $bucket->openDownloadStreamByName('my-file.txt');
$fileId = $bucket->getFileIdForStream($stream);