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