Docs Menu
Docs Home
/ / /
Laravel MongoDB

GridFS Filesystems

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.

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,
]);
},
],
],

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.

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