GridFS Filesystems

Overview

You can use the GridFS Adapter for Flysystem to store large files in MongoDB. GridFS lets you store files of unlimited size in the same database as your data.

Configuration

Before using the GridFS driver, install the Flysystem GridFS package through the Composer package manager by running the following command:

composer require league/flysystem-gridfs

Configure Laravel File Storage to use the gridfs driver in config/filesystems.php:

'disks' => [
    'gridfs' => [
        'driver' => 'gridfs',
        'connection' => 'mongodb',
        // 'database' => null,
        // 'bucket' => 'fs',
        // 'prefix' => '',
        // 'read-only' => false,
        // 'throw' => false,
    ],
],

You can configure the following settings in config/filesystems.php:

Setting	Description
`driver`	Required. Specifies the filesystem driver to use. Must be `gridfs` for MongoDB.
`connection`	Database connection used to store jobs. It must be a `mongodb` connection. The driver uses the default connection if a connection is not specified.
`database`	Name of the MongoDB database for the GridFS bucket. The driver uses the database of the connection if a database is not specified.
`bucket`	Name or instance of the GridFS bucket. A database can contain multiple buckets identified by their name. Defaults to `fs`.
`prefix`	Specifies a prefix for the name of the files that are stored in the bucket. Using a distinct bucket is recommended in order to store the files in a different collection, instead of using a prefix. The prefix should not start with a leading slash (`/`).
`read-only`	If `true`, writing to the GridFS bucket is disabled. Write operations will return `false` or throw exceptions depending on the configuration of `throw`. Defaults to `false`.
`throw`	If `true`, exceptions are thrown when an operation cannot be performed. If `false`, operations return `true` on success and `false` on error. Defaults to `false`.

You can also use a factory or a service name to create an instance of MongoDB\GridFS\Bucket. In this case, the options connection and database are ignored:

use Illuminate\Foundation\Application;
use MongoDB\GridFS\Bucket;
'disks' => [
    'gridfs' => [
        'driver' => 'gridfs',
        'bucket' => static function (Application $app): Bucket {
            return $app['db']->connection('mongodb')
                ->getMongoDB()
                ->selectGridFSBucket([
                    'bucketName' => 'avatars',
                    'chunkSizeBytes' => 261120,
                ]);
        },
    ],
],

Usage

Laravel Filesystem provides a common interface for all the supported file systems. You can use the gridfs disk in the same way as the local disk.

The following example writes a file to the gridfs disk, then reads the file:

$disk = Storage::disk('gridfs');
// Write the file "hello.txt" into GridFS
$disk->put('hello.txt', 'Hello World!');
// Read the file
echo $disk->get('hello.txt'); // Hello World!

To learn more Laravel File Storage, see Laravel File Storage in the Laravel documentation.

Versioning

GridFS creates file documents for each uploaded file. These documents contain metadata, including the file name and a unique ObjectId. If multiple documents share the same file name, they are considered "revisions" and further distinguished by creation timestamps.

The Laravel MongoDB integration uses the GridFS Flysystem adapter. It interacts with file revisions in the following ways:

Reading a file reads the last revision of this file name
Writing a file creates a new revision for this file name
Renaming a file renames all the revisions of this file name
Deleting a file deletes all the revisions of this file name

The GridFS Adapter for Flysystem does not provide access to a specific revision of a file name. You must use the GridFS API if you need to work with revisions, as shown in the following code:

// Create a bucket service from the MongoDB connection
/** @var \MongoDB\GridFS\Bucket $bucket */
$bucket = $app['db']->connection('mongodb')->getMongoDB()->selectGridFSBucket();
// Download the last but one version of a file
$bucket->openDownloadStreamByName('hello.txt', ['revision' => -2])

Note

If you specify the prefix Filesystem setting, you will have to explicitly prepend the file names when using the GridFS API directly.

Back

Transactions

Issues & Help