gridfs.txt

======
GridFS
======

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

:manual:`GridFS </core/gridfs>` is a specification for storing and retrieving
files in MongoDB. GridFS uses two collections to store files. One collection
stores the file chunks (e.g. ``fs.chunks``), and the other stores file metadata
(e.g. ``fs.files``). The :phpclass:`MongoDB\\GridFS\\Bucket` class provides an
interface around these collections for working with the files as PHP
:php:`Streams <stream>`.

Creating a GridFS Bucket
------------------------

You can construct a GridFS bucket using the PHP extension's
:php:`MongoDB\\Driver\\Manager <class.mongodb-driver-manager>` class, or select
a bucket from the |php-library|'s :phpclass:`MongoDB\\Database` class via the
:phpmethod:`selectGridFSBucket() <MongoDB\\Database::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
   :phpclass:`MongoDB\\GridFS\\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:

.. code-block:: php

   <?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:

.. code-block:: php

   <?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:

.. code-block:: php

   <?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:

.. code-block:: php

   <?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
:phpmethod:`openDownloadStreamByName()
<MongoDB\\GridFS\\Bucket::openDownloadStreamByName>` and
:phpmethod:`downloadToStreamByName()
<MongoDB\\GridFS\\Bucket::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:

.. code-block:: php

   <?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``.

.. code-block:: php

   <?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 :phpmethod:`find() <MongoDB\\GridFS\\Bucket::find>` method allows you to
retrieve documents from the GridFS files collection, which contain metadata
about the GridFS files.

.. code-block:: php

   <?php

   $bucket = (new MongoDB\Client)->test->selectGridFSBucket();

   $cursor = $bucket->find(['filename' => 'my-file.txt']);

Accessing File Metadata for an Existing Stream
----------------------------------------------

The :phpmethod:`getFileDocumentForStream()
<MongoDB\\GridFS\\Bucket::getFileDocumentForStream>` method may be used to get
the file document for an existing readable or writable GridFS stream.

.. code-block:: php

   <?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);

.. note::

   Since the file document for a writable stream is not committed to MongoDB
   until the stream is closed,
   :phpmethod:`getFileDocumentForStream()
   <MongoDB\\GridFS\\Bucket::getFileDocumentForStream>` can only return an
   in-memory document, which will be missing some fields (e.g. ``length``,
   ``md5``).

The :phpmethod:`getFileIdForStream()
<MongoDB\\GridFS\\Bucket::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
:phpmethod:`getFileDocumentForStream()
<MongoDB\\GridFS\\Bucket::getFileDocumentForStream>`.

.. code-block:: php

   <?php

   $bucket = (new MongoDB\Client)->test->selectGridFSBucket();

   $stream = $bucket->openDownloadStreamByName('my-file.txt');
   $fileId = $bucket->getFileIdForStream($stream);